The terms master and slave have historically been used in replication, and
MariaDB has begun the process of adding primary and replica synonyms. The old
terms will continue to be used to maintain backward compatibility - see
MDEV-18777 to follow progress on this effort.

Syntax
------

CHANGE MASTER ['connection_name'] TO master_def  [, master_def] ... 
 [FOR CHANNEL 'channel_name']

master_def:
  MASTER_BIND = 'interface_name'
 | MASTER_HOST = 'host_name'
 | MASTER_USER = 'user_name'
 | MASTER_PASSWORD = 'password'
 | MASTER_PORT = port_num
 | MASTER_CONNECT_RETRY = interval
 | MASTER_HEARTBEAT_PERIOD = interval
 | MASTER_LOG_FILE = 'master_log_name'
 | MASTER_LOG_POS = master_log_pos
 | RELAY_LOG_FILE = 'relay_log_name'
 | RELAY_LOG_POS = relay_log_pos
 | MASTER_DELAY = interval
 | 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_USE_GTID = {current_pos|slave_pos|no}
 | MASTER_DEMOTE_TO_SLAVE = bool
 | IGNORE_SERVER_IDS = (server_id_list)
 | DO_DOMAIN_IDS = ([N,..])
 | IGNORE_DOMAIN_IDS = ([N,..])

Description
-----------

The CHANGE MASTER statement sets the options that a replica uses to connect to
and replicate from a primary.

MariaDB starting with 10.7.0
----------------------------
The FOR CHANNEL keyword was added for MySQL compatibility. This is identical
to using the channel_name directly after CHANGE MASTER.

Multi-Source Replication
------------------------

If you are using multi-source replication, then you need to specify a
connection name when you execute CHANGE MASTER. There are two ways to do this:

* Setting the default_master_connection system variable prior to executing
CHANGE MASTER.
* Setting the connection_name parameter when executing CHANGE MASTER.

default_master_connection
-------------------------

SET default_master_connection = 'gandalf';
STOP SLAVE;
CHANGE MASTER TO 
 MASTER_PASSWORD='new3cret';
START SLAVE;

connection_name
---------------

STOP SLAVE 'gandalf';
CHANGE MASTER 'gandalf' TO 
 MASTER_PASSWORD='new3cret';
START SLAVE 'gandalf';

Options
-------

Connection Options
------------------

MASTER_USER
-----------

The MASTER_USER option for CHANGE MASTER defines the user account that the
replica will use to connect to the primary.

This user account will need the REPLICATION SLAVE privilege (or, from MariaDB
10.5.1, the REPLICATION REPLICA on the primary.

For example:

STOP SLAVE;
CHANGE MASTER TO
 MASTER_USER='repl',
 MASTER_PASSWORD='new3cret';
START SLAVE;

The maximum length of the MASTER_USER string is 96 characters until MariaDB
10.5, and 128 characters from MariaDB 10.6.

MASTER_PASSWORD
---------------

The MASTER_PASSWORD option for CHANGE MASTER defines the password that the
replica will use to connect to the primary as the user account defined by the
MASTER_USER option.

For example:

STOP SLAVE;
CHANGE MASTER TO 
 MASTER_PASSWORD='new3cret';
START SLAVE;

The maximum length of the MASTER_PASSWORD string is 32 characters. The
effective maximum length of the string depends on how many bytes are used per
character and can be up to 96 characters.

Due to MDEV-29994, the password can be silently truncated to 41 characters
when MariaDB is restarted. For this reason it is recommended to use a password
that is shorter than this.

MASTER_HOST
-----------

The MASTER_HOST option for CHANGE MASTER defines the hostname or IP address of
the primary.

If you set the value of the MASTER_HOST option to the empty string, then that
is not the same as not setting the option's value at all. If you set the value
of the MASTER_HOST option to the empty string, then the CHANGE MASTER command
will fail with an error. In MariaDB 5.3 and before, if you set the value of
the MASTER_HOST option to the empty string, then the CHANGE MASTER command
would succeed, but the subsequent START SLAVE command would fail.

For example:

STOP SLAVE;
CHANGE MASTER TO
 MASTER_HOST='dbserver1.example.com',
 MASTER_USER='repl',
 MASTER_PASSWORD='new3cret',
 MASTER_USE_GTID=slave_pos;
START SLAVE;

If you set the value of the MASTER_HOST option in a CHANGE MASTER command,
then the replica assumes that the primary is different from before, even if
you set the value of this option to the same value it had previously. In this
scenario, the replica will consider the old values for the primary's binary
log file name and position to be invalid for the new primary. As a side
effect, if you do not explicitly set the values of the MASTER_LOG_FILE and
MASTER_LOG_POS options in the statement, then the statement will be implicitly
appended with MASTER_LOG_FILE='' and MASTER_LOG_POS=4. However, if you enable
GTID mode for replication by setting the MASTER_USE_GTID option to some value
other than no in the statement, then these values will effectively be ignored
anyway.

Replicas cannot connect to primaries using Unix socket files or Windows named
pipes. The replica must connect to the primary using TCP/IP.

The maximum length of the MASTER_HOST string is 60 characters until MariaDB
10.5, and 255 characters from MariaDB 10.6.

MASTER_PORT
-----------

The MASTER_PORT option for CHANGE MASTER defines the TCP/IP port of the
primary.

For example:

STOP SLAVE;
CHANGE MASTER TO
 MASTER_HOST='dbserver1.example.com',
 MASTER_PORT=3307,
 MASTER_USER='repl',
 MASTER_PASSWORD='new3cret',
 MASTER_USE_GTID=slave_pos;
START SLAVE;

If you set the value of the MASTER_PORT option in a CHANGE MASTER command,
then the replica assumes that the primary is different from before, even if
you set the value of this option to the same value it had previously. In this
scenario, the replica will consider the old values for the primary's binary
log file name and position to be invalid for the new primary. As a side
effect, if you do not explicitly set the values of the MASTER_LOG_FILE and
MASTER_LOG_POS options in the statement, then the statement will be implicitly
appended with MASTER_LOG_FILE='' and MASTER_LOG_POS=4. However, if you enable
GTID mode for replication by setting the MASTER_USE_GTID option to some value
other than no in the statement, then these values will effectively be ignored
anyway.

Replicas cannot connect to primaries using Unix socket files or Windows named
pipes. The replica must connect to the primary using TCP/IP.

MASTER_CONNECT_RETRY
--------------------

The MASTER_CONNECT_RETRY option for CHANGE MASTER defines how many seconds
that the replica will wait between connection retries. The default is 60.

STOP SLAVE;
CHANGE MASTER TO 
 MASTER_CONNECT_RETRY=20;
START SLAVE;

The number of connection attempts is limited by the master_retry_count option.
It can be set either on the command-line or in a server option group in an
option file prior to starting up the server. For example:

[mariadb]
...
master_retry_count=4294967295

MASTER_BIND
-----------

The MASTER_BIND option for CHANGE MASTER is only supported by MySQL 5.6.2 and
later and by MySQL NDB Cluster 7.3.1 and later. This option is not supported
by MariaDB. See MDEV-19248 for more information.

The MASTER_BIND option for CHANGE MASTER can be used on replicas that have
multiple network interfaces to choose which network interface the replica will
use to connect to the primary.

MASTER_HEARTBEAT_PERIOD
-----------------------

The MASTER_HEARTBEAT_PERIOD option for CHANGE MASTER can be used to set the
interval in seconds between replication heartbeats. Whenever the primary's
binary log is updated with an event, the waiting period for the next heartbeat
is reset.

This option's interval argument has the following characteristics:

* It is a decimal value with a range of 0 to 4294967 seconds.
* It has a resolution of hundredths of a second.
* Its smallest valid non-zero value is 0.001.
* Its default value is the value of the slave_net_timeout system variable
divided by 2.
* If it's set to 0, then heartbeats are disabled.

Heartbeats are sent by the primary only if there are no unsent events in the
binary log file for a period longer than the interval.

If the RESET SLAVE statement is executed, then the heartbeat interval is reset
to the default.

If the slave_net_timeout system variable is set to a value that is lower than
the current heartbeat interval, then a warning will be issued.

TLS Options
-----------

The TLS options are used for providing information about TLS. The options can
be set even on replicas that are compiled without TLS support. The TLS options
are saved to either the default master.info file or the file that is
configured by the master_info_file option, but these TLS options are ignored
unless the replica supports TLS.

See Replication with Secure Connections for more information.

MASTER_SSL
----------

The MASTER_SSL option for CHANGE MASTER tells the replica whether to force TLS
for the connection. The valid values are 0 or 1. Required to be set to 1 for
the other MASTER_SSL* options to have any effect.

For example:

STOP SLAVE;
CHANGE MASTER TO
 MASTER_SSL=1;
START SLAVE;

MASTER_SSL_CA
-------------

The MASTER_SSL_CA option for CHANGE MASTER defines a path to a PEM file that
should contain one or more X509 certificates for trusted Certificate
Authorities (CAs) to use for TLS. This option requires that you use the
absolute path, not a relative path.

For example:

STOP SLAVE;
CHANGE MASTER TO
 MASTER_SSL_CERT='/etc/my.cnf.d/certificates/server-cert.pem',
 MASTER_SSL_KEY='/etc/my.cnf.d/certificates/server-key.pem',
 MASTER_SSL_CA='/etc/my.cnf.d/certificates/ca.pem',
 MASTER_SSL_VERIFY_SERVER_CERT=1;
START SLAVE;

See Secure Connections Overview: Certificate Authorities (CAs) for more
information.

The maximum length of MASTER_SSL_CA string is 511 characters.

MASTER_SSL_CAPATH
-----------------

The MASTER_SSL_CAPATH option for CHANGE MASTER defines a path to a directory
that contains one or more PEM files that should each contain one X509
certificate for a trusted Certificate Authority (CA) to use for TLS. This
option requires that you use the absolute path, not a relative path. The
directory specified by this option needs to be run through the openssl rehash
command.

For example:

STOP SLAVE;
CHANGE MASTER TO
 MASTER_SSL_CERT='/etc/my.cnf.d/certificates/server-cert.pem',
 MASTER_SSL_KEY='/etc/my.cnf.d/certificates/server-key.pem',
 MASTER_SSL_CAPATH='/etc/my.cnf.d/certificates/ca/',
 MASTER_SSL_VERIFY_SERVER_CERT=1;
START SLAVE;

See Secure Connections Overview: Certificate Authorities (CAs) for more
information.

The maximum length of MASTER_SSL_CA_PATH string is 511 characters.

MASTER_SSL_CERT
---------------

The MASTER_SSL_CERT option for CHANGE MASTER defines a path to the X509
certificate file to use for TLS. This option requires that you use the
absolute path, not a relative path.

For example:

STOP SLAVE;
CHANGE MASTER TO
 MASTER_SSL_CERT='/etc/my.cnf.d/certificates/server-cert.pem',
 MASTER_SSL_KEY='/etc/my.cnf.d/certificates/server-key.pem',
 MASTER_SSL_CA='/etc/my.cnf.d/certificates/ca.pem',
 MASTER_SSL_VERIFY_SERVER_CERT=1;
START SLAVE;

The maximum length of MASTER_SSL_CERT string is 511 characters.

MASTER_SSL_CRL
--------------

The MASTER_SSL_CRL option for CHANGE MASTER defines a path to a PEM file that
should contain one or more revoked X509 certificates to use for TLS. This
option requires that you use the absolute path, not a relative path.

This option is only supported if the server was built with OpenSSL. If the
server was built with yaSSL, then this option is not supported. See TLS and
Cryptography Libraries Used by MariaDB for more information about which
libraries are used on which platforms.

For example:

STOP SLAVE;
CHANGE MASTER TO
 MASTER_SSL_CERT='/etc/my.cnf.d/certificates/server-cert.pem',
 MASTER_SSL_KEY='/etc/my.cnf.d/certificates/server-key.pem',
 MASTER_SSL_CA='/etc/my.cnf.d/certificates/ca.pem',
 MASTER_SSL_VERIFY_SERVER_CERT=1,
 MASTER_SSL_CRL='/etc/my.cnf.d/certificates/crl.pem';
START SLAVE;

See Secure Connections Overview: Certificate Revocation Lists (CRLs) for more
information.

The maximum length of MASTER_SSL_CRL string is 511 characters.

MASTER_SSL_CRLPATH
------------------

The MASTER_SSL_CRLPATH option for CHANGE MASTER defines a path to a directory
that contains one or more PEM files that should each contain one revoked X509
certificate to use for TLS. This option requires that you use the absolute
path, not a relative path. The directory specified by this variable needs to
be run through the openssl rehash command.

This option is only supported if the server was built with OpenSSL. If the
server was built with yaSSL, then this option is not supported. See TLS and
Cryptography Libraries Used by MariaDB for more information about which
libraries are used on which platforms.

For example:

STOP SLAVE;
CHANGE MASTER TO
 MASTER_SSL_CERT='/etc/my.cnf.d/certificates/server-cert.pem',
 MASTER_SSL_KEY='/etc/my.cnf.d/certificates/server-key.pem',
 MASTER_SSL_CA='/etc/my.cnf.d/certificates/ca.pem',
 MASTER_SSL_VERIFY_SERVER_CERT=1,
 MASTER_SSL_CRLPATH='/etc/my.cnf.d/certificates/crl/';
START SLAVE;

See Secure Connections Overview: Certificate Revocation Lists (CRLs) for more
information.

The maximum length of MASTER_SSL_CRL_PATH string is 511 characters.

MASTER_SSL_KEY
--------------

The MASTER_SSL_KEY option for CHANGE MASTER defines a path to a private key
file to use for TLS. This option requires that you use the absolute path, not
a relative path.

For example:

STOP SLAVE;
CHANGE MASTER TO
 MASTER_SSL_CERT='/etc/my.cnf.d/certificates/server-cert.pem',
 MASTER_SSL_KEY='/etc/my.cnf.d/certificates/server-key.pem',
 MASTER_SSL_CA='/etc/my.cnf.d/certificates/ca.pem',
 MASTER_SSL_VERIFY_SERVER_CERT=1;
START SLAVE;

The maximum length of MASTER_SSL_KEY string is 511 characters.

MASTER_SSL_CIPHER
-----------------
