
The MASTER_SSL_CIPHER option for CHANGE MASTER defines the list of permitted
ciphers or cipher suites to use for TLS. Besides cipher names, if MariaDB was
compiled with OpenSSL, this option could be set to "SSLv3" or "TLSv1.2" to
allow all SSLv3 or all TLSv1.2 ciphers. Note that the TLSv1.3 ciphers cannot
be excluded when using OpenSSL, even by using this option. See Using TLSv1.3
for details.

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_CIPHER='TLSv1.2';
START SLAVE;

The maximum length of MASTER_SSL_CIPHER string is 511 characters.

MASTER_SSL_VERIFY_SERVER_CERT
-----------------------------

The MASTER_SSL_VERIFY_SERVER_CERT option for CHANGE MASTER enables server
certificate verification. This option is disabled by default prior to MariaDB
11.3.0, and enabled by default from MariaDB 11.3.0.

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: Server Certificate Verification for more
information.

Binary Log Options
------------------

These options are related to the binary log position on the primary.

MASTER_LOG_FILE
---------------

The MASTER_LOG_FILE option for CHANGE MASTER can be used along with
MASTER_LOG_POS to specify the coordinates at which the replica's I/O thread
should begin reading from the primary's binary logs the next time the thread
starts.

For example:

STOP SLAVE;
CHANGE MASTER TO
 MASTER_LOG_FILE='master2-bin.001',
 MASTER_LOG_POS=4;
START SLAVE;

The MASTER_LOG_FILE and MASTER_LOG_POS options cannot be specified if the
RELAY_LOG_FILE and RELAY_LOG_POS options were also specified.

The MASTER_LOG_FILE and MASTER_LOG_POS options are effectively ignored if you
enable GTID mode for replication by setting the MASTER_USE_GTID option to some
value other than no in the statement.

MASTER_LOG_POS
--------------

The MASTER_LOG_POS option for CHANGE MASTER can be used along with
MASTER_LOG_FILE to specify the coordinates at which the replica's I/O thread
should begin reading from the primary's binary logs the next time the thread
starts.

For example:

STOP SLAVE;
CHANGE MASTER TO
 MASTER_LOG_FILE='master2-bin.001',
 MASTER_LOG_POS=4;
START SLAVE;

The MASTER_LOG_FILE and MASTER_LOG_POS options cannot be specified if the
RELAY_LOG_FILE and RELAY_LOG_POS options were also specified.

The MASTER_LOG_FILE and MASTER_LOG_POS options are effectively ignored if you
enable GTID mode for replication by setting the MASTER_USE_GTID option to some
value other than no in the statement.

Relay Log Options
-----------------

These options are related to the relay log position on the replica.

RELAY_LOG_FILE
--------------

The RELAY_LOG_FILE option for CHANGE MASTER can be used along with the
RELAY_LOG_POS option to specify the coordinates at which the replica's SQL
thread should begin reading from the relay log the next time the thread starts.

The CHANGE MASTER statement usually deletes all relay log files. However, if
the RELAY_LOG_FILE and/or RELAY_LOG_POS options are specified, then existing
relay log files are kept.

When you want to change the relay log position, you only need to stop the
replica's SQL thread. The replica's I/O thread can continue running. The STOP
SLAVE and START SLAVE statements support the SQL_THREAD option for this
scenario. For example:

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

When the value of this option is changed, the metadata about the replica's SQL
thread's position in the relay logs will also be changed in the relay-log.info
file or the file that is configured by the relay_log_info_file system variable.

The RELAY_LOG_FILE and RELAY_LOG_POS options cannot be specified if the
MASTER_LOG_FILE and MASTER_LOG_POS options were also specified.

RELAY_LOG_POS
-------------

The RELAY_LOG_POS option for CHANGE MASTER can be used along with the
RELAY_LOG_FILE option to specify the coordinates at which the replica's SQL
thread should begin reading from the relay log the next time the thread starts.

The CHANGE MASTER statement usually deletes all relay log files. However, if
the RELAY_LOG_FILE and/or RELAY_LOG_POS options are specified, then existing
relay log files are kept.

When you want to change the relay log position, you only need to stop the
replica's SQL thread. The replica's I/O thread can continue running. The STOP
SLAVE and START SLAVE statements support the SQL_THREAD option for this
scenario. For example:

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

When the value of this option is changed, the metadata about the replica's SQL
thread's position in the relay logs will also be changed in the relay-log.info
file or the file that is configured by the relay_log_info_file system variable.

The RELAY_LOG_FILE and RELAY_LOG_POS options cannot be specified if the
MASTER_LOG_FILE and MASTER_LOG_POS options were also specified.

GTID Options
------------

MASTER_USE_GTID
---------------

The MASTER_USE_GTID option for CHANGE MASTER can be used to configure the
replica to use the global transaction ID (GTID) when connecting to a primary.
The possible values are:

* current_pos - Replicate in GTID mode and use gtid_current_pos as the
position to start downloading transactions from the primary. Deprecated from
MariaDB 10.10. Using to transition to primary can break the replication state
if the replica executes local transactions due to actively updating
gtid_current_pos with gtid_binlog_pos and gtid_slave_pos. Use the new, safe,
MASTER_DEMOTE_TO_SLAVE=<bool> option instead.
* slave_pos - Replicate in GTID mode and use gtid_slave_pos as the position to
start downloading transactions from the primary. From MariaDB 10.5.1,
replica_pos is an alias for slave_pos.
* no - Don't replicate in GTID mode.

For example:

STOP SLAVE;
CHANGE MASTER TO
 MASTER_USE_GTID = current_pos;
START SLAVE;

Or:

STOP SLAVE;
SET GLOBAL gtid_slave_pos='0-1-153';
CHANGE MASTER TO
 MASTER_USE_GTID = slave_pos;
START SLAVE;

MASTER_DEMOTE_TO_SLAVE
----------------------

MariaDB starting with 10.10
---------------------------
Used to transition a primary to become a replica. Replaces the old
MASTER_USE_GTID=current_pos with a safe alternative by forcing users to set
Using_Gtid=Slave_Pos and merging gtid_binlog_pos into gtid_slave_pos once at
CHANGE MASTER TO time. If gtid_slave_pos is more recent than gtid_binlog_pos
(as in the case of chain replication), the replication state should be
preserved.

For example:

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

Replication Filter Options
--------------------------

Also see Replication filters.

IGNORE_SERVER_IDS
-----------------

The IGNORE_SERVER_IDS option for CHANGE MASTER can be used to configure a
replica to ignore binary log events that originated from certain servers.
Filtered binary log events will not get logged to the replica’s relay log, and
they will not be applied by the replica.

The option's value can be specified by providing a comma-separated list of
server_id values. For example:

STOP SLAVE;
CHANGE MASTER TO 
 IGNORE_SERVER_IDS = (3,5);
START SLAVE;

If you would like to clear a previously set list, then you can set the value
to an empty list. For example:

STOP SLAVE;
CHANGE MASTER TO 
 IGNORE_SERVER_IDS = ();
START SLAVE;

DO_DOMAIN_IDS
-------------

The DO_DOMAIN_IDS option for CHANGE MASTER can be used to configure a replica
to only apply binary log events if the transaction's GTID is in a specific
gtid_domain_id value. Filtered binary log events will not get logged to the
replica’s relay log, and they will not be applied by the replica.

The option's value can be specified by providing a comma-separated list of
gtid_domain_id values. Duplicate values are automatically ignored. For example:

STOP SLAVE;
CHANGE MASTER TO 
 DO_DOMAIN_IDS = (1,2);
START SLAVE;

If you would like to clear a previously set list, then you can set the value
to an empty list. For example:

STOP SLAVE;
CHANGE MASTER TO 
 DO_DOMAIN_IDS = ();
START SLAVE;

The DO_DOMAIN_IDS option and the IGNORE_DOMAIN_IDS option cannot both be set
to non-empty values at the same time. If you want to set the DO_DOMAIN_IDS
option, and the IGNORE_DOMAIN_IDS option was previously set, then you need to
clear the value of the IGNORE_DOMAIN_IDS option. For example:

STOP SLAVE;
CHANGE MASTER TO 
 IGNORE_DOMAIN_IDS = (),
 DO_DOMAIN_IDS = (1,2);
START SLAVE;

The DO_DOMAIN_IDS option can only be specified if the replica is replicating
in GTID mode. Therefore, the MASTER_USE_GTID option must also be set to some
value other than no in order to use this option.

IGNORE_DOMAIN_IDS
-----------------

The IGNORE_DOMAIN_IDS option for CHANGE MASTER can be used to configure a
replica to ignore binary log events if the transaction's GTID is in a specific
gtid_domain_id value. Filtered binary log events will not get logged to the
replica’s relay log, and they will not be applied by the replica.

The option's value can be specified by providing a comma-separated list of
gtid_domain_id values. Duplicate values are automatically ignored. For example:

STOP SLAVE;
CHANGE MASTER TO 
 IGNORE_DOMAIN_IDS = (1,2);
START SLAVE;

If you would like to clear a previously set list, then you can set the value
to an empty list. For example:

STOP SLAVE;
CHANGE MASTER TO 
 IGNORE_DOMAIN_IDS = ();
START SLAVE;

The DO_DOMAIN_IDS option and the IGNORE_DOMAIN_IDS option cannot both be set
to non-empty values at the same time. If you want to set the IGNORE_DOMAIN_IDS
option, and the DO_DOMAIN_IDS option was previously set, then you need to
clear the value of the DO_DOMAIN_IDS option. For example:

STOP SLAVE;
CHANGE MASTER TO 
 DO_DOMAIN_IDS = (),
 IGNORE_DOMAIN_IDS = (1,2);
START SLAVE;

The IGNORE_DOMAIN_IDS option can only be specified if the replica is
replicating in GTID mode. Therefore, the MASTER_USE_GTID option must also be
set to some value other than no in order to use this option.

Delayed Replication Options
---------------------------

MASTER_DELAY
------------

The MASTER_DELAY option for CHANGE MASTER can be used to enable delayed
replication. This option specifies the time in seconds (at least) that a
replica should lag behind the primary up to a maximum value of 2147483647, or
about 68 years. Before executing an event, the replica will first wait, if
necessary, until the given time has passed since the event was created on the
primary. The result is that the replica will reflect the state of the primary
some time back in the past. The default is zero, no delay.

STOP SLAVE;
CHANGE MASTER TO 
 MASTER_DELAY=3600;
START SLAVE;

Changing Option Values
----------------------

If you don't specify a given option when executing the CHANGE MASTER
statement, then the option keeps its old value in most cases. Most of the
time, there is no need to specify the options that do not need to change. For
example, if the password for the user account that the replica uses to connect
to its primary has changed, but no other options need to change, then you can
just change the MASTER_PASSWORD option by executing the following commands:

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

There are some cases where options are implicitly reset, such as when the
MASTER_HOST and MASTER_PORT options are changed.

Option Persistence
------------------

The values of the MASTER_LOG_FILE and MASTER_LOG_POS options (i.e. the binary
log position on the primary) and most other options are written to either the
default master.info file or the file that is configured by the
master_info_file option. The replica's I/O thread keeps this binary log
position updated as it downloads events only when MASTER_USE_GTID option is
set to NO. Otherwise the file is not updated on a per event basis.

The master_info_file option 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_info_file=/mariadb/myserver1-master.info

The values of the RELAY_LOG_FILE and RELAY_LOG_POS options (i.e. the relay log
position) are written to either the default relay-log.info file or the file
that is configured by the relay_log_info_file system variable. The replica's
SQL thread keeps this relay log position updated as it applies events.

The relay_log_info_file system variable 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]
...
relay_log_info_file=/mariadb/myserver1-relay-log.info

GTID Persistence
----------------

If the replica is replicating binary log events that contain GTIDs, then the
replica's SQL thread will write every GTID that it applies to the
mysql.gtid_slave_pos table. This GTID can be inspected and modified through
the gtid_slave_pos system variable.

If the replica has the log_slave_updates system variable enabled and if the
replica has the binary log enabled, then every write by the replica's SQL
thread will also go into the replica's binary log. This means that GTIDs of
replicated transactions would be reflected in the value of the gtid_binlog_pos
system variable.

Creating a Replica from a Backup
--------------------------------

The CHANGE MASTER statement is useful for setting up a replica when you have a
backup of the primary and you also have the binary log position or GTID
position corresponding to the backup.

After restoring the backup on the replica, you could execute something like
this to use the binary log position:

CHANGE MASTER TO
 MASTER_LOG_FILE='master2-bin.001',
 MASTER_LOG_POS=4;
START SLAVE;
