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 репликации и потока ввода/вывода репликации. Правила, определяющие такое использование, приведены позже в этом разделе.

При использовании многопоточной реплики (другими словами, slave_parallel_workers больше 0), остановка реплики может привести к “пробелам” в последовательности транзакций, которые были выполнены из лога репликации, независимо от того, была ли реплика остановлена намеренно или иным образом. Когда такие пробелы существуют, выполнение CHANGE MASTER TO завершается ошибкой. Решением в этой ситуации является выполнение START SLAVE UNTIL 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.2, «Каналы репликации» для получения дополнительной информации.

Неуказанные параметры сохраняют свои значения, за исключением случаев, указанных в последующем обсуждении. Таким образом, в большинстве случаев нет необходимости указывать параметры, которые не изменяются. Например, если пароль для подключения к серверу источника репликации изменился, выполните это заявление, чтобы сообщить реплике о новом пароле:

CHANGE MASTER TO MASTER_PASSWORD='new3cret';

MASTER_HOST, MASTER_USER, MASTER_PASSWORD и MASTER_PORT предоставляют реплике информацию о том, как подключаться к серверу источника репликации:

Установка MASTER_SSL=1 для подключения репликации и отсутствие дальнейших параметров MASTER_SSL_xxx соответствует установке --ssl-mode=REQUIRED для клиента, как описано в Параметры команд для зашифрованных подключений. С MASTER_SSL=1 попытка подключения будет успешной только в том случае, если можно установить зашифрованное соединение. Соединение репликации не переходит на незашифрованное соединение, поэтому нет настройки, соответствующей параметру --ssl-mode=PREFERRED для репликации. Если MASTER_SSL=0 установлено, это соответствует --ssl-mode=DISABLED.

Параметры MASTER_SSL_xxx и MASTER_TLS_VERSION определяют, как реплика использует шифрование и шифры для защиты подключения репликации. Эти параметры можно изменить даже на репликах, скомпилированных без поддержки SSL. Они сохраняются в репозитории метаданных источника, но игнорируются, если на реплике не включена поддержка SSL. Параметры MASTER_SSL_xxx и MASTER_TLS_VERSION выполняют те же функции, что и параметры клиента --ssl-xxx и --tls-version, описанные в Параметры команд для зашифрованных подключений. Соответствие между двумя наборами параметров и использование параметров MASTER_SSL_xxx и MASTER_TLS_VERSION для настройки безопасного соединения поясняется в Разделе 16.3.8, «Настройка репликации для использования зашифрованных подключений».

Параметры MASTER_HEARTBEAT_PERIOD, MASTER_CONNECT_RETRY и MASTER_RETRY_COUNT контролируют, как реплика распознает, что соединение с источником потеряно, и предпринимает попытки повторного подключения.

MASTER_DELAY указывает, на сколько секунд реплика должна отставать от источника. Событие, полученное от источника, не выполняется, пока не пройдёт не менее interval секунд после его выполнения на источнике. Значение по умолчанию равно 0. Возникает ошибка, если interval не является целым неотрицательным числом в диапазоне от 0 до 2³¹−1. Для получения дополнительной информации см. Раздел 16.3.10, «Задержка репликации».

С MySQL 5.7, операция CHANGE MASTER TO, использующая параметр MASTER_DELAY, может быть выполнена на работающей реплике, когда поток репликации SQL остановлен.

MASTER_BIND используется на репликах с несколькими сетевыми интерфейсами и определяет, какой сетевой интерфейс реплики используется для подключения к источнику.

Настроенный адрес, если таковой имеется, отображается в столбце Master_Bind в выводе команды SHOW SLAVE STATUS. Если вы используете таблицу для репозитория метаданных источника (сервер запущен с master_info_repository=TABLE), значение также отображается в столбце Master_bind таблицы mysql.slave_master_info.

Возможность привязки реплики к конкретному сетевому интерфейсу также поддерживается NDB Cluster.

MASTER_LOG_FILE и MASTER_LOG_POS — координаты, с которых поток ввода/вывода репликации должен начать чтение данных из источника при следующем запуске потока. RELAY_LOG_FILE и RELAY_LOG_POS — координаты, с которых поток SQL репликации должен начать чтение данных из релевого журнала при следующем запуске потока. Если вы указываете любой из этих параметров, вы не можете указать MASTER_AUTO_POSITION = 1 (описано позже в этом разделе). Если ни MASTER_LOG_FILE, ни MASTER_LOG_POS не указаны, реплика использует последние координаты потока SQL репликации до выполнения CHANGE MASTER TO. Это гарантирует отсутствие разрывов в репликации, даже если поток SQL репликации отстал от потока ввода/вывода репликации, когда нужно только изменить, например, пароль.

С MySQL 5.7 операция CHANGE MASTER TO, использующая параметры RELAY_LOG_FILE, RELAY_LOG_POS или оба, может быть выполнена на работающей реплике при остановленном потоке SQL репликации. До MySQL 5.7.4, CHANGE MASTER TO удаляет все файлы релевого журнала и создаёт новый, если вы не укажете RELAY_LOG_FILE или RELAY_LOG_POS. В этом случае файлы релевого журнала сохраняются; глобальная переменная relay_log_purge устанавливается в 0. В MySQL 5.7.4 и более поздних версиях релейные журналы сохраняются, если хотя бы один из потоков репликации SQL и ввода/вывода репликации работает. Если оба потока остановлены, все файлы релевого журнала удаляются, если не указан хотя бы один из параметров RELAY_LOG_FILE или RELAY_LOG_POS. Для канала приложения Group Replication (group_replication_applier), который имеет только поток SQL и не имеет потока ввода/вывода, это верно, если поток SQL остановлен, но с этим каналом нельзя использовать параметры RELAY_LOG_FILE и RELAY_LOG_POS.

RELAY_LOG_FILE может использовать абсолютный или относительный путь и использует то же имя файла, что и MASTER_LOG_FILE. (Ошибка #12190)

Когда MASTER_AUTO_POSITION = 1 используется с CHANGE MASTER TO, реплика пытается подключиться к источнику, используя функцию автоматического позиционирования в репликации на основе GTID, а не позиции в бинарном журнале. Начиная с MySQL 5.7, этот параметр можно использовать с CHANGE MASTER TO только если оба потока репликации SQL и ввода/вывода остановлены. И реплика, и источник должны иметь включённые 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 = 1, при первоначальном установлении соединения реплика отправляет набор GTID, содержащий транзакции, которые она уже получила, подтвердила или и то, и другое. Источник отвечает, отправляя все транзакции, записанные в его бинарном журнале, GTID которых не входит в набор GTID, отправленный репликой. Этот обмен гарантирует, что источник отправляет только транзакции с GTID, которые реплика ещё не записала или не подтвердила. Если реплика получает транзакции от более чем одного источника, как в случае с алмазной топологией, функция автоматического пропуска гарантирует, что транзакции не применяются дважды. Для получения подробной информации о том, как вычисляется набор GTID, отправленный репликой, см. Раздел 16.1.3.3, «Автоматическое позиционирование GTID».

Если какие-либо транзакции, которые должны быть отправлены источником, были удалены из бинарного журнала источника или добавлены в набор GTID в переменной системы gtid_purged другим методом, источник отправляет ошибку реплике, и репликация не начинается. Также, если во время обмена транзакциями обнаруживается, что реплика записала или подтвердила транзакции с UUID источника в GTID, но сам источник их не подтвердил, источник отправляет ошибку реплике, и репликация не начинается. Информация о том, как обращаться с такими ситуациями, приведена в Раздел 16.1.3.3, «Автоматическое позиционирование GTID».

IGNORE_SERVER_IDS принимает список из 0 или более идентификаторов серверов, разделённых запятыми. События, исходящие от соответствующих серверов, игнорируются, за исключением событий вращения и удаления журнала, которые всё равно записываются в релейный журнал.

При круговой репликации исходный сервер обычно выполняет роль терминатора собственных событий, чтобы они не применялись более одного раза. Таким образом, этот вариант полезен при круговой репликации, когда один из серверов в кольце удаляется. Предположим, что у вас есть круговая конфигурация репликации с 4 серверами, имеющими идентификаторы серверов 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 не оказывает никакого влияния на список идентификаторов серверов. В MySQL 5.7.5 и более поздних версиях, RESET SLAVE ALL очищает IGNORE_SERVER_IDS. (Ошибка #18816897)

Если IGNORE_SERVER_IDS содержит идентификатор собственного сервера и сервер был запущен с опцией --replicate-same-server-id , включенной, возникает ошибка.

Репозиторий метаданных источника и вывод инструкции SHOW SLAVE STATUS предоставляют список серверов, которые в настоящее время игнорируются. Дополнительную информацию см. в разделе 16.2.4.2, «Репозитории метаданных репликации» и разделе 13.7.5.34, «Инструкция SHOW SLAVE STATUS».

Вызов инструкции CHANGE MASTER TO приводит к записи предыдущих значений для MASTER_HOST, MASTER_PORT, MASTER_LOG_FILE и MASTER_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 в данный момент. Правила определения этого состояния приведены здесь:

Вы можете проверить текущее состояние потоков SQL и I/O репликации с помощью инструкции SHOW SLAVE STATUS. Обратите внимание, что канал приложения репликации группы (group_replication_applier) не имеет потока I/O, только поток SQL.

Дополнительную информацию см. в разделе 16.3.7, «Переключение источников во время переключения».

Если вы используете репликацию на основе инструкций и временных таблиц, возможно, что инструкция CHANGE MASTER TO, следующая за инструкцией STOP SLAVE, оставит временные таблицы на реплике. Начиная с MySQL 5.7, выводится предупреждение (), когда это происходит. Вы можете избежать этого в таких случаях, убедившись, что значение системной переменной состояния Slave_open_temp_tables равно 0 перед выполнением инструкции CHANGE MASTER TO.

Инструкция CHANGE MASTER TO полезна для настройки реплики, когда у вас есть моментальный снимок сервера-источника репликации и вы записали координаты бинарного лога источника, соответствующие времени снимка. После загрузки снимка в реплику для синхронизации с источником, вы можете выполнить инструкцию 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;

Следующий пример демонстрирует операцию, которая используется реже. Она используется, когда у реплики есть файлы журнала релейной записи, которые вы хотите, чтобы она выполнила снова по какой-либо причине. Для этого источник не обязательно должен быть доступен. Вам нужно только использовать инструкцию CHANGE MASTER TO и запустить поток SQL (START SLAVE SQL_THREAD):

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

В следующей таблице показана максимальная допустимая длина для строковых опций.