Syntax:
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
  | PRIVILEGE_CHECKS_USER = {'account' | NULL}
  | 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_COMPRESSION_ALGORITHMS = 'value'
  | MASTER_ZSTD_COMPRESSION_LEVEL = level
  | 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'
  | MASTER_PUBLIC_KEY_PATH = 'key_file_name'
  | GET_MASTER_PUBLIC_KEY = {0|1}
  | IGNORE_SERVER_IDS = (server_id_list)

channel_option:
    FOR CHANNEL channel

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

CHANGE MASTER TO changes the parameters that the slave server uses for
connecting to the master server, for reading the master binary log, and
reading the slave relay log. It also updates the contents of the master
info and relay log info repositories (see
https://dev.mysql.com/doc/refman/8.0/en/slave-logs.html). CHANGE MASTER
TO requires the REPLICATION_SLAVE_ADMIN or SUPER privilege.

You can issue CHANGE MASTER TO statements on a running slave without
first stopping it, depending on the states of the slave SQL thread and
slave I/O thread. The rules governing such use are provided later in
this section.

When using a multithreaded slave (in other words slave_parallel_workers
is greater than 0), stopping the slave can cause "gaps" in the sequence
of transactions that have been executed from the relay log, regardless
of whether the slave was stopped intentionally or otherwise. When such
gaps exist, issuing CHANGE MASTER TO fails. The solution in this
situation is to issue START SLAVE UNTIL SQL_AFTER_MTS_GAPS which
ensures that the gaps are closed.

The optional FOR CHANNEL channel clause enables you to name which
replication channel the statement applies to. Providing a FOR CHANNEL
channel clause applies the CHANGE MASTER TO statement to a specific
replication channel, and is used to add a new channel or modify an
existing channel. For example, to add a new channel called channel2:

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

If no clause is named and no extra channels exist, the statement
applies to the default channel.

When using multiple replication channels, if a CHANGE MASTER TO
statement does not name a channel using a FOR CHANNEL channel clause,
an error occurs. See
https://dev.mysql.com/doc/refman/8.0/en/replication-channels.html for
more information.

Options not specified retain their value, except as indicated in the
following discussion. Thus, in most cases, there is no need to specify
options that do not change.

MASTER_HOST, MASTER_USER, MASTER_PASSWORD, and MASTER_PORT provide
information to the slave about how to connect to its master:

o MASTER_HOST and MASTER_PORT are the host name (or IP address) of the
  master host and its TCP/IP port.

  *Note*:

  Replication cannot use Unix socket files. You must be able to connect
  to the master MySQL server using TCP/IP.

  If you specify the MASTER_HOST or MASTER_PORT option, the slave
  assumes that the master server is different from before (even if the
  option value is the same as its current value.) In this case, the old
  values for the master binary log file name and position are
  considered no longer applicable, so if you do not specify
  MASTER_LOG_FILE and MASTER_LOG_POS in the statement,
  MASTER_LOG_FILE='' and MASTER_LOG_POS=4 are silently appended to it.

  Setting MASTER_HOST='' (that is, setting its value explicitly to an
  empty string) is not the same as not setting MASTER_HOST at all.
  Trying to set MASTER_HOST to an empty string fails with an error.

  Values used for MASTER_HOST and other CHANGE MASTER TO options are
  checked for linefeed (\n or 0x0A) characters; the presence of such
  characters in these values causes the statement to fail with
  ER_MASTER_INFO. (Bug #11758581, Bug #50801)

o MASTER_USER and MASTER_PASSWORD are the user name and password of the
  account to use for connecting to the master.

  MASTER_USER cannot be made empty; setting MASTER_USER = '' or leaving
  it unset when setting a value for MASTER_PASSWORD causes an error
  (Bug #13427949).

  The password used for a MySQL Replication slave account in a CHANGE
  MASTER TO statement is limited to 32 characters in length; trying to
  use a password of more than 32 characters causes CHANGE MASTER TO to
  fail.

  The text of a running CHANGE MASTER TO statement, including values
  for MASTER_USER and MASTER_PASSWORD, can be seen in the output of a
  concurrent SHOW PROCESSLIST statement. (The complete text of a START
  SLAVE statement is also visible to SHOW PROCESSLIST.)

PRIVILEGE_CHECKS_USER (available as of MySQL 8.0.18) names a user
account that supplies a security context for the specified channel.
NULL, which is the default, means no security context is used. If you
do not specify a channel and no other channels exist, the statement is
applied to the default channel. For example, to start privilege checks
on the channel channel_1 on a running replication slave, issue the
following statements:

mysql> STOP SLAVE FOR CHANNEL 'channel_1';
mysql> CHANGE MASTER TO PRIVILEGE_CHECKS_USER = 'priv_repl'@'%.example.com' FOR CHANNEL 'channel_1'; 
mysql> START SLAVE FOR CHANNEL 'channel_1';

The user name and host name for the user account must follow the syntax
described in
https://dev.mysql.com/doc/refman/8.0/en/account-names.html, and the
user must not be an anonymous user (with a blank user name) or the
CURRENT_USER. The account must have the REPLICATION_APPLIER privilege,
plus the required privileges to execute the transactions replicated on
the channel. When you restart the replication channel, the privilege
checks are applied from that point on. For more information, see
https://dev.mysql.com/doc/refman/8.0/en/replication-privilege-checks.ht
ml.

MASTER_COMPRESSION_ALGORITHMS and MASTER_ZSTD_COMPRESSION_LEVEL
(available as of MySQL 8.0.18) enable control over the use of
compression for connections to the master:

o MASTER_COMPRESSION_ALGORITHMS specifies the permitted compression
  algorithms. The available algorithms are the same as for the
  protocol_compression_algorithms system variable. The default value is
  uncompressed.

  The value of MASTER_COMPRESSION_ALGORITHMS applies only if the
  slave_compressed_protocol system variable is disabled. If
  slave_compressed_protocol is enabled, it takes precedence over
  MASTER_COMPRESSION_ALGORITHMS and connections to the master use zlib
  compression if both master and slave support that algorithm.

o MASTER_ZSTD_COMPRESSION_LEVEL is the compression level to use for
  connections that use the zstd compression algorithm. The permitted
  levels are from 1 to 22, with larger values indicating increasing
  levels of compression. The default zstd compression level is 3. The
  compression level setting has no effect on connections that do not
  use zstd compression.

For more information, see
https://dev.mysql.com/doc/refman/8.0/en/connection-compression-control.
html.

The MASTER_SSL_xxx options and the MASTER_TLS_VERSION option specify
how the slave uses encryption and ciphers to secure the replication
connection. These options can be changed even on slaves that are
compiled without SSL support. They are saved to the master info
repository, but are ignored if the slave does not have SSL support
enabled. The MASTER_SSL_xxx and MASTER_TLS_VERSION options perform the
same functions as the --ssl-xxx and --tls-version client options
described in
https://dev.mysql.com/doc/refman/8.0/en/connection-options.html#encrypt
ed-connection-options. The correspondence between the two sets of
options, and the use of the MASTER_SSL_xxx and MASTER_TLS_VERSION
options to set up a secure connection, is explained in
https://dev.mysql.com/doc/refman/8.0/en/replication-solutions-encrypted
-connections.html.

*Important*:

To connect to the replication master using a user account that
authenticates with the caching_sha2_password plugin, you must either
set up a secure connection as described in
https://dev.mysql.com/doc/refman/8.0/en/replication-solutions-encrypted
-connections.html, or enable the unencrypted connection to support
password exchange using an RSA key pair. The caching_sha2_password
authentication plugin is the default for new users created from MySQL
8.0 (for details, see
https://dev.mysql.com/doc/refman/8.0/en/caching-sha2-pluggable-authenti
cation.html). If the user account that you create or use for
replication (as specified by the MASTER_USER option) uses this
authentication plugin, and you are not using a secure connection, you
must enable RSA key pair-based password exchange for a successful
connection.

To enable RSA key pair-based password exchange, specify either the
MASTER_PUBLIC_KEY_PATH or the GET_MASTER_PUBLIC_KEY=1 option. Either of
these options provides the RSA public key to the slave:

o MASTER_PUBLIC_KEY_PATH indicates the path name to a file containing a
  slave-side copy of the public key required by the master for RSA key
  pair-based password exchange. The file must be in PEM format. This
  option applies to slaves that authenticate with the sha256_password
  or caching_sha2_password authentication plugin. (For sha256_password,
  MASTER_PUBLIC_KEY_PATH can be used only if MySQL was built using
  OpenSSL.)

o GET_MASTER_PUBLIC_KEY indicates whether to request from the master
  the public key required for RSA key pair-based password exchange.
  This option applies to slaves that authenticate with the
  caching_sha2_password authentication plugin. For connections by
  accounts that authenticate using this plugin, the master does not
  send the public key unless requested, so it must be requested or
  specified in the client. If MASTER_PUBLIC_KEY_PATH is given and
  specifies a valid public key file, it takes precedence over
  GET_MASTER_PUBLIC_KEY.

The MASTER_HEARTBEAT_PERIOD, MASTER_CONNECT_RETRY, and
MASTER_RETRY_COUNT options control how the slave recognizes that the
connection to the master has been lost and makes attempts to reconnect.

o The slave_net_timeout system variable specifies the number of seconds
  that the slave waits for either more data or a heartbeat signal from
  the master, before the slave considers the connection broken, aborts
  the read, and tries to reconnect. The default value is 60 seconds
  (one minute).

o The heartbeat interval, which stops the connection timeout occurring
  in the absence of data if the connection is still good, is controlled
  by the MASTER_HEARTBEAT_PERIOD option. A heartbeat signal is sent to
  the slave after that number of seconds, and the waiting period is
  reset whenever the master's binary log is updated with an event.
  Heartbeats are therefore sent by the master only if there are no
  unsent events in the binary log file for a period longer than this.
  The heartbeat interval interval is a decimal value having the range 0
  to 4294967 seconds and a resolution in milliseconds; the smallest
  nonzero value is 0.001. Setting interval to 0 disables heartbeats
  altogether. The heartbeat interval defaults to half the value of the
  slave_net_timeout system variable. It is recorded in the master info
  log and shown in the replication_connection_configuration Performance
  Schema table. Issuing RESET SLAVE resets the heartbeat interval to
  the default value.

  Note that a change to the value or default setting of
  slave_net_timeout does not automatically change the heartbeat
  interval, whether that has been set explicitly or is using a
  previously calculated default. A warning is issued if you set
  @@GLOBAL.slave_net_timeout to a value less than that of the current
  heartbeat interval. If slave_net_timeout is changed, you must also
  issue CHANGE MASTER TO to adjust the heartbeat interval to an
  appropriate value so that the heartbeat signal occurs before the
  connection timeout. If you do not do this, the heartbeat signal has
  no effect, and if no data is received from the master, the slave can
  make repeated reconnection attempts, creating zombie dump threads.

o If the slave does need to reconnect, the first retry occurs
  immediately after the timeout. MASTER_CONNECT_RETRY specifies the
  interval between reconnection attempts, and MASTER_RETRY_COUNT limits
  the number of reconnection attempts. If both the default settings are
  used, the slave waits 60 seconds between reconnection attempts
  (MASTER_CONNECT_RETRY=60), and keeps attempting to reconnect at this
  rate for 60 days (MASTER_RETRY_COUNT=86400). These values are
  recorded in the master info log and shown in the
  replication_connection_configuration Performance Schema table.
  MASTER_RETRY_COUNT supersedes the --master-retry-count server startup
  option.

MASTER_DELAY specifies how many seconds behind the master the slave
must lag. An event received from the master is not executed until at
least interval seconds later than its execution on the master. The
default is 0. An error occurs if interval is not a nonnegative integer
in the range from 0 to 231−1. For more information, see
https://dev.mysql.com/doc/refman/8.0/en/replication-delayed.html.

A CHANGE MASTER TO statement employing the MASTER_DELAY option can be
executed on a running slave when the slave SQL thread is stopped.

MASTER_BIND is for use on replication slaves having multiple network
interfaces, and determines which of the slave's network interfaces is
chosen for connecting to the master.

The address configured with this option, if any, can be seen in the
Master_Bind column of the output from SHOW SLAVE STATUS. In the master
info repository table mysql.slave_master_info, the value can be seen as
the Master_bind column.

The ability to bind a replication slave to a specific network interface
is also supported by NDB Cluster.

MASTER_LOG_FILE and MASTER_LOG_POS are the coordinates at which the
slave I/O thread should begin reading from the master the next time the
thread starts. RELAY_LOG_FILE and RELAY_LOG_POS are the coordinates at
which the slave SQL thread should begin reading from the relay log the
next time the thread starts. If you specify either of MASTER_LOG_FILE
or MASTER_LOG_POS, you cannot specify RELAY_LOG_FILE or RELAY_LOG_POS.
If you specify either of MASTER_LOG_FILE or MASTER_LOG_POS, you also
cannot specify MASTER_AUTO_POSITION = 1 (described later in this
section). If neither of MASTER_LOG_FILE or MASTER_LOG_POS is specified,
the slave uses the last coordinates of the slave SQL thread before
CHANGE MASTER TO was issued. This ensures that there is no
discontinuity in replication, even if the slave SQL thread was late
compared to the slave I/O thread, when you merely want to change, say,
the password to use.

RELAY_LOG_FILE can use either an absolute or relative path, and uses
the same base name as MASTER_LOG_FILE. A CHANGE MASTER TO statement
employing RELAY_LOG_FILE, RELAY_LOG_POS, or both options can be
executed on a running slave when the slave SQL thread is stopped. Relay
logs are preserved if at least one of the slave SQL thread and the
slave I/O thread is running. If both threads are stopped, all relay log
files are deleted unless at least one of RELAY_LOG_FILE or
RELAY_LOG_POS is specified. Note that the Group Replication applier
channel (group_replication_applier) has no I/O thread, only a SQL
thread. For this channel, the relay logs are not preserved when the SQL
thread is stopped.

When MASTER_AUTO_POSITION = 1 is used with CHANGE MASTER TO, the slave
attempts to connect to the master using the GTID-based replication
protocol. This option can be used with CHANGE MASTER TO only if both
the slave SQL and slave I/O threads are stopped. Both the slave and the
master must have GTIDs enabled (GTID_MODE=ON, ON_PERMISSIVE, or
OFF_PERMISSIVE on the slave, and GTID_MODE=ON on the master).
Auto-positioning is used for the connection, so the coordinates
represented by MASTER_LOG_FILE and MASTER_LOG_POS are not used, and the
use of either or both of these options together with
MASTER_AUTO_POSITION = 1 causes an error. If multi-source replication
is enabled on the slave, you need to set the MASTER_AUTO_POSITION = 1
option for each applicable replication channel.

With MASTER_AUTO_POSITION = 1 set, in the initial connection handshake,
the slave sends a GTID set containing the transactions that it has
already received, committed, or both. The master responds by sending
all transactions recorded in its binary log whose GTID is not included
in the GTID set sent by the slave. This exchange ensures that the
master only sends the transactions with a GTID that the slave has not
already recorded or committed. If the slave receives transactions from
more than one master, as in the case of a diamond topology, the
auto-skip function ensures that the transactions are not applied twice.
For details of how the GTID set sent by the slave is computed, see
https://dev.mysql.com/doc/refman/8.0/en/replication-gtids-auto-position
ing.html.

If any of the transactions that should be sent by the master have been
purged from the master's binary log, or added to the set of GTIDs in
the gtid_purged system variable by another method, the master sends the
error ER_MASTER_HAS_PURGED_REQUIRED_GTIDS to the slave, and replication
does not start. The GTIDs of the missing purged transactions are
identified and listed in the master's error log in the warning message
ER_FOUND_MISSING_GTIDS. Also, if during the exchange of transactions it
is found that the slave has recorded or committed transactions with the
master's UUID in the GTID, but the master itself has not committed
them, the master sends the error ER_SLAVE_HAS_MORE_GTIDS_THAN_MASTER to
the slave and replication does not start. For information on how to
handle these situations, see
https://dev.mysql.com/doc/refman/8.0/en/replication-gtids-auto-position
ing.html.

You can see whether replication is running with auto-positioning
enabled by checking the Performance Schema
replication_connection_status table or the output of SHOW SLAVE STATUS.
Disabling the MASTER_AUTO_POSITION option again makes the slave revert
to file-based replication, in which case you must also specify one or
both of the MASTER_LOG_FILE or MASTER_LOG_POS options.

IGNORE_SERVER_IDS takes a comma-separated list of 0 or more server IDs.
Events originating from the corresponding servers are ignored, with the
exception of log rotation and deletion events, which are still recorded
in the relay log.

In circular replication, the originating server normally acts as the
terminator of its own events, so that they are not applied more than
once. Thus, this option is useful in circular replication when one of
the servers in the circle is removed. Suppose that you have a circular
replication setup with 4 servers, having server IDs 1, 2, 3, and 4, and
server 3 fails. When bridging the gap by starting replication from
server 2 to server 4, you can include IGNORE_SERVER_IDS = (3) in the
CHANGE MASTER TO statement that you issue on server 4 to tell it to use
server 2 as its master instead of server 3. Doing so causes it to
ignore and not to propagate any statements that originated with the
server that is no longer in use.

If IGNORE_SERVER_IDS contains the server's own ID and the server was
started with the --replicate-same-server-id option enabled, an error
results.

*Note*:

When global transaction identifiers (GTIDs) are used for replication,
transactions that have already been applied are automatically ignored,
so the IGNORE_SERVER_IDS function is not required and is deprecated. If
gtid_mode=ON is set for the server, a deprecation warning is issued if
you include the IGNORE_SERVER_IDS option in a CHANGE MASTER TO
statement.

The master info repository and the output of SHOW SLAVE STATUS provide
the list of servers that are currently ignored. For more information,
see https://dev.mysql.com/doc/refman/8.0/en/slave-logs-status.html, and
[HELP SHOW SLAVE STATUS].

If a CHANGE MASTER TO statement is issued without any IGNORE_SERVER_IDS
option, any existing list is preserved. To clear the list of ignored
servers, it is necessary to use the option with an empty list:

CHANGE MASTER TO IGNORE_SERVER_IDS = ();

RESET SLAVE ALL clears IGNORE_SERVER_IDS.

*Note*:

A deprecation warning is issued if SET GTID_MODE=ON is issued when any
channel has existing server IDs set with IGNORE_SERVER_IDS. Before
starting GTID-based replication, check for and clear all ignored server
ID lists on the servers involved. The SHOW_SLAVE_STATUS statement
displays the list of ignored IDs, if there is one. If you do receive
the deprecation warning, you can still clear a list after gtid_mode=ON
is set by issuing a CHANGE MASTER TO statement containing the
IGNORE_SERVER_IDS option with an empty list.

Invoking CHANGE MASTER TO causes the previous values for MASTER_HOST,
MASTER_PORT, MASTER_LOG_FILE, and MASTER_LOG_POS to be written to the
error log, along with other information about the slave's state prior
to execution.

CHANGE MASTER TO causes an implicit commit of an ongoing transaction.
See https://dev.mysql.com/doc/refman/8.0/en/implicit-commit.html.

From MySQL 5.7, the strict requirement to execute STOP SLAVE prior to
issuing any CHANGE MASTER TO statement (and START SLAVE afterward) is
removed. Instead of depending on whether the slave is stopped, the
behavior of CHANGE MASTER TO depends on the states of the slave SQL
thread and slave I/O threads; which of these threads is stopped or
running now determines the options that can or cannot be used with a
CHANGE MASTER TO statement at a given point in time. The rules for
making this determination are listed here:

o If the SQL thread is stopped, you can execute CHANGE MASTER TO using
  any combination that is otherwise allowed of RELAY_LOG_FILE,
  RELAY_LOG_POS, and MASTER_DELAY options, even if the slave I/O thread
  is running. No other options may be used with this statement when the
  I/O thread is running.

o If the I/O thread is stopped, you can execute CHANGE MASTER TO using
  any of the options for this statement (in any allowed combination)
  except RELAY_LOG_FILE, RELAY_LOG_POS, MASTER_DELAY, or
  MASTER_AUTO_POSITION = 1 even when the SQL thread is running.

o Both the SQL thread and the I/O thread must be stopped before issuing
  a CHANGE MASTER TO statement that employs MASTER_AUTO_POSITION = 1.

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

For more information, see
https://dev.mysql.com/doc/refman/8.0/en/replication-solutions-switch.ht
ml.

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 slave. A warning
(ER_WARN_OPEN_TEMP_TABLES_MUST_BE_ZERO) is now 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 slave when you have the
snapshot of the master and have recorded the master binary log
coordinates corresponding to the time of the snapshot. After loading
the snapshot into the slave to synchronize it with the master, you can
run CHANGE MASTER TO MASTER_LOG_FILE='log_name', MASTER_LOG_POS=log_pos
on the slave to specify the coordinates at which the slave should begin
reading the master binary log.

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

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

The next example shows an operation that is less frequently employed.
It is used when the slave has relay log files that you want it to
execute again for some reason. To do this, the master need not be
reachable. You need only use CHANGE MASTER TO and start the SQL thread
(START SLAVE SQL_THREAD):

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

URL: https://dev.mysql.com/doc/refman/8.0/en/change-master-to.html

