Replication can be controlled through the SQL interface. This section discusses statements for managing slave replication servers. Replication Master SQL discusses statements for managing master servers.
CHANGE MASTER TO master_def [, master_def] ... master_def = MASTER_HOST = 'host_name' | MASTER_USER = 'user_name' | MASTER_PASSWORD = 'password' | MASTER_PORT = port_num | MASTER_CONNECT_RETRY = count | 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_SSL = {0|1} | MASTER_SSL_CA = 'ca_file_name' | MASTER_SSL_CAPATH = 'ca_directory_name' | MASTER_SSL_CERT = 'cert_file_name' | MASTER_SSL_KEY = 'key_file_name' | MASTER_SSL_CIPHER = 'cipher_list'
Changes the parameters that the slave server uses for connecting to and communicating with the master server. The possible master_def values are shown above.
The relay log options (RELAY_LOG_FILE and RELAY_LOG_POS) are available beginning with MySQL 4.0.
The SSL options (MASTER_SSL, MASTER_SSL_CA, MASTER_SSL_CAPATH, MASTER_SSL_CERT, MASTER_SSL_KEY, and MASTER_SSL_CIPHER) are available beginning with MySQL 4.1.1. You can change these options even on slaves that are compiled without SSL support. They will be saved to the master.info file but ignored until you use a server that has SSL support enabled.
For example:
mysql> CHANGE MASTER TO -> MASTER_HOST='master2.mycompany.com', -> MASTER_USER='replication', -> MASTER_PASSWORD='bigs3cret', -> MASTER_PORT=3306, -> MASTER_LOG_FILE='master2-bin.001', -> MASTER_LOG_POS=4, -> MASTER_CONNECT_RETRY=10; mysql> CHANGE MASTER TO -> RELAY_LOG_FILE='slave-relay-bin.006', -> RELAY_LOG_POS=4025;
MASTER_USER, MASTER_PASSWORD, MASTER_SSL, MASTER_SSL_CA, MASTER_SSL_CAPATH, MASTER_SSL_CERT, MASTER_SSL_KEY, and MASTER_SSL_CIPHER are information for the slave to be able to connect to its master. If you don't specify some of these informations, the non-specified informations will keep their old value. For example, if the password to connect to your MySQL master has changed, you just need to issue
mysql> STOP SLAVE; -- if replication was running mysql> CHANGE MASTER TO MASTER_PASSWORD='new3cret'; mysql> START SLAVE; -- if you want to restart replication
to tell the slave about the new password; no need to specify the information which did not change (host, port, user etc).
MASTER_HOST, MASTER_PORT are the hostname or IP adress of the master host, and its TCP port. Note that if MASTER_HOST is equal to localhost, then, like in other parts of MySQL, the port may be ignored (if Unix sockets can be used for example).
If you specify MASTER_HOST or MASTER_PORT, the slave will assume that the master server is different than before (even if you specify a host or port value value that is the same as the current value.) In this case, the old values of master binlog name and position are considered no longer applicable, so if you do not specify MASTER_LOG_FILE and MASTER_LOG_POS in the command, MASTER_LOG_FILE="" and MASTER_LOG_POS=4 are silently appended to it.
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. If you specify any of them, you can't specify RELAY_LOG_FILE or RELAY_LOG_POS. If none of MASTER_LOG_FILE and MASTER_LOG_POS was specified, then the last coordinates of the slave SQL thread before CHANGE MASTER was issued, are used. This ensures that replication has no discontinuity, even if the slave SQL thread was late compared to the slave I/O thread, when you just want to change, say, the password to use. This safe behavior was introduced starting from MySQL 4.0.17 and 4.1.1. (Before these versions, the used coordinates were the last coordinates of the slave I/O thread before CHANGE MASTER was issued, which caused the SQL thread to sometimes lose some events from the master, thus breaking replication.)
CHANGE MASTER deletes all relay logs (and starts a new one), unless you specified RELAY_LOG_FILE or RELAY_LOG_POS (in that case relay logs will be kept; since MySQL 4.1.1 the RELAY_LOG_PURGE global variable will silently be set to 0). CHANGE MASTER TO updates master.info and relay-log.info.
CHANGE MASTER is useful for setting up a slave when you have the snapshot of the master and have recorded the log and the offset on the master that the snapshot corresponds to. You can run CHANGE MASTER TO MASTER_LOG_FILE="log_name_on_master", MASTER_LOG_POS=log_offset_on_master on the slave after restoring the snapshot.
The first example above (CHANGE MASTER TO MASTER_HOST="master2.mycompany.com" etc) changes the master and master's binlog coordinates. This is when you want the slave to replicate the master. The second example, less frequently used, is when the slave has relay logs which, for some reason, you want the slave to execute again; to do this the master needn't be reachable, you just have to do CHANGE MASTER TO and start the SQL thread (START SLAVE SQL_THREAD). You can even use this out of a replication setup, on a standalone, slave-of-nobody server, to recover after a crash. Suppose your server has crashed and you have restored a backup. You want to replay the server's own binlogs (not relay logs, but regular binary logs), supposedly named myhost-bin.*. First make a backup copy of these binlogs in some safe place, in case you don't exactly follow the procedure below and accidentally have the server purge the binlogs. If using MySQL 4.1.1 or newer, do SET GLOBAL RELAY_LOG_PURGE=0 for additional safety. Then start the server without log-bin, with a new (different from before) server ID, with relay-log=myhost-bin (to make the server believe that these regular binlogs are relay logs) and skip-slave-start, then issue these statements:
mysql> CHANGE MASTER TO -> RELAY_LOG_FILE='myhost-bin.153', -> RELAY_LOG_POS=410, -> MASTER_HOST='some_dummy_string'; mysql> START SLAVE SQL_THREAD;
Then the server will read and execute its own binlogs, thus achieving crash recovery. Once the recovery is finished, run STOP SLAVE, shutdown the server, delete master.info and relay-log.info, and restart the server with its original options. For the moment, specifying MASTER_HOST (even with a dummy value) is compulsory to make the server think it is a slave, and giving the server a new, different from before, server ID is also compulsory otherwise the server will see events with its ID and think it is in a circular replication setup and skip the events, which is unwanted. In the future we plan to add options to get rid of these small constraints.
LOAD DATA FROM MASTER
Takes a snapshot of the master and copies it to the slave. Updates the values of MASTER_LOG_FILE and MASTER_LOG_POS so that the slave will start replicating from the correct position. Will honor table and database exclusion rules specified with replicate-* options.
Use of this statement is subject to the following conditions:
It works only with MyISAM tables.
It acquires a global read lock on the master while taking the snapshot, which prevents updates on the master during the load operation.
In the future, it is planned to make this statement work with InnoDB tables and to remove the need for global read lock by using the non-blocking online backup feature.
If you are loading big tables, you may have to increase the values of net_read_timeout and net_write_timeout on both your master and slave. See SHOW VARIABLES.
Note that LOAD DATA FROM MASTER does NOT copy any tables from the mysql database. This is to make it easy to have different users and privileges on the master and the slave.
This statement requires that the replication account that is used to connect to the master have RELOAD and SUPER privileges on the master, SELECT privileges on all master's tables you want to load. All master's tables on which the user has no SELECT privilege will be ignored by LOAD DATA FROM MASTER; this is because the master will hide them to the user: LOAD DATA FROM MASTER calls SHOW DATABASES to know the master databases to load, but SHOW DATABASES returns only databases on which the user has some privilege. See Show database info. On the slave's side, the user which issues LOAD DATA FROM MASTER should have grants to drop and create the involved databases and tables.
LOAD TABLE tbl_name FROM MASTER
Downloads a copy of the table from master to the slave. This statement is implemented mainly for debugging of LOAD DATA FROM MASTER. Requires that the account used for connecting to the master server have RELOAD and SUPER privileges on the master, and SELECT on the master table to load. On the slave's side, the user which issues LOAD TABLE FROM MASTER should have grants to drop and create the table. Please read the timeout notes in the description of LOAD DATA FROM MASTER above; they apply here, too. Please also read the limitations of LOAD DATA FROM MASTER above, they apply too (for example, LOAD TABLE FROM MASTER only works for MyISAM tables).
SELECT MASTER_POS_WAIT('master_log_file', master_log_pos)
This is a function, not a command. It is used to ensure that the slave has reached (read and executed up to) a given position in the master's binlog. See Miscellaneous functions for a full description.
RESET SLAVE
Makes the slave forget its replication position in the master's binlogs. This statement is meant to be used for a clean start: it deletes the master.info and relay-log.info files, all the relay logs, and starts a new relay log. Note: All relay logs are deleted, even if they had not been totally executed by the slave SQL thread. (This is a condition likely to exist on a replication slave that is highly loaded, or if you have issued a STOP SLAVE statement.) Connection information stored in the master.info file is immediately reset to the values specified in the corresponding startup options, if they were specified. This information includes values such as master host, master port, master user, and master password. If the slave SQL thread was in the middle of replicating temporary tables when it was stopped, and RESET SLAVE is issued, these replicated temporary tables are deleted on the slave.
This statement was named FLUSH SLAVE before MySQL 3.23.26.
SET GLOBAL SQL_SLAVE_SKIP_COUNTER = n
Skip the next n events from the master. This is useful for recovering from replication stops caused by a statement.
This statement is valid only when the slave thread is not running. Otherwise, it produces an error.
Before MySQL 4.0, omit the GLOBAL keyword from the statement.
SHOW SLAVE STATUS
Provides status information on essential parameters of the slave threads. If you issue this statement using the mysql client, you can use a \G statement terminator rather than semicolon to get a more readable vertical layout:
mysql> SHOW SLAVE STATUS\G *************************** 1. row *************************** Slave_IO_State: Waiting for master to send event Master_Host: localhost Master_User: root Master_Port: 3306 Connect_Retry: 3 Master_Log_File: gbichot-bin.005 Read_Master_Log_Pos: 79 Relay_Log_File: gbichot-relay-bin.005 Relay_Log_Pos: 548 Relay_Master_Log_File: gbichot-bin.005 Slave_IO_Running: Yes Slave_SQL_Running: Yes Replicate_Do_DB: Replicate_Ignore_DB: Last_Errno: 0 Last_Error: Skip_Counter: 0 Exec_Master_Log_Pos: 79 Relay_Log_Space: 552 Until_Condition: None Until_Log_File: Until_Log_Pos: 0 Master_SSL_Allowed: No Master_SSL_CA_File: Master_SSL_CA_Path: Master_SSL_Cert: Master_SSL_Cipher: Master_SSL_Key: Seconds_Behind_Master: 8
Depending on your version of MySQL, you may not see all the fields just shown. In particular, several fields are present only as of MySQL 4.1.1.
The fields displayed by SHOW SLAVE STATUS have the following meanings:
Slave_IO_State | A copy of the State column of the output of SHOW PROCESSLIST for the slave I/O thread; will tell you if this thread is trying to connect to the master, waiting for events from the master, reconnecting to the master, etc. Possible states are listed in Replication Implementation Details. Looking at this column is necessary because, for example, the thread can be running but unsuccessfully trying to connect to the master: only this column will make you aware of the connection problem. On the opposite, the state of the SQL thread is not copied, because things are simpler for this thread: if it's running, there is no problem; if it's not, you will find the error in the Last_Error column (described below). This field is present beginning with MySQL 4.1.1. |
Master_Host | The current master host. |
Master_User | The current user used to connect to the master. |
Master_Port | The current master port. |
Connect_Retry | The current value of master-connect-retry. |
Master_Log_File | The name of the master's binlog file from which the I/O thread is currently reading. |
Read_Master_Log_Pos | The position which the I/O thread has read up to in this master's binlog. |
Relay_Log_File | The name of the relay log file from which the SQL thread is currently reading and executing. |
Relay_Log_Pos | The position which the SQL thread has read and executed up to in this relay log. |
Relay_Master_Log_File | The name of the master's binlog file that contains the last event executed by the SQL thread. |
Slave_IO_Running | Tells whether or not the I/O thread is started. |
Slave_SQL_Running | Tells whether or not the SQL thread is started. |
Replicate_Do_DB, Replicate_Ignore_DB | The lists of the databases that were specified with the --replicate-do-db and --replicate-ignore-db options, if any |
Replicate_Do_Table, Replicate_Ignore_Table, Replicate_Wild_Do_Table, Replicate_Wild_Ignore_Table | The lists of tables that were specified with the --replicate-do-table, --replicate-ignore-table, --replicate-wild-do-table, and --replicate-wild-ignore_table options, if any These fields are present beginning with MySQL 4.1.1. |
Last_Errno | The error number returned by the most recently executed query. A value of 0 means ``no error''. |
Last_Error |
The error message returned by the most recently executed query.
For example:
Last_Errno: 1051 Last_Error: error 'Unknown table 'z'' on query 'drop table z'The message indicates that the table z existed on the master and was dropped there, but it did not exist on the slave, so DROP TABLE failed on the slave. (This might occur if you forgot to copy the table to the slave when setting up replication.) The empty string means ``no error''. If the Last_Error value is not empty, it will also appear as a message in the slave's error log. |
Skip_Counter | The last used value for SQL_SLAVE_SKIP_COUNTER. |
Exec_Master_Log_Pos | The position in the master's binlog (Relay_Master_Log_File) of the last event executed by the SQL thread. ((Relay_Master_Log_File,Exec_Master_Log_Pos) in the master's binlog corresponds to (Relay_Log_File,Relay_Log_Pos) in the relay log). |
Relay_Log_Space | The total combined size of all existing relay logs. |
Until_Condition, Until_Log_File, Until_Log_Pos |
The values specified in the UNTIL clause of the START SLAVE
statement.
Until_Condition has these values:
|
Master_SSL_Allowed, Master_SSL_CA_File, Master_SSL_CA_Path, Master_SSL_Cert, Master_SSL_Cipher, Master_SSL_Key |
These fields show the
The SSL parameters used by the slave to connect to the master, if any.
Master_SSL_Allowed has these values:
|
Seconds_Behind_Master | The number of seconds that have elapsed since the timestamp of the last master's event executed by the slave SQL thread. Will be NULL when no event has been executed yet, or after CHANGE MASTER and RESET SLAVE. This column can be used to know how ``late'' your slave is. It will work even though your master and slave don't have identical clocks. This field is present beginning with MySQL 4.1.1. |
START SLAVE [thread_name [, thread_name] ... ] START SLAVE [SQL_THREAD] UNTIL MASTER_LOG_FILE = 'log_name', MASTER_LOG_POS = log_pos START SLAVE [SQL_THREAD] UNTIL RELAY_LOG_FILE = 'log_name', RELAY_LOG_POS = log_pos thread_name = IO_THREAD | SQL_THREAD
START SLAVE with no options starts both of the slave threads. The I/O thread reads queries from the master server and stores them in the relay log. The SQL thread reads the relay log and executes the queries. Note that if START SLAVE succeeds in starting the slave threads it will return without any error. But even in that case it might be that slave threads start and then later stop (because they don't manage to connect to the master or read his binlogs or any other problem). START SLAVE will not warn you about this. You must check your slave's error log for error messages generated by the slave threads, or check that these are running fine with SHOW SLAVE STATUS.
START SLAVE requires the SUPER privilege.
As of MySQL 4.0.2, you can add IO_THREAD or SQL_THREAD options to the statement to name which of the threads to start.
As of MySQL 4.1.1, an UNTIL clause may be added to specify that the slave should start until the SQL thread reaches a given point in the master binlogs or in the slave relay logs. When the SQL thread reaches that point, it stops. If the SQL_THREAD option is specified in the statement, it starts only the SQL thread. Otherwise, it starts both slave threads. If the SQL thread is already running, the UNTIL clause is ignored and a warning is issued.
With an UNTIL clause, you must specify both a log filename and position. Do not mix master and relay log options.
Any UNTIL condition is reset by a subsequent STOP SLAVE statement, or a START SLAVE statement that includes no UNTIL clause, or a server restart.
The UNTIL clause can be useful for debugging replication, or to cause replication to proceed until just before the point where you want to avoid having the slave replicated a statement. For example, if an unwise DROP TABLE statement was executed on the master, you can use UNTIL to tell the slave to execute up to that point but no farther. To find what the event is, use mysqlbinlog with the master logs or relay logs, or by using a SHOW BINLOG EVENTS statement.
If you are using UNTIL to have the slave process replicated queries in sections, it is recommended that you start the slave with the --skip-slave-start option to prevent the SQL thread from running when the slave starts. It's probably best to use this option in an option file rather than on the command line, so that an unexpected server restart does not cause it to be forgotten.
The SHOW SLAVE STATUS statement includes output fields that display the current values of the UNTIL condition.
This command is called SLAVE START before MySQL 4.0.5. For the moment, SLAVE START is still accepted for backward compatibility, but is deprecated.
STOP SLAVE [thread_name [, thread_name] ... ] thread_name = IO_THREAD | SQL_THREAD
Stops the slave threads. STOP SLAVE requires the SUPER privilege.
Like START SLAVE, this statement may be used with the IO_THREAD and SQL_THREAD options to name the thread or threads to stop.
This command is called SLAVE STOP before MySQL 4.0.5. For the moment, SLAVE STOP is still accepted for backward compatibility, but is deprecated.