13.4.2.1 CHANGE MASTER TO 構文

CHANGE MASTER TO option [, option] ...

option:
    MASTER_BIND = 'interface_name'
  | MASTER_HOST = 'host_name'
  | MASTER_USER = 'user_name'
  | MASTER_PASSWORD = 'password'
  | MASTER_PORT = port_num
  | MASTER_CONNECT_RETRY = interval
  | MASTER_RETRY_COUNT = count
  | MASTER_DELAY = interval
  | MASTER_HEARTBEAT_PERIOD = interval
  | MASTER_LOG_FILE = 'master_log_name'
  | MASTER_LOG_POS = master_log_pos
  | MASTER_AUTO_POSITION = {0|1}
  | RELAY_LOG_FILE = 'relay_log_name'
  | RELAY_LOG_POS = relay_log_pos
  | MASTER_SSL = {0|1}
  | MASTER_SSL_CA = 'ca_file_name'
  | MASTER_SSL_CAPATH = 'ca_directory_name'
  | MASTER_SSL_CERT = 'cert_file_name'
  | MASTER_SSL_CRL = 'crl_file_name'
  | MASTER_SSL_CRLPATH = 'crl_directory_name'
  | MASTER_SSL_KEY = 'key_file_name'
  | MASTER_SSL_CIPHER = 'cipher_list'
  | MASTER_SSL_VERIFY_SERVER_CERT = {0|1}
  | IGNORE_SERVER_IDS = (server_id_list)

server_id_list:
    [server_id [, server_id] ... ]

CHANGE MASTER TO は、スレーブサーバーがマスターサーバーへの接続、マスターバイナリログの読み取り、およびスレーブリレーログの読み取りに使用するパラメータを変更します。また、マスター情報およびリレーログ情報リポジトリの内容も更新します (セクション17.2.2「レプリケーションリレーおよびステータスログ」を参照してください)。CHANGE MASTER TO を使用するには、スレーブレプリケーションスレッドを停止する必要があります (必要に応じて STOP SLAVE を使用します)。MySQL 5.6.11 以降では、gtid_next も AUTOMATIC に設定する必要があります (Bug #16062608)。

次の説明に示されているものを除き、指定されていないオプションはその値を保持します。そのため、ほとんどの場合、変更されないオプションを指定する必要はありません。たとえば、MySQL マスターに接続するためのパスワードが変更された場合は、新しいパスワードについてスレーブに通知するために次のステートメントを発行するだけで済みます。

STOP SLAVE; -- if replication was running
CHANGE MASTER TO MASTER_PASSWORD='new3cret';
START SLAVE; -- if you want to restart replication

MASTER_HOST、MASTER_USER、MASTER_PASSWORD、および MASTER_PORT はスレーブに、そのマスターに接続する方法に関する情報を提供します。

• MASTER_HOST と MASTER_PORT は、マスターホストのホスト名 (または IP アドレス) とその TCP/IP ポートです。

  注記

  レプリケーションでは、Unix ソケットファイルを使用できません。また、TCP/IP を使用してマスター MySQL サーバーに接続できる必要があります。

  MASTER_HOST または MASTER_PORT オプションを指定すると、スレーブは (そのオプション値が現在の値と同じ場合でも) マスターサーバーが以前とは異なっていると見なします。この場合、マスターバイナリログファイルの名前と位置の古い値は適用されなくなったと見なされるため、このステートメントで MASTER_LOG_FILE と MASTER_LOG_POS を指定しないと、そのあとに MASTER_LOG_FILE='' と MASTER_LOG_POS=4 が暗黙のうちに付加されます。

  MASTER_HOST='' を設定する (つまり、その値を明示的に空の文字列に設定する) ことは、MASTER_HOST をまったく設定しないことと同じではありません。MySQL 5.5 からは、MASTER_HOST を空の文字列に設定しようとするとエラーで失敗します。以前は、MASTER_HOST を空の文字列に設定すると、そのあとの START SLAVE が失敗しました。(Bug #28796)

  MySQL 5.6.5 以降では、MASTER_HOST やその他の CHANGE MASTER TO オプションに使用されている値にラインフィード (\n または 0x0A) 文字が含まれていないかがチェックされます。このような文字がこれらの値に含まれていると、ステートメントが ER_MASTER_INFO で失敗します。(Bug #11758581、Bug #50801)

• MASTER_USER と MASTER_PASSWORD は、マスターへの接続に使用するアカウントのユーザー名とパスワードです。

  MySQL 5.6.4 以降では、MASTER_USER を空にすることはできません。MASTER_PASSWORD の値を設定するときに MASTER_USER = '' を設定するか、または未設定のままにするとエラーが発生します (Bug #13427949)。

  CHANGE MASTER TO ステートメントで MySQL レプリケーションスレーブアカウントに使用されるパスワードは、長さが 32 文字に制限されます。パスワードがこれより長い場合、このステートメントは成功しますが、超過した文字はすべて暗黙のうちに切り捨てられます。これは MySQL レプリケーションに固有の問題であり、MySQL 5.7 で修正されています。(Bug #11752299、Bug #43439)

  実行中の CHANGE MASTER TO ステートメントのテキスト (MASTER_USER と MASTER_PASSWORD の値を含む) は、並列 SHOW PROCESSLIST ステートメントの出力で確認できます。(SHOW PROCESSLIST には START SLAVE ステートメントの完全なテキストも表示されます。)

MASTER_SSL_xxx オプションは、接続での SSL の使用に関する情報を提供します。これらは、セクション6.3.10.4「SSL コマンドのオプション」およびセクション17.3.7「SSL を使用してレプリケーションをセットアップする」で説明されている --ssl-xxx オプションに対応します。これらのオプションは、SSL サポートなしでコンパイルされたスレーブ上でも変更できます。これらはマスター情報リポジトリに保存されますが、スレーブで SSL サポートが有効になっていない場合は無視されます。MASTER_SSL_CRL と MASTER_SSL_CRLPATH は MySQL 5.6.3 で追加されました。

MASTER_CONNECT_RETRY は、接続再試行の間で待機する秒数を指定します。デフォルトは 60 です。

MASTER_RETRY_COUNT (MySQL 5.6.1 で追加されました) は、再接続の試行の回数を制限し、SHOW SLAVE STATUS (これも MySQL 5.6.1 で追加されました) の出力内の Master_Retry_Count カラムの値を更新します。デフォルト値は 24 * 3600 = 86400 です。MASTER_RETRY_COUNT は古い --master-retry-count サーバーオプションの置き換えを目的にしており、現在ではこの制限を設定するための推奨される方法です。新しいアプリケーションでは --master-retry-count に依存しないようにするとともに、以前のバージョンの MySQL から MySQL 5.6.1 以降にアップグレードする場合は、これに依存する既存のすべてのアプリケーションを、代わりに CHANGE MASTER TO ... MASTER_RETRY_COUNT を使用するように更新することをお勧めします。

MASTER_DELAY は、スレーブがマスターから遅延する必要がある秒数を指定します。マスターから受信されたイベントは、そのマスター上での実行より少なくとも interval 秒あとになるまで実行されません。デフォルトは 0 です。interval が 0 から 2³¹-1 までの範囲の負ではない整数でない場合は、エラーが発生します。詳細は、セクション17.3.9「遅延レプリケーション」を参照してください。このオプションは MySQL 5.6.0 で追加されました。

MASTER_BIND は、複数のネットワークインタフェースを備えたレプリケーションスレーブ上で使用されることを目的にしており、マスターへの接続にそのスレーブのどのネットワークインタフェースが選択されるかを決定します。

このオプションを使用して構成されたアドレス (存在する場合) は、SHOW SLAVE STATUS からの出力の Master_Bind カラムで確認できます。スレーブステータスログテーブルを使用している (サーバーを --master-info-repository=TABLE で起動している) 場合、この値はまた、mysql.slave_master_info テーブルの Master_bind カラムとしても確認できます。

レプリケーションスレーブを特定のネットワークインタフェースにバインドする機能は、MySQL 5.6.2 で追加されました。これはまた、MySQL Cluster NDB 7.3.1 以降でもサポートされています。

MASTER_HEARTBEAT_PERIOD は、レプリケーションハートビートの間の間隔 (秒単位) を設定します。イベントによってマスターのバイナリログが更新されると常に、次のハートビートの待機中の期間がリセットされます。interval は、0 から 4294967 秒までの範囲とミリ秒単位の分解能を持つ 10 進数値です。0 以外の最小の値は 0.001 です。ハートビートがマスターによって送信されるのは、バイナリログファイル内に未送信のイベントが interval より長い期間にわたって存在しない場合だけです。

マスター接続情報をテーブルにロギングしている場合、MASTER_HEARTBEAT_PERIOD は、mysql.slave_master_info テーブルの Heartbeat カラムの値として確認できます。

interval を 0 に設定すると、ハートビートが完全に無効になります。interval のデフォルト値は、slave_net_timeout を 2 で割った値に等しくなります。

@@GLOBAL.slave_net_timeout を現在のハートビート間隔より小さい値に設定すると、警告が発行されます。ハートビート間隔に対して RESET SLAVE を発行する効果は、その間隔のデフォルト値へのリセットです。

MASTER_LOG_FILE と MASTER_LOG_POS は、スレーブ I/O スレッドが、次回そのスレッドが起動されたときにマスターからの読み取りを開始すべき座標です。RELAY_LOG_FILE と RELAY_LOG_POS は、スレーブ SQL スレッドが、次回そのスレッドが起動されたときにリレーログからの読み取りを開始すべき座標です。MASTER_LOG_FILE または MASTER_LOG_POS のどちらかを指定する場合は、RELAY_LOG_FILE や RELAY_LOG_POS を指定できません。MySQL 5.6.5 以降では、MASTER_LOG_FILE または MASTER_LOG_POS のどちらかを指定する場合は、MASTER_AUTO_POSITION = 1 (このセクションのあとの方で説明されています) も指定できません。MASTER_LOG_FILE と MASTER_LOG_POS のどちらも指定されていない場合、スレーブは、CHANGE MASTER TO が発行される前のスレーブ SQL スレッドの最後の座標を使用します。これにより、たとえば、単に使用するパスワードだけを変更する場合、スレーブ SQL スレッドがスレーブ I/O スレッドに比べて遅くなったとしても、レプリケーションに不連続性が発生しないことが保証されます。

MASTER_AUTO_POSITION は、MySQL 5.6.5 で追加されました。MASTER_AUTO_POSITION = 1 が CHANGE MASTER TO とともに使用された場合、スレーブは、GTID ベースのレプリケーションプロトコルを使用してマスターに接続しようとします。

GTID を使用している場合、スレーブは、どのトランザクションの受信または実行、あるいはその両方をすでに行なっているかをマスターに通知します。このセットを計算するために、スレーブは、gtid_executed のグローバル値と SHOW SLAVE STATUS からの Retrieved_gtid_set カラムの値を読み取ります。Retrieved_gtid_set には最後に転送されたトランザクションの GTID が、そのトランザクションが部分的にしか転送されなかった場合でも含まれているため、最後に受信された GTID はこのセットから除かれます。そのため、スレーブは次のセットを計算します。

UNION(@@GLOBAL.gtid_executed, Retrieved_gtid_set - last_received_GTID)

このセットは初期ハンドシェークの一部としてマスターに送信され、マスターは実行したうちの、そのセットに含まれていないすべてのトランザクションを戻します。これらのトランザクションのいずれかがすでにマスターのバイナリログからパージされている場合は、マスターからスレーブにエラー ER_MASTER_HAS_PURGED_REQUIRED_GTIDS が送信され、レプリケーションは開始されません。

GTID ベースのレプリケーションが使用されている場合、MASTER_LOG_FILE と MASTER_LOG_POS によって表された座標は使用されず、代わりにグローバルトランザクション識別子が使用されます。そのため、これらのオプションのどちらかまたは両方を MASTER_AUTO_POSITION とともに使用するとエラーが発生します。

MySQL 5.6.10 からは、SHOW SLAVE STATUS の出力をチェックすることによって、自動ポジショニングが有効な状態でレプリケーションが実行されているかどうかを確認できます。(Bug #15992220)

CHANGE MASTER TO ... MASTER_AUTO_POSITION = 1 を発行する前に、gtid_mode も有効にする必要があります。そうしないと、このステートメントはエラーで失敗します。

GTID を使用したあとに古いファイルベースのレプリケーションプロトコルに戻すには、MASTER_LOG_FILE または MASTER_LOG_POSITION のうちの少なくとも 1 つだけでなく、MASTER_AUTO_POSITION = 0 を指定する新しい CHANGE MASTER TO ステートメントを発行できます。

CHANGE MASTER TO は、RELAY_LOG_FILE または RELAY_LOG_POS が指定されていないかぎり、すべてのリレーログファイルを削除し、新しいリレーログファイルを開始します。指定されている場合、リレーログファイルは保持され、relay_log_purge グローバル変数は暗黙のうちに 0 に設定されます。

MySQL 5.6.2 より前は、RELAY_LOG_FILE には絶対パスが必要でした。MySQL 5.6.2 からは、パスを相対パスにすることができます。その場合は、スレーブのデータディレクトリを基準にしていると見なされます。(Bug #12190)

IGNORE_SERVER_IDS は、0 個以上のサーバー ID のカンマ区切りリストを受け取ります。対応するサーバーから発信されているイベントは、引き続リレーログ内に記録されるログのローテーションおよび削除イベントを除いて無視されます。

循環レプリケーションでは、発信元のサーバーは通常、独自のイベントのターミネータとして機能するため、これらのイベントが複数回適用されることはありません。そのため、このオプションは、循環内のいずれかのサーバーが削除されたときの循環レプリケーションで役立ちます。1、2、3、および 4 のサーバー ID を持つ 4 台のサーバーを含む循環レプリケーションセットアップが存在するとき、サーバー 3 に障害が発生したとします。サーバー 2 からサーバー 4 へのレプリケーションを開始してこのギャップをブリッジする場合、サーバー 4 上で発行する CHANGE MASTER TO ステートメント内に IGNORE_SERVER_IDS = (3) を含めることにより、サーバー 4 にそのマスターとしてサーバー 3 の代わりにサーバー 2 を使用するよう指示できます。それにより、サーバー 4 は、使用されなくなっているサーバーで発信されたすべてのステートメントを無視し、伝播しなくなります。

CHANGE MASTER TO ステートメントが IGNORE_SERVER_IDS オプションなしで発行された場合は、既存のリストがすべて保持されます。無視されるサーバーのリストをクリアするには、このオプションを空のリストとともに使用する必要があります。

CHANGE MASTER TO IGNORE_SERVER_IDS = ();

RESET SLAVE ALL は、サーバー ID リストには影響を与えません。この問題は MySQL 5.7 で修正されています。(Bug #18816897)

IGNORE_SERVER_IDS にサーバーの独自の ID が含まれているときに、--replicate-same-server-id オプションが有効な状態でそのサーバーが起動された場合は、エラーが発生します。

MySQL 5.6 では、マスター情報リポジトリおよび SHOW SLAVE STATUS の出力によって、現在無視されているサーバーのリストが提供されます。詳細は、セクション17.2.2.2「スレーブステータスログ」およびセクション13.7.5.35「SHOW SLAVE STATUS 構文」を参照してください。

MySQL 5.6 では、CHANGE MASTER TO を呼び出すと、MASTER_HOST、MASTER_PORT、MASTER_LOG_FILE、および MASTER_LOG_POS の以前の値が、実行の前のスレーブの状態に関するその他の情報とともにエラーログに書き込まれます。

MySQL 5.6.7 以降では、CHANGE MASTER TO によって進行中のトランザクションの暗黙的なコミットが発生します。セクション13.3.3「暗黙的なコミットを発生させるステートメント」を参照してください。

CHANGE MASTER TO は、マスターのスナップショットが存在し、かつそのスナップショットの時間に対応するマスターバイナリログの座標が記録されている場合のスレーブの設定に役立ちます。そのスナップショットをスレーブにロードしてスレーブをマスターと同期させたあと、スレーブ上で CHANGE MASTER TO MASTER_LOG_FILE='log_name'、MASTER_LOG_POS=log_pos を実行して、スレーブがマスターバイナリログの読み取りを開始すべき座標を指定できます。

次の例では、スレーブが使用するマスターサーバーを変更し、スレーブが読み取りを開始するマスターバイナリログの座標を確立します。これは、マスターをレプリケートするスレーブを設定する場合に使用されます。

CHANGE MASTER TO
  MASTER_HOST='master2.mycompany.com',
  MASTER_USER='replication',
  MASTER_PASSWORD='bigs3cret',
  MASTER_PORT=3306,
  MASTER_LOG_FILE='master2-bin.001',
  MASTER_LOG_POS=4,
  MASTER_CONNECT_RETRY=10;

次の例は、使用される頻度の低い操作を示しています。これは、何らかの理由で再度実行したいリレーログファイルがスレーブに存在する場合に使用されます。これを行うために、マスターに到達できる必要はありません。CHANGE MASTER TO を使用し、SQL スレッドを開始する (START SLAVE SQL_THREAD) だけで済みます。

CHANGE MASTER TO
  RELAY_LOG_FILE='slave-relay-bin.006',
  RELAY_LOG_POS=4025;

この 2 番目の操作は、クラッシュのあとのリカバリのために、スレーブ以外のスタンドアロンサーバーを含む非レプリケーションセットアップで使用することもできます。サーバーがクラッシュし、それをバックアップからリストアしたとします。そのサーバーの独自の (たとえば、myhost-bin.* という名前の) バイナリログファイル (リレーログファイルではなく、通常のバイナリログファイル) を再実行しようとしています。まず、下の手順のとおりに実行せず、バイナリログがサーバーで誤ってパージされた場合に備えて、これらのバイナリログファイルのバックアップコピーをどこか安全な場所に作成します。さらに安全にするために、SET GLOBAL relay_log_purge=0 を使用します。次に、--log-bin オプションなしでサーバーを起動します。代わりに、--replicate-same-server-id、--relay-log=myhost-bin (サーバーに、これらの通常のバイナリログファイルがリレーログファイルであると信じ込ませるため)、および --skip-slave-start オプションを使用します。サーバーが起動したら、次のステートメントを発行します。

CHANGE MASTER TO
  RELAY_LOG_FILE='myhost-bin.153',
  RELAY_LOG_POS=410,
  MASTER_HOST='some_dummy_string';
START SLAVE SQL_THREAD;

サーバーは独自のバイナリログファイルを読み取って実行し、それによりクラッシュリカバリを実現します。リカバリが完了したら、STOP SLAVE を実行し、サーバーをシャットダウンし、マスター情報およびリレーログ情報リポジトリをクリアして、サーバーをその元のオプションで再起動します。

MASTER_HOST オプションの指定 (ダミー値であっても) は、サーバーにそれがスレーブであると思わせるために必要です。

次の表は、文字列値のオプションに許可される最大長を示しています。

オプション	最大長
MASTER_HOST	60
MASTER_USER	16
MASTER_PASSWORD	32
MASTER_LOG_FILE	255
RELAY_LOG_FILE	255
MASTER_SSL_CA	255
MASTER_SSL_CAPATH	255
MASTER_SSL_CERT	255
MASTER_SSL_CRL	255
MASTER_SSL_CRLPATH	255
MASTER_SSL_KEY	255
MASTER_SSL_CIPHER	511