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

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

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

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

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

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 インスタンスへの接続を理解することです。 管理時のインスタンスへの接続およびインスタンス間の接続の要件は、次のとおりです:

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 を参照してください。 これは、信頼性のある使用のために不可欠です。たとえば、設定が永続化されていない場合、構成の変更が失われるため、再起動後にクラスタに追加されたインスタンスは再結合されません。

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

これらの要件を満たさないインスタンスは、構成変更の永続化を自動的にサポートしておらず、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})

インスタンスの管理に使用されるユーザーアカウントは 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 コールからの最大出力が可能になります。 使用可能な出力レベルは次のとおりです:

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

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

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

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

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

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()