The terms master and slave have historically been used in replication, but the
terms terms primary and replica are now preferred. The old terms are used
still used in parts of the documentation, and in MariaDB commands, although
MariaDB 10.5 has begun the process of renaming. The documentation process is
ongoing. 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_USER 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