Documentation Home
MySQL Shell 8.0
Download this Manual
PDF (US Ltr) - 1.4Mb
PDF (A4) - 1.4Mb
MySQL Shell 8.0  /  MySQL AdminAPI の使用  /  MySQL AdminAPI

このページは機械翻訳したものです。

6.1 MySQL AdminAPI

このセクションでは、AdminAPI の概要と開始に必要な知識について説明します。

MySQL Shell には、dba グローバル変数とそれに関連付けられたメソッドを介してアクセスする AdminAPI が含まれています。 dba 変数メソッドは、InnoDB クラスタ および InnoDB ReplicaSet のデプロイ、構成および管理を可能にする操作を提供します。 たとえば、dba.createCluster() メソッドを使用して InnoDB クラスタ を作成します。 また、AdminAPI では、InnoDB クラスタ と InnoDB ReplicaSet の統合を可能にするユーザーの作成や更新など、一部の MySQL Router 関連タスクの管理がサポートされています。

MySQL Shell には、ネイティブ SQL モードに加えて、JavaScript および Python のスクリプト言語モードが用意されています。 このガイド全体を通して、MySQL Shell は主に JavaScript モードで使用されます。 MySQL Shell を起動すると、デフォルトで JavaScript モードになります。 JavaScript モードの場合は\js、Python モードの場合は\py を発行して、モードを切り替えます。 \js を発行して、JavaScript モードであることを確認します。

重要

MySQL Shell ではソケット接続を介してサーバーに接続できますが、AdminAPI ではサーバーインスタンスへの TCP 接続が必要です。 ソケットベースの接続は AdminAPI ではサポートされていません。

このセクションでは、MySQL Shell について理解していることを前提としています。詳細は、MySQL Shell 8.0 を参照してください。MySQL Shell では、AdminAPI のオンラインヘルプも提供されます。 使用可能なすべての dba コマンドをリストするには、dba.help() メソッドを使用します。 特定の方法のオンラインヘルプを参照するには、一般的な形式の object.help('methodname') を使用します。 例: 

mysql-js> dba.help('getCluster')

Retrieves a cluster from the Metadata Store.

SYNTAX

  dba.getCluster([name][, options])

WHERE

  name: Parameter to specify the name of the cluster to be returned.
  options: Dictionary with additional options.

>trimmed for brevity<

このドキュメントに加えて、MySQL Shell JavaScript API リファレンスまたは MySQL Shell Python API リファレンス (「コネクタおよび API」から入手可能) のすべての AdminAPI メソッドの開発者用ドキュメントがあります。

このセクションは、InnoDB クラスタ または InnoDB ReplicaSet の使用に適用され、次のもので構成されます:

デプロイメントシナリオ

AdminAPI では、次のデプロイメントシナリオがサポートされます:

  • 本番デプロイメント: 完全な本番環境を使用する場合は、必要な数のマシンを構成してから、サーバーインスタンスをマシンにデプロイする必要があります。

  • サンドボックスのデプロイメント: 完全本番デプロイメントにコミットする前にデプロイメントをテストする場合、提供されているサンドボックス機能を使用すると、ローカルマシンにテスト環境をすばやく設定できます。 サンドボックスサーバーインスタンスは必要な構成で作成され、採用されているテクノロジを試すことができます。

    重要

    サンドボックスデプロイメントは、完全本番環境での使用には適していません。

コンポーネントのインストール

AdminAPI に必要なソフトウェアコンポーネントのインストール方法は、使用するデプロイメントのタイプによって異なります。 本番デプロイメントの場合は、各マシンにコンポーネントをインストールします。 本番デプロイメントでは、MySQL サーバーインスタンスを実行している複数のリモートホストマシンを使用するため、コンポーネントのインストールなどのタスクを実行するには、SSH や Windows リモートデスクトップなどのツールを使用して各マシンに接続する必要があります。 サンドボックスデプロイメントの場合は、コンポーネントを単一のマシンにインストールします。 サンドボックスデプロイメントは単一のマシンに対してローカルであるため、インストールはローカルマシンで一度のみ実行する必要があります。 次のインストール方法を使用できます:

次のドキュメントを使用して、コンポーネントをダウンロードおよびインストールします:

重要

一致するバージョンのコンポーネントを常に使用します。たとえば、MySQL Router 8.0.29 とともに MySQL 8.0.29 を実行するインスタンスを管理するには、MySQL Shell 8.0.29 を実行します。

必要なソフトウェアをインストールしたら、セクション6.2「MySQL InnoDB クラスタ」 または セクション6.3「MySQL InnoDB ReplicaSet」 のどちらに従うかを選択します。

ホスト名の構成

本番デプロイメントでは、使用するインスタンスは個別のマシンで実行されるため、各マシンには一意のホスト名が必要であり、サーバーインスタンスを実行する他のマシンのホスト名を解決できる必要があります。 そうでない場合は、次のことができます:

  • 各マシンを構成して、相互の IP をホスト名にマップします。 詳細は、オペレーティングシステムのドキュメントを参照してください。 これは推奨される解決策です。

  • DNS サービスの設定

  • 各インスタンスの MySQL 構成の report_host 変数を、適切な外部から到達可能なアドレスに構成

AdminAPI では、ホスト名のかわりに IP アドレスを使用できます。 MySQL Shell 8.0.18 から、ターゲット MySQL Server のバージョンが 8.0.13 より高い場合、AdminAPI は IPv6 アドレスをサポートします。 MySQL Shell 8.0.18 以上を使用している場合、すべてのクラスタインスタンスで 8.0.14 以上が実行されていると、IPv6 またはホスト名を使用して、インスタンス接続文字列および localAddress、groupSeeds、ipAllowlist などのオプションを指定して IPv6 アドレスに解決できます。 IPv6 の使用の詳細は、IPv6 および IPv6 と IPv4 の混合グループのサポート を参照してください。 以前のバージョンでは、IPv4 アドレスのみサポートされていました。

MySQL サーバーのホスト名が正しく構成されているかどうかを確認するには、次のクエリーを実行して、インスタンスが他のサーバーに自身のアドレスをレポートする方法を確認し、返されたアドレスを使用して他のホストからその MySQL サーバーへの接続を試行します: 

SELECT coalesce(@@report_host, @@hostname);

インスタンスの指定

AdminAPI を使用するコア概念の 1 つは、InnoDB クラスタ または InnoDB ReplicaSet を構成する MySQL インスタンスへの接続を理解することです。 管理時のインスタンスへの接続およびインスタンス間の接続の要件は、次のとおりです:

  • TCP/IP 接続のみがサポートされ、Unix ソケットまたは名前付きパイプの使用はサポートされていません。InnoDB クラスタ および InnoDB ReplicaSet は、広域ネットワーク上で実行されているローカルエリアネットワークでの使用を目的としていますが、お薦めしません。

  • クラシック MySQL プロトコル 接続のみがサポートされており、X プロトコル はサポートされていません。

    ヒント

    アプリケーションで X プロトコル を使用できます。この要件は、AdminAPI を使用した管理操作用です。

MySQL Shell を使用すると、様々な API を操作でき、URI 類似文字列またはキーと値のペアを使用したサーバーへの接続 で説明されているように接続の指定がサポートされます。 URI のような文字列またはキーと値のペアを使用して接続を指定できます。 追加の接続パラメータ は AdminAPI ではサポートされていません。 このドキュメントでは、URI のような接続文字列を使用した AdminAPI を示します。 たとえば、ユーザー myuser として www.example.com の MySQL サーバーインスタンスに接続するには、3306 のポートで接続文字列を使用します: 

myuser@www.example.com:3306

この接続文字列を dba.configureInstance() などの AdminAPI 操作で使用するには、接続文字列を一重引用符 (') または二重引用符 (\") で囲むなどして、接続文字列を文字列として解釈する必要があります。 AdminAPI の JavaScript 実装を使用している場合には、次のコマンドを発行します: 

MySQL JS > dba.configureInstance('myuser@www.example.com:3306')

MySQL Shell をデフォルトの対話モードで実行している場合は、パスワードの入力を求められます。AdminAPI では MySQL Shell セクション4.4「プラガブルパスワードストア」 がサポートされており、インスタンスへの接続に使用したパスワードを格納すると、プロンプトは表示されなくなります。

設定の永続化

InnoDB クラスタ、InnoDB ReplicaSet およびそのサーバーインスタンスを操作するために使用する AdminAPI コマンドによって、インスタンス上の MySQL の構成が変更されます。 MySQL Shell のインスタンスへの接続方法およびインスタンスにインストールされている MySQL のバージョンに応じて、これらの構成変更をインスタンスに自動的に永続化できます。 インスタンスに設定を永続化すると、インスタンスの再起動後に構成の変更が保持されます。バックグラウンド情報は、SET PERSIST を参照してください。 これは、信頼性のある使用のために不可欠です。たとえば、設定が永続化されていない場合、構成の変更が失われるため、再起動後にクラスタに追加されたインスタンスは再結合されません。

次の要件を満たすインスタンスでは、構成変更の永続化が自動的にサポートされます:

  • インスタンスで MySQL バージョン 8.0.11 以上が実行されている

  • persisted_globals_load が ON に設定されている

  • インスタンスが --no-defaults オプションで起動されていません

これらの要件を満たさないインスタンスは、構成変更の永続化を自動的にサポートしておらず、AdminAPI 操作によってインスタンス設定の変更が永続化されると、次のような警告が表示されます: 

WARNING: On instance 'localhost:3320' membership change cannot be persisted since MySQL version 5.7.21
does not support the SET PERSIST command (MySQL version >= 8.0.5 required). Please use the
<Dba>.configureLocalInstance command locally to persist the changes.

MySQL Shell が現在実行されている MySQL インスタンス (つまり、ローカルインスタンス) に対して AdminAPI コマンドが発行されると、MySQL Shell は構成の変更をインスタンスに直接保持します。 構成変更の自動永続化をサポートするローカルインスタンスでは、構成変更はインスタンス mysqld-auto.cnf ファイルに永続化され、構成変更にそれ以上のステップは必要ありません。 構成変更の自動永続化をサポートしていないローカルインスタンスでは、変更をローカルで行う必要があります。dba.configureLocalInstance() でのインスタンスの構成 を参照してください。

リモートインスタンス (つまり、MySQL Shell が現在実行されているインスタンス以外のインスタンス) に対して実行する場合、インスタンスが構成変更の永続化を自動的にサポートしている場合、AdminAPI コマンドは、インスタンスの mysql-auto.conf オプションファイルに対する構成変更を永続化します。 リモートインスタンスが構成変更の永続化を自動的にサポートしていない場合、AdminAPI コマンドはインスタンスオプションファイルを自動的に構成できません。 つまり、AdminAPI コマンドは、現在の構成を表示するためなど、インスタンスから情報を読み取ることができますが、構成への変更をインスタンスオプションファイルに永続化することはできません。 この場合、変更をローカルに永続化する必要があります。dba.configureLocalInstance() でのインスタンスの構成 を参照してください。

ハンドラオブジェクトの取得

AdminAPI を使用している場合、InnoDB クラスタ または InnoDB ReplicaSet を表すハンドラオブジェクトを使用します。 このオブジェクトを変数に割り当て、使用可能な操作を使用して InnoDB クラスタ または InnoDB ReplicaSet を監視および管理します。 ハンドラオブジェクトを取得できるようにするには、InnoDB クラスタ または InnoDB ReplicaSet に属するいずれかのインスタンスへの接続を確立します。 たとえば、dba.createCluster() を使用してクラスタを作成する場合、この操作は変数に割り当てることができる Cluster オブジェクトを返します。 このオブジェクトを使用して、インスタンスの追加やクラスタステータスの確認など、クラスタを操作します。 MySQL Shell の再起動後など、後日クラスタを再度取得する場合は、dba.getCluster([name],[options]) 関数を使用します。 例: 

mysql-js> var cluster1 = dba.getCluster()

同様に、dba.getReplicaSet() 操作を使用して InnoDB ReplicaSet を取得します。 例: 

mysql-js> var replicaset1 = dba.getReplicaSet()

name を指定しない場合、デフォルトオブジェクトが返されます。 デフォルトでは、MySQL Shell はハンドラの取得時にプライマリインスタンスへの接続を試行します。 この動作を構成するには、connectToPrimary オプションを設定します。 connectToPrimary が true で、アクティブなグローバル MySQL Shell セッションがプライマリインスタンスに対するものでない場合、MySQL Shell はプライマリインスタンスに対するクエリーを実行します。 クラスタにクォーラムがない場合、操作は失敗します。 connectToPrimary が false の場合、取得されたオブジェクトはアクティブセッション、つまり MySQL Shell の現在のグローバルセッションと同じインスタンスを使用します。 connectToPrimary が指定されていない場合、MySQL Shell は connectToPrimary を true として扱い、false である connectToPrimary にフォールバックします。

セカンダリに強制的に接続するには、セカンダリインスタンスへの接続を確立し、次を発行して connectToPrimary オプションを使用します: 

mysql-js> shell.connect(secondary_member)
mysql-js> var cluster1 = dba.getCluster(testCluster, {connectToPrimary:false})
ヒント

セカンダリインスタンスには super_read_only=ON があるため、変更を書き込むことはできません。

管理用のユーザーアカウントの作成

インスタンスの管理に使用されるユーザーアカウントは root アカウントである必要はありませんが、完全な MySQL 管理者権限 (SUPER, GRANT OPTION, CREATE, DROP など) に加えて、メタデータテーブルに対する完全な読取りおよび書込み権限がユーザーに割り当てられている必要があります。 この手順では、ユーザー icadmin を InnoDB クラスタ の例に、rsadmin を InnoDB ReplicaSet の例に示します。

重要

管理者のユーザー名とパスワードは、すべてのインスタンスで同じである必要があります。

8.0.20 以降のバージョンでは、setupAdminAccount(user) 操作を使用して、InnoDB クラスタ または InnoDB ReplicaSet の管理に必要な権限を持つ MySQL ユーザーアカウントを作成またはアップグレードします。 setupAdminAccount() 操作を使用するには、root などのユーザーを作成する権限を持つ MySQL ユーザーとして接続する必要があります。 setupAdminAccount(user) 操作では、dba.upgradeMetadata() 操作の前に、必要な権限を持つ既存の MySQL アカウントをアップグレードすることもできます。

必須の user 引数は、アカウントの管理に使用するために作成またはアップグレードする MySQL アカウントの名前です。 setupAdminAccount() 操作で受け入れられるユーザー名の形式は、標準の MySQL アカウント名の形式に従います。アカウント名の指定 を参照してください。 ユーザー引数の形式は username[@host]です。ここで、host はオプションであり、指定しない場合は % ワイルドカード文字にデフォルト設定されます。

たとえば、変数 myCluster に割り当てられた InnoDB クラスタ を管理する icadmin という名前のユーザーを作成するには、次のように発行します: 

mysql-js> myCluster.setupAdminAccount('icadmin')

Missing the password for new account icadmin@%. Please provide one.
Password for new account: ********
Confirm password: ********

Creating user icadmin@%.
Setting user password.
Account icadmin@% was successfully created.

たとえば、8.0.20 より前のバージョンで作成された管理ユーザーがすでに存在する場合は、setupAdminAccount() 操作で update オプションを使用して、既存のユーザーの権限をアップグレードします。 これは、管理ユーザーに互換性を持たせるために、アップグレード時に関連します。 たとえば、icadmin issue という名前のユーザーをアップグレードするには、次のようにします: 

mysql-js> myCluster.setupAdminAccount('icadmin', {'update':1})
Updating user icadmin@%.
Account icadmin@% was successfully updated.

8.0.20 より前のバージョンでは、管理用のユーザーを作成するには、dba.configureInstance() 操作で clusterAdmin オプションを使用することをお薦めします。 clusterAdmin オプションは、適切な権限を持つユーザーを作成する権限を持つユーザーに基づく MySQL Shell 接続で使用する必要があります。この例では、root ユーザーが使用されます。 例: 

mysql-js> dba.configureInstance('root@ic-1:3306', {clusterAdmin: "'icadmin'@'ic-1%'"});

setupAdminAccount() 操作および clusterAdmin オプションで受け入れられるユーザー名の形式は、標準の MySQL アカウント名形式に従います。アカウント名の指定 を参照してください。

読取り操作のみが必要な場合 (監視目的など)、より制限された権限を持つアカウントを使用できます。 AdminAPI のユーザーの構成を参照してください。

詳細ロギング

本番デプロイメントを使用する場合は、MySQL Shell の冗長ロギングを構成すると便利です。 たとえば、ログ内の情報は、InnoDB クラスタ の一部として機能するようにサーバーインスタンスを準備する際に発生する可能性のある問題を見つけて解決するのに役立ちます。 冗長ロギングレベルで MySQL Shell を起動するには、--log-level オプションを使用します: 

shell> mysqlsh --log-level=DEBUG3

DEBUG3 レベルをお薦めします。詳細は、--log-level を参照してください。 DEBUG3 が設定されている場合、MySQL Shell ログファイルには、各 AdminAPI コールの一部として実行される SQL クエリーを含む Debug: execute_sql( ... ) などの行が含まれます。 MySQL Shell によって生成されるログファイルは、Unix ベースのシステムの場合は ~/.mysqlsh/mysqlsh.log にあり、Microsoft Windows システムの場合は %APPDATA%\MySQL\mysqlsh\mysqlsh.log にあります。 詳しくは第9章「MySQL Shell のロギングおよびデバッグ」をご覧ください。

MySQL Shell ログレベルの有効化に加えて、各コマンドの発行後に AdminAPI が MySQL Shell で提供する出力量を構成できます。 AdminAPI 出力の量を有効にするには、MySQL Shell で次のコマンドを発行します: 

mysql-js> dba.verbose=2

これにより、AdminAPI コールからの最大出力が可能になります。 使用可能な出力レベルは次のとおりです:

  • デフォルトは 0 または OFF です。 これは最小限の出力を提供し、トラブルシューティングを行わない場合に推奨されるレベルです。

  • 1 または ON を指定すると、各コールから AdminAPI に冗長出力が追加されます。

  • 2 は、AdminAPI への各コールの実行内容に関する完全な情報を提供するデバッグ出力を冗長出力に追加します。

MySQL Shell では、オプションで、AdminAPI 操作で使用される SQL ステートメントをログに記録でき (サンドボックス操作を除く)、実行時に端末に表示することもできます。 これを行うように MySQL Shell を構成するには、セクション9.3「AdminAPI 操作のロギング」 を参照してください。

プライマリの検索

単一プライマリ InnoDB クラスタ または InnoDB ReplicaSet を使用している場合は、構成の変更をメタデータに書き込むことができるように、管理タスクのためにプライマリインスタンスに接続する必要があります。 現在のプライマリを検索するには、次の手順を実行します:

  • MySQL Shell の起動時に --redirect-primary オプションを使用して、ターゲットサーバーが InnoDB クラスタ または InnoDB ReplicaSet の一部であることを確認します。 ターゲットインスタンスがプライマリでない場合、MySQL Shell はプライマリを検索してそれに接続します。

  • ターゲットインスタンスがクラスタまたは ReplicaSet に属しているかどうかをチェックする shell.connectToPrimary([instance, password]) 操作 (バージョン 8.0.20 で追加) を使用します。 その場合、MySQL Shell はプライマリに対して新しいセッションを開き、アクティブなグローバル MySQL Shell セッションを確立されたセッションに設定して戻します。

    instance が指定されていない場合、操作はアクティブなグローバル MySQL Shell セッションの使用を試みます。 instance が指定されておらず、アクティブなグローバル MySQL Shell セッションがない場合は、例外がスローされます。 ターゲットインスタンスがクラスタまたは ReplicaSet に属していない場合、操作はエラーで失敗します。

  • ステータス操作を使用して、結果でプライマリを検索し、そのインスタンスに手動で接続します。

スクリプト AdminAPI

このセクションに示す対話型モードに加えて、MySQL Shell では batch mode でのスクリプトの実行がサポートされています。 これにより、MySQL Shell --file オプションを使用して実行できる JavaScript または Python で記述されたスクリプトを使用して、AdminAPI を使用したプロセスを自動化できます。 例: 

shell> mysqlsh --file setup-innodb-cluster.js
注記

スクリプトファイル名の後に指定されたコマンドラインオプションは、MySQL Shell ではなくスクリプトに渡されます。 これらのオプションには、JavaScript の os.argv 配列または Python の sys.argv 配列を使用してアクセスできます。 どちらの場合も、配列で最初に選択されるオプションはスクリプト名です。

スクリプトファイルの例の内容を次に示します: 

print('InnoDB クラスタ sandbox set up\n');
print('==================================\n');
print('Setting up a MySQL InnoDB Cluster with 3 MySQL Server sandbox instances,\n');
print('installed in ~/mysql-sandboxes, running on ports 3310, 3320 and 3330.\n\n');

var dbPass = shell.prompt('Please enter a password for the MySQL root account: ', {type:"password"});

try {
   print('\nDeploying the sandbox instances.');
   dba.deploySandboxInstance(3310, {password: dbPass});
   print('.');
   dba.deploySandboxInstance(3320, {password: dbPass});
   print('.');
   dba.deploySandboxInstance(3330, {password: dbPass});
   print('.\nSandbox instances deployed successfully.\n\n');

   print('Setting up InnoDB Cluster...\n');
   shell.connect('root@localhost:3310', dbPass);

   var cluster = dba.createCluster("prodCluster");

   print('Adding instances to the Cluster.');
   cluster.addInstance({user: "root", host: "localhost", port: 3320, password: dbPass});
   print('.');
   cluster.addInstance({user: "root", host: "localhost", port: 3330, password: dbPass});
   print('.\nInstances successfully added to the Cluster.');

   print('\nInnoDB Cluster deployed successfully.\n');
} catch(e) {
   print('\nThe InnoDB Cluster could not be created.\n\nError: ' +
   + e.message + '\n');
}

AdminAPI は、MySQL Shell セクション5.8「API コマンドラインインタフェース」 でもサポートされます。 これにより、AdminAPI を環境に簡単に統合できます。 たとえば、ポート 1234 でリスニングしているサンドボックスインスタンスを使用して InnoDB クラスタ のステータスを確認するには、次のようにします: 

$ mysqlsh root@localhost:1234 -- cluster status

これは、MySQL Shell の同等のコマンドにマップされます: 

mysql-js> cluster.status()

PREV   HOME   UP   NEXT
Download this Manual
PDF (US Ltr) - 1.4Mb
PDF (A4) - 1.4Mb