13.4.2.1 更改主声明

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] ... ]

更改为主更改副本用于连接到复制源服务器，读取源的二进制日志以及读取副本的中继日志的参数。它还会更新复制元数据存储库的内容(请参阅第 16.2.4 节“中继日志和复制应用程序元数据存储库”)。 更改为主需要SUPER特权。

在 MySQL 5.7.4 之前，必须在发出此语句之前使用停止复制线程。在 MySQL 5.7.4 和更高版本中，您可以在运行中的副本上发出CHANGE MASTER TO语句而无需执行此操作，这取决于复制 SQL 线程和复制 I/O 线程的状态。本节稍后将提供 Management 此类使用的规则。

当使用多线程副本(换言之slave_parallel_workers大于 0)时，停止副本可能会导致已从中继日志执行的事务序列出现“间隙”，而不管副本是否被有意停止。如果存在此类差距，则发出更改为主失败。在这种情况下，解决方案是发出从开始直到 SQL_AFTER_MTS_GAPS，以确保缩小差距。

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

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

如果未命名任何子句且不存在其他通道，则该语句将应用于默认通道。

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

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

CHANGE MASTER TO MASTER_PASSWORD='new3cret';

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

• MASTER_HOST和MASTER_PORT是主控主机及其 TCP/IP 端口的主机名(或 IP 地址)。

如果指定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随后失败。 (缺陷号 28796)

检查用于MASTER_HOST和其他CHANGE MASTER TO选项的值的换行符(\n或0x0A)；这些值中存在此类字符会导致语句以ER_MASTER_INFO失败。 (缺陷#11758581，缺陷#50801)

• MASTER_USER和MASTER_PASSWORD是用于连接到源的帐户的用户名和密码。如果指定MASTER_PASSWORD，则还需要MASTER_USER。 CHANGE MASTER TO语句中用于复制用户帐户的密码的长度限制为 32 个字符；在 MySQL 5.7.5 之前的版本中，如果密码更长，则语句成功，但是任何多余的字符都会被静默截断。在 MySQL 5.7.5 和更高版本中，尝试使用超过 32 个字符的密码会导致CHANGE MASTER TO失败。 (缺陷#11752299，缺陷#43439)

可以通过指定MASTER_USER=''来设置空用户名，但是无法使用空用户名启动复制通道。如果出于安全目的需要从副本存储库中清除以前使用的凭据，并且仅在以后不要尝试使用该通道，则仅设置一个空的MASTER_USER用户名。

并发SHOW PROCESSLIST语句的输出中可以看到正在运行的更改为主语句的文本，包括MASTER_USER和MASTER_PASSWORD的值。 (SHOW PROCESSLIST也可以看到START SLAVE语句的全文)。

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

从 MySQL 5.7.3 开始，设置MASTER_SSL=1意味着副本到源的连接必须使用 SSL，否则连接尝试将失败。在 5.7.3 之前，MASTER_SSL=1并未强制副本使用 SSL 连接。这类似于--ssl命令行选项的 Client 端含义；参见加密连接的命令选项。

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

• slave_net_timeout系统变量指定副本在认为连接断开，中止读取并尝试重新连接之前，副本 await 来自源的更多数据或心跳 signal 的秒数。默认值为 60 秒(一分钟)。在 MySQL 5.7.7 之前，默认值为 3600 秒(一小时)。

• 心跳间隔由MASTER_HEARTBEAT_PERIOD选项控制，该间隔将在没有数据的情况下停止连接超时(如果连接仍然良好)。在该秒数之后，将心跳 signal 发送到副本，并且每当使用事件更新源的二进制日志时，都会重置 await 时间。因此，仅当二进制日志文件中没有未发送事件的时间超过此时间时，才由源发送心跳。心跳间隔* interval 为十进制值，范围为 0 到 4294967 秒，分辨率为毫秒。最小的非零值为 0.001. 将 interval *设置为 0 会完全禁用心跳。心跳间隔默认为slave_net_timeout系统变量的一半。它记录在源元数据存储库中，并显示在replication_connection_configuration Performance Schematable 中。发出RESET SLAVE会将心跳间隔重置为默认值。

• 在 MySQL 5.7.4 之前，不包含MASTER_HEARTBEAT_PERIOD导致CHANGE MASTER TO将心跳间隔重置为默认值(系统变量slave_net_timeout的一半)，并且Slave_received_heartbeats重置为 0.除了RESET SLAVE，现在不重置心跳间隔。错误 18185490)

• 请注意，更改值或默认设置slave_net_timeout不会自动更改心跳间隔，无论是已明确设置还是正在使用先前计算的默认值。如果将@@GLOBAL.slave_net_timeout设置为小于当前心跳间隔的值，则会发出警告。如果更改了slave_net_timeout，则还必须发出更改为主以将心跳间隔调整为适当的值，以便在连接超时之前出现心跳 signal。如果不执行此操作，则心跳 signal 将无效，并且如果未从源接收到任何数据，则副本可以重复尝试重新连接，从而创建僵尸转储线程。

• 如果副本确实需要重新连接，则第一次重试将在超时后立即进行。 MASTER_CONNECT_RETRY指定重新连接尝试之间的间隔，MASTER_RETRY_COUNT限制重新连接尝试的次数。如果同时使用两个默认设置，则副本将在两次尝试重新连接(MASTER_CONNECT_RETRY=60)之间 await60 秒，并 continue 尝试以此速率重新连接 60 天(MASTER_RETRY_COUNT=86400)。这些值记录在源元数据存储库中，并显示在replication_connection_configuration Performance Schematable 中。 MASTER_RETRY_COUNT取代--master-retry-count服务器启动选项。

MASTER_DELAY指定副本必须滞后源几秒。从源接收到的事件要比在源上执行的事件晚至少* interval 秒才执行。默认值为 0.如果 interval *不是 0 到 231-1 范围内的非负整数，则会发生错误。有关更多信息，请参见第 16.3.10 节，“延迟复制”。

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

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

使用此选项配置的地址(如果有的话)可以在显示从站状态的输出的Master_Bind列中看到。如果将 table 用于源元数据存储库(服务器以master_info_repository=TABLE开头)，则该值也可以视为mysql.slave_master_infotable 的Master_bind列。

NDB 群集还支持将副本绑定到特定网络接口的功能。

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。如果指定MASTER_LOG_FILE或MASTER_LOG_POS之一，则也不能指定MASTER_AUTO_POSITION = 1(在本节后面介绍)。如果未指定MASTER_LOG_FILE或MASTER_LOG_POS中的任何一个，则副本将使用发出更改为主之前的复制 SQL 线程的最后坐标。这可以确保即使您只是想更改要使用的密码，即使复制 SQL 线程比复制 I/O 线程都晚，复制也不会中断。

从 MySQL 5.7 开始，当复制 SQL 线程停止时，可以在正在运行的副本上执行使用RELAY_LOG_FILE，RELAY_LOG_POS或这两个选项的CHANGE MASTER TO语句。在 MySQL 5.7.4 之前，CHANGE MASTER TO删除所有中继日志文件并开始一个新的中继日志文件，除非您指定RELAY_LOG_FILE或RELAY_LOG_POS。在这种情况下，将保留中继日志文件。 relay_log_purge全局变量默认设置为 0.在 MySQL 5.7.4 及更高版本中，如果复制 SQL 线程和复制 I/O 线程中的至少一个正在运行，则中继日志将保留。如果两个线程都停止，则除非指定了RELAY_LOG_FILE或RELAY_LOG_POS中的至少一个，否则所有中继日志文件都将被删除。请注意，组复制应用程序通道(group_replication_applier)没有 I/O 线程，只有 SQL 线程。对于此通道，当 SQL 线程停止时，不会保留中继日志。

RELAY_LOG_FILE可以使用绝对路径或相对路径，并使用与MASTER_LOG_FILE相同的基本名称。错误 12190)

当MASTER_AUTO_POSITION = 1与CHANGE MASTER TO一起使用时，副本将尝试使用基于 GTID 的复制协议连接到源。从 MySQL 5.7 开始，只有复制 SQL 线程和复制 I/O 线程都停止时，CHANGE MASTER TO才能使用此选项。副本服务器和源服务器都必须启用 GTID(副本服务器上的GTID_MODE=ON，ON_PERMISSIVE,或OFF_PERMISSIVE，源服务器上的GTID_MODE=ON)。自动定位用于连接，因此不使用MASTER_LOG_FILE和MASTER_LOG_POStable 示的坐标，并且将这些选项中的一个或两个与MASTER_AUTO_POSITION = 1一起使用会导致错误。如果在副本上启用了多源复制，则需要为每个适用的复制通道设置MASTER_AUTO_POSITION = 1选项。

设置为MASTER_AUTO_POSITION = 1时，在初始连接握手中，副本将发送一个 GTID 集，其中包含它已接收，已提交或同时发生的事务。源通过发送记录在其二进制日志中的所有事务进行响应，这些事务的 GTID 未包含在副本发送的 GTID 集中。这种交换可确保源仅发送具有副本尚未记录或提交的 GTID 的事务。如果副本从多个来源接收事务，例如菱形拓扑，则自动跳过功能可确保不会两次应用事务。有关如何计算副本发送的 GTID 集的详细信息，请参见第 16.1.3.3 节“ GTID 自动定位”。

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

您可以通过检查 Performance Schema replication_connection_statustable 或显示从站状态的输出来查看复制是否在启用自动定位的情况下运行。再次禁用MASTER_AUTO_POSITION选项会使副本恢复为基于文件的复制，在这种情况下，您还必须指定MASTER_LOG_FILE或MASTER_LOG_POS选项之一或全部。

IGNORE_SERVER_IDS以逗号分隔的 0 或多个服务器 ID 列 table。除了日志轮换和删除事件(仍记录在中继日志中)之外，将忽略源自相应服务器的事件。

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

如果发出的更改为主语句没有任何IGNORE_SERVER_IDS选项，则将保留所有现有列 table。要清除忽略的服务器列 table，必须使用带有空列 table 的选项：

CHANGE MASTER TO IGNORE_SERVER_IDS = ();

在 MySQL 5.7.5 之前，重设全部对服务器 ID 列 table 无效。在 MySQL 5.7.5 和更高版本中，RESET SLAVE ALL清除IGNORE_SERVER_IDS。错误#18816897)

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

源元数据存储库和显示从站状态的输出提供了当前被忽略的服务器列 table。有关更多信息，请参见第 16.2.4.2 节“复制应用程序元数据存储库”和第 13.7.5.34 节“ SHOW SLAVE STATUS 语句”。

调用更改为主会将MASTER_HOST，MASTER_PORT，MASTER_LOG_FILE和MASTER_LOG_POS的先前值以及有关副本状态在执行前的其他信息写入错误日志。

CHANGE MASTER TO导致正在进行的事务的隐式提交。参见第 13.3.3 节“导致隐式提交的声明”。

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

• 如果 SQL 线程已停止，则即使复制 I/O 线程正在运行，也可以使用RELAY_LOG_FILE，RELAY_LOG_POS和MASTER_DELAY选项允许的任何组合来执行CHANGE MASTER TO。当 I/O 线程正在运行时，此语句不能与其他选项一起使用。

• 如果 I/O 线程已停止，则即使使用 SQL 线程，也可以使用此语句的任何选项(以任何允许的组合)执行CHANGE MASTER TO(*除外)RELAY_LOG_FILE，RELAY_LOG_POS，MASTER_DELAY或MASTER_AUTO_POSITION = 1。

• 在发出使用MASTER_AUTO_POSITION = 1的CHANGE MASTER TO语句之前，必须停止 SQL 线程和 I/O 线程。

您可以使用显示从站状态检查复制 SQL 线程和复制 I/O 线程的当前状态。请注意，组复制应用程序通道(group_replication_applier)没有 I/O 线程，只有 SQL 线程。

有关更多信息，请参见第 16.3.7 节“故障转移期间切换源”。

如果使用的是基于语句的复制和临时 table，则STOP SLAVE语句后的CHANGE MASTER TO语句可能会在副本上留下临时 table。从 MySQL 5.7 开始，每当发生警告时，就会发出警告(ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO)。在这种情况下，可以通过在执行这样的CHANGE MASTER TO语句之前确保Slave_open_temp_tables系统状态变量的值等于 0 来避免这种情况。

当您拥有复制源服务器的快照并记录了与快照时间相对应的源二进制日志坐标时，更改为主对于设置副本很有用。将快照加载到副本中以使其与源同步后，可以在副本上运行CHANGE MASTER TO MASTER_LOG_FILE='log_name', MASTER_LOG_POS=log_pos以指定副本应开始读取源二进制日志的坐标。

以下示例更改了副本使用的复制源服务器，并构建了副本开始读取的源的二进制日志坐标。当您要设置副本以复制源时使用此方法：

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;

下一个示例显示了较少使用的操作。当副本具有中继日志文件(出于某种原因希望您再次执行)时，将使用该副本。为此，源不必是可及的。您只需要使用更改为主并启动 SQL 线程(START SLAVE SQL_THREAD)：

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

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

Option	Maximum Length
MASTER_HOST	60
MASTER_USER	96
MASTER_PASSWORD	32
MASTER_LOG_FILE	511
RELAY_LOG_FILE	511
MASTER_SSL_CA	511
MASTER_SSL_CAPATH	511
MASTER_SSL_CERT	511
MASTER_SSL_CRL	511
MASTER_SSL_CRLPATH	511
MASTER_SSL_KEY	511
MASTER_SSL_CIPHER	511
MASTER_TLS_VERSION	511