CHANGE MASTER TO option [, option] ... [ channel_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 = 'source_log_name'
  | MASTER_LOG_POS = source_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}
  | MASTER_TLS_VERSION = 'protocol_list'
  | IGNORE_SERVER_IDS = (server_id_list)
}

channel_option:
    FOR CHANNEL channel

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

CHANGE MASTER TO更改副本用于连接到复制源服务器、读取源的二进制日志和读取副本的中继日志的参数。它还更新复制元数据存储库的内容（请参阅 第 16.2.4 节，“中继日志和复制元数据存储库”）。CHANGE MASTER TO需要 SUPER特权。

在 MySQL 5.7.4 之前，复制线程必须停止，STOP SLAVE必要时在发出此语句之前使用。在 MySQL 5.7.4 及更高版本中，您可以CHANGE MASTER TO在不执行此操作的情况下在正在运行的副本上发出语句，具体取决于复制 SQL 线程和复制 I/O 线程的状态。管理此类使用的规则将在本节后面提供。

当使用多线程副本（换句话说 slave_parallel_workers大于 0）时，停止副本会导致 从中继日志执行的事务序列中出现“间隙”，无论副本是有意还是其他方式停止。当存在这种差距时，发行CHANGE MASTER TO 就会失败。在这种情况下的解决方案是发出 START SLAVE UNTIL SQL_AFTER_MTS_GAPS确保差距被关闭的问题。

可选子句使您能够命名该语句适用于哪个复制通道。提供一个子句将 语句应用于特定的复制通道，并用于添加新通道或修改现有通道。例如，要添加一个名为 channel2 的新频道： FOR CHANNEL channelFOR CHANNEL channelCHANGE MASTER TO

CHANGE MASTER TO MASTER_HOST=host1, MASTER_PORT=3002 FOR CHANNEL 'channel2'

如果没有命名子句并且不存在额外的通道，则该语句适用于默认通道。

使用多个复制通道时，如果CHANGE MASTER TO语句未使用 子句命名通道，则会发生错误。有关详细信息，请参阅第 16.2.2 节，“复制通道”。 FOR CHANNEL channel

未指定的选项保留其值，除非在以下讨论中指出。因此，在大多数情况下，无需指定不会更改的选项。例如，如果连接到复制源服务器的密码已更改，请发出此语句以将新密码告知副本：

CHANGE MASTER TO MASTER_PASSWORD='new3cret';

MASTER_HOST, MASTER_USER, MASTER_PASSWORD, MASTER_PORT并向副本提供有关如何连接到其复制源服务器的信息：

设置MASTER_SSL=1复制连接然后不设置其他 选项对应于 客户端的设置，如 加密连接的命令选项中所述。使用 ，连接尝试只有在可以建立加密连接时才会成功。复制连接不会退回到未加密的连接，因此没有与 复制设置对应的设置。如果已设置，则对应于 . MASTER_SSL_xxx--ssl-mode=REQUIREDMASTER_SSL=1--ssl-mode=PREFERREDMASTER_SSL=0--ssl-mode=DISABLED

选项和选项指定副本如何 使用加密和密码来保护复制连接。即使在没有 SSL 支持的情况下编译的副本，也可以更改这些选项。它们保存到源元数据存储库，但如果副本未启用 SSL 支持，则会被忽略。和 选项执行与 加密连接的命令选项中描述 的和 客户端选项相同的功能 。两组选项的对应关系，以及和的 使用MASTER_SSL_xxxMASTER_TLS_VERSIONMASTER_SSL_xxxMASTER_TLS_VERSION--ssl-xxx--tls-versionMASTER_SSL_xxxMASTER_TLS_VERSION设置安全连接的选项，在 第 16.3.8 节，“设置复制以使用加密连接”中进行了解释。

、MASTER_HEARTBEAT_PERIOD和 选项控制副本如何识别MASTER_CONNECT_RETRY与 MASTER_RETRY_COUNT源的连接已丢失并尝试重新连接。

MASTER_DELAY指定副本必须落后于源多少秒。从源接收到的事件至少 interval比它在源上的执行晚几秒才执行。^{默认值为 0。如果不是 0 到 2 31} −1interval范围内的非负整数，则会发生错误 。有关详细信息，请参阅第 16.3.10 节，“延迟复制”。

从 MySQL 5.7 开始，当复制 SQL 线程停止时，可以在正在运行的副本上执行 CHANGE MASTER TO使用该选项的语句。MASTER_DELAY

MASTER_BIND用于具有多个网络接口的副本，并确定选择哪个副本的网络接口来连接到源。

使用此选项配置的地址（如果有）可以在Master_Bind输出的列中 看到SHOW SLAVE STATUS。如果您正在为源元数据存储库（服务器以 启动 master_info_repository=TABLE）使用表，则该值也可以视为表的Master_bind 列mysql.slave_master_info。

NDB Cluster 还支持将副本绑定到特定网络接口的能力。

MASTER_LOG_FILEMASTER_LOG_POS是复制 I/O 线程在下次线程启动时应开始从源读取的坐标 。 RELAY_LOG_FILE并且 RELAY_LOG_POS是复制 SQL 线程在下次线程启动时应该开始从中继日志读取的坐标。如果指定这些选项中的任何一个，则无法指定MASTER_AUTO_POSITION = 1（在本节后面描述）。MASTER_LOG_FILE如果or 均未 MASTER_LOG_POS指定，则副本使用之前复制 SQL 线程的最后一个坐标CHANGE MASTER TO发出。这确保了复制没有中断，即使复制 SQL 线程比复制 I/O 线程晚了，当您只想更改，比方说，要使用的密码时。

从 MySQL 5.7 开始，当复制 SQL 线程停止时，可以在正在运行的副本上执行使用 、 或这两个选项的 CHANGE MASTER TO语句。在 MySQL 5.7.4 之前，删除所有中继日志文件并启动一个新文件，除非您指定或 。在这种情况下，会保留中继日志文件；全局变量静默设置为 0。在 MySQL 5.7.4 及更高版本中，如果复制 SQL 线程和复制 I/O 线程中至少有一个正在运行，则会保留中继日志。如果两个线程都停止，则删除所有中继日志文件，除非至少有一个或 RELAY_LOG_FILERELAY_LOG_POSCHANGE MASTER TORELAY_LOG_FILERELAY_LOG_POSrelay_log_purgeRELAY_LOG_FILERELAY_LOG_POS被指定。对于只有一个 SQL 线程而没有 I/O 线程的 Group Replication applier 通道 ( group_replication_applier)，如果 SQL 线程停止，就会出现这种情况，但是对于该通道，您不能使用 RELAY_LOG_FILE和 RELAY_LOG_POS选项。

RELAY_LOG_FILE可以使用绝对路径或相对路径，并使用与 MASTER_LOG_FILE. （漏洞 #12190）

当MASTER_AUTO_POSITION = 1与 一起使用时 CHANGE MASTER TO，副本尝试使用基于 GTID 的复制的自动定位功能连接到源，而不是基于二进制日志文件的位置。CHANGE MASTER TO从 MySQL 5.7 开始，只有当复制 SQL 线程和复制 I/O 线程都停止时才能使用此选项 。副本和源都必须启用 GTID（GTID_MODE=ON， ON_PERMISSIVE,或 OFF_PERMISSIVE在副本和 GTID_MODE=ON源上）。 MASTER_LOG_FILE, MASTER_LOG_POS, RELAY_LOG_FILE, 和 RELAY_LOG_POS不能与 一起指定MASTER_AUTO_POSITION = 1。如果在副本上启用了多源复制，则需要设置MASTER_AUTO_POSITION = 1每个适用的复制通道的选项。

使用MASTER_AUTO_POSITION = 1set，在初始连接握手中，副本发送一个 GTID 集，其中包含它已经接收、提交或两者都包含的事务。源通过发送记录在其二进制日志中的所有事务来响应，这些事务的 GTID 不包含在副本发送的 GTID 集中。此交换确保源仅发送具有副本尚未记录或提交的 GTID 的事务。如果副本从多个来源接收交易，如在菱形拓扑的情况下，自动跳过功能确保交易不会被应用两次。有关如何计算副本发送的 GTID 集的详细信息，请参阅 第 16.1.3.3 节，“GTID 自动定位”.

如果应由源发送的任何事务已从源的二进制日志中清除，或已gtid_purged 通过其他方法添加到系统变量中的 GTID 集，则源将错误发送 ER_MASTER_HAS_PURGED_REQUIRED_GTIDS 到副本，并且复制不会开始. 此外，如果在事务交换期间发现副本已记录或提交了 GTID 中源的 UUID 的事务，但源本身尚未提交它们，则源将错误发送 ER_SLAVE_HAS_MORE_GTIDS_THAN_MASTER 到副本并且复制不会启动。有关如何处理这些情况的信息，请参阅 第 16.1.3.3 节，“GTID 自动定位”。

IGNORE_SERVER_IDS采用逗号分隔的 0 个或多个服务器 ID 列表。来自相应服务器的事件将被忽略，日志轮换和删除事件除外，它们仍然记录在中继日志中。

在循环复制中，原始服务器通常充当其自身事件的终结者，因此它们不会被多次应用。因此，当循环中的一台服务器被删除时，此选项在循环复制中很有用。假设您有一个包含 4 个服务器的循环复制设置，服务器 ID 分别为 1、2、3 和 4，而服务器 3 发生故障。当通过开始从服务器 2 到服务器 4 的复制来弥合差距时，您可以IGNORE_SERVER_IDS = (3)在CHANGE MASTER TO您在服务器 4 上发出的语句中包含告诉它使用服务器 2 作为其源而不是服务器 3。这样做会导致它忽略而不是传播源自不再使用的服务器的任何语句。

如果CHANGE MASTER TO发出的语句没有任何IGNORE_SERVER_IDS 选项，则保留任何现有列表。要清除忽略的服务器列表，必须使用带有空列表的选项：

CHANGE MASTER TO IGNORE_SERVER_IDS = ();

在 MySQL 5.7.5 之前， RESET SLAVE ALL对服务器 ID 列表没有影响。在 MySQL 5.7.5 及更高版本中，RESET SLAVE ALL清除 IGNORE_SERVER_IDS. （漏洞#18816897）

如果IGNORE_SERVER_IDS包含服务器自己的 ID 并且服务器是在 --replicate-same-server-id启用该选项的情况下启动的，则会产生错误。

源元数据存储库和输出 SHOW SLAVE STATUS提供了当前被忽略的服务器列表。有关详细信息，请参阅第 16.2.4.2 节，“复制元数据存储库”和 第 13.7.5.34 节，“SHOW SLAVE STATUS 语句”。

调用会导致、 、 和 CHANGE MASTER TO的先前值连同有关执行前副本状态的其他信息一起写入错误日志。 MASTER_HOSTMASTER_PORTMASTER_LOG_FILEMASTER_LOG_POS

CHANGE MASTER TO导致正在进行的事务的隐式提交。请参阅第 13.3.3 节，“导致隐式提交的语句”。

在 MySQL 5.7.4 及更高版本中，删除了STOP SLAVE在发出任何 CHANGE MASTER TO语句之前（以及 之后） 执行的严格要求 。START SLAVE的行为不依赖于副本是否停止，而是依赖于CHANGE MASTER TO（在 MySQL 5.7.4 及更高版本中）复制 SQL 线程和复制 I/O 线程的状态；现在停止或运行这些线程中的哪一个决定了在给定时间点可以或不能与CHANGE MASTER TO语句一起使用的选项。此处列出了做出此决定的规则：

You can check the current state of the replication SQL thread and the replication I/O thread using SHOW SLAVE STATUS. Note that the Group Replication applier channel (group_replication_applier) has no I/O thread, only an SQL thread.

For more information, see Section 16.3.7, “Switching Sources During Failover”.

If you are using statement-based replication and temporary tables, it is possible for a CHANGE MASTER TO statement following a STOP SLAVE statement to leave behind temporary tables on the replica. From MySQL 5.7, a warning (ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO) is issued whenever this occurs. You can avoid this in such cases by making sure that the value of the Slave_open_temp_tables system status variable is equal to 0 prior to executing such a CHANGE MASTER TO statement.

CHANGE MASTER TO is useful for setting up a replica when you have the snapshot of the replication source server and have recorded the source's binary log coordinates corresponding to the time of the snapshot. After loading the snapshot into the replica to synchronize it with the source, you can run CHANGE MASTER TO MASTER_LOG_FILE='log_name', MASTER_LOG_POS=log_pos on the replica to specify the coordinates at which the replica should begin reading the source's binary log.

The following example changes the replication source server the replica uses and establishes the source's binary log coordinates from which the replica begins reading. This is used when you want to set up the replica to replicate the source:

CHANGE MASTER TO
  MASTER_HOST='source2.example.com',
  MASTER_USER='replication',
  MASTER_PASSWORD='password',
  MASTER_PORT=3306,
  MASTER_LOG_FILE='source2-bin.001',
  MASTER_LOG_POS=4,
  MASTER_CONNECT_RETRY=10;

下一个示例显示了一个不太经常使用的操作。当副本具有中继日志文件时使用，您希望它出于某种原因再次执行。为此，源不需要可达。您只需要使用 CHANGE MASTER TO并启动 SQL 线程 ( START SLAVE SQL_THREAD)：

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

下表显示了字符串值选项的最大允许长度。