Chapter 56. Replication Startup Options

On both the master and the slave you need to use the server-id option to establish a unique replication ID for each server. You should pick a unique integer in the range from 1 to 2^32 - 1 for each master and slave. Example: server-id=3

The options that you can use on the master server for controlling binary logging are all described in Binary log.

The following table describes the options you can use on slave servers. You can specify them on the command line or in an option file.

NOTE: Replication handles the following options in a special way:

If no master.info file exists when the slave server starts, it uses values for those options that are specified in option files or on the command line. This will occur when you start the server as a replication slave for the very first time, or you have run RESET SLAVE and shut down and restarted the slave server.

However, if the master.info file exists when the slave server starts, it uses the values in the file and IGNORES any values specified for those options in option files or on the command line.

Suppose you specify this option in your my.cnf file:

[mysqld]
master-host=this_host

The first time you start the server as a replication slave, it will read and use that option from the my.cnf file. The server will then record that value in the master.info file. The next time you start the server, it will read the master host value from the master.info file only. If you modify the my.cnf file to specify a different master host, it will have no effect. You must use CHANGE MASTER TO instead.

As of MySQL 4.1.1, the following options also are handled specially:

The master.info file includes the values corresponding to those options. In addition, the 4.1.1 file format includes as its first line the number of lines in the file. If you upgrade an older server to 4.1.1, the master.info will be upgraded to the new format automatically when the new server starts. (If you downgrade a 4.1.1 or newer server to a version older than 4.1.1, you should manually remove the first line before starting the older server for the first time.)

Because the server gives an existing master.info file precedence over the startup options just described, you might prefer not to use startup options for these values at all, and instead specify them by using the CHANGE MASTER TO statement. See CHANGE MASTER TO.

This example shows a more extensive use of startup options to configure a slave server:

[mysqld]
server-id=2
master-host=db-master.mycompany.com
master-port=3306
master-user=pertinax
master-password=freitag
master-connect-retry=60
report-host=db-slave.mycompany.com

The following list describes startup options for controlling replication:

--log-slave-updates Tells the slave to log the updates performed by its SQL thread to the slave's own binary log. Off by default. For this option to have any effect, the slave must be started with binary logging enabled (--log-bin option). --log-slave-updates is used when you want to chain replication servers. For example, you might want a setup like this:
    A -> B -> C
    
That is, A serves as the master for the slave B, and B serves as the master for the slave C. For this to work, where B is both a master and a slave, you must start B with the --log-slave-updates option. A and B must both be started with binary logging enabled.
--log-warnings Makes the slave print more messages about what it is doing. For example, it will warn you that it succeeded in reconnecting after a network/connection failure, and warn you about how each slave thread started. This option is not limited to replication use only. It produces warnings across a spectrum of server activities.
--master-host=host Specify the hostname or IP address of the master replication server. If this option is not given, the slave thread will not be started. The value in master.info takes precedence if it can be read. Probably a better name for this options would have been something like --bootstrap-master-host, but it is too late to change now.
--master-user=username The username of the account that the slave thread uses for authentication when connecting to the master. The account must have the REPLICATION SLAVE privilege (prior to MySQL 4.0.2, it must have the FILE privilege instead). If the master user is not set, user test is assumed. The value in master.info takes precedence if it can be read.
--master-password=password The password of the account that the slave thread uses for authentication when connecting to the master. If not set, an empty password is assumed. The value in master.info takes precedence if it can be read.
--master-port=port_number The port the master is listening on. If not set, the compiled setting of MYSQL_PORT is assumed. If you have not tinkered with configure options, this should be 3306. The value in master.info takes precedence if it can be read.
--master-connect-retry=seconds The number of seconds the slave thread sleeps before retrying to connect to the master in case the master goes down or the connection is lost. Default is 60. The value in master.info takes precedence if it can be read.
--master-info-file=filename Specifies the name to use for the file in which the slave records information about the master. The default name is mysql.info in the data directory.
--master-ssl , --master-ssl-ca=file_name , --master-ssl-capath=directory_name , --master-ssl-cert=file_name , --master-ssl-cipher=cipher_list , --master-ssl-key=file_name These options are used for setting up a secure replication connection to the master server using SSL. Their meanings are the same as the corresponding --ssl, --ssl-ca, --ssl-capath, --ssl-cert, --ssl-cipher, --ssl-key options described in SSL options. These options are operational as of MySQL 4.1.1.
--max-relay-log-size=# To rotate the relay log automatically. See SHOW VARIABLES.
--relay-log=filename To specify the location and name that should be used for relay logs. You can use this to have hostname-independant relay log names, or if your relay logs tend to be big (and you don't want to decrease max_relay_log_size) and you need to put them on some area different from the data directory, or if you want to increase speed by balancing load between disks.
--relay-log-index=filename To specify the location and name that should be used for the relay logs index file.
--relay-log-info-file=filename To give relay-log.info another name and/or to put it in another directory than the data directory.
--relay-log-purge=0|1 Disables/enables automatic purging of relay logs as soon as they are not needed any more. This is a global variable that can be dynamically changed with SET GLOBAL RELAY_LOG_PURGE=0|1. The default value is 1. This option is available as of MySQL 4.1.1.
--relay-log-space-limit=# To put an upper limit on the total size of all relay logs on the slave (a value of 0 means ``unlimited''). This is useful if you have a small hard disk on your slave machine. When the limit is reached, the I/O thread pauses (does not read the master's binlog) until the SQL thread has caught up and deleted some now unused relay logs. Note that this limit is not absolute: there are cases where the SQL thread needs more events to be able to delete; in that case the I/O thread will overgo the limit until deletion becomes possible. Not doing so would cause a deadlock (which happens before MySQL 4.0.13). Users should not set --relay-log-space-limit to less than twice the value of --max-relay-log-size (or --max-binlog-size if --max-relay-log-size is 0) because in that case there are chances that when the I/O thread waits for free space because --relay-log-space-limit is exceeded, the SQL thread has no relay log to purge and so cannot satisfy the I/O thread, forcing the I/O thread to temporarily ignore --relay-log-space-limit.
--replicate-do-table=db_name.table_name Tells the slave thread to restrict replication to the specified table. To specify more than one table, use the directive multiple times, once for each table. This will work for cross-database updates, in contrast to --replicate-do-db. Please read the notes that follow this option list.
--replicate-ignore-table=db_name.table_name Tells the slave thread to not replicate any command that updates the specified table (even if any other tables may be update by the same command). To specify more than one table to ignore, use the directive multiple times, once for each table. This will work for cross-database updates, in contrast to --replicate-ignore-db. Please read the notes that follow this option list.
--replicate-wild-do-table=db_name.table_name Tells the slave thread to restrict replication to queries where any of the updated tables match the specified wildcard pattern. To specify more than one table, use the directive multiple times, once for each table. This will work for cross-database updates. Please read the notes that follow this option list. Example: --replicate-wild-do-table=foo%.bar% will replicate only updates that uses a table in any databases that start with foo and whose table names start with bar. Note that if you do --replicate-wild-do-table=foo%.% then the rule will be propagated to CREATE DATABASE and DROP DATABASE, that is, these two statements will be replicated if the database name matches the database pattern (foo% here) (this magic is triggered by % being the table pattern). Escaping wildcard characters _ and %: if you want to replicate, for example, all tables of the my_own%db database (this is the exact name of the database), but not replicate tables from the my1ownAABCdb database, you should escape the _ and %: you should use something like this: replicate-wild-do-table=my\_own\%db. And if you are specifying this option from the command-line, depending on your system you may need to escape the \ (for example, with a bash shell, you would need to type --replicate-wild-do-table=my\\_own\\%db).
--replicate-wild-ignore-table=db_name.table_name Tells the slave thread to not replicate a query where any table matches the given wildcard pattern. To specify more than one table to ignore, use the directive multiple times, once for each table. This will work for cross-database updates. Please read the notes that follow this option list. Example: --replicate-wild-ignore-table=foo%.bar% will not do updates to tables in databases that start with foo and whose table names start with bar. Note that if you do --replicate-wild-ignore-table=foo%.% then the rule will be propagated to CREATE DATABASE and DROP DATABASE, that is, these two statements will not be replicated if the database name matches the database pattern (foo% here) (this magic is triggered by % being the table pattern). Escaping wildcard characters _ and %: see notes in the description of replicate-wild-do-table just above.
--replicate-do-db=database_name Tells the slave to restrict replication to commands where the current database (that is, the one selected by USE) is database_name. To specify more than one database, use the directive multiple times, once for each database. Note that this will not replicate cross-database queries such as UPDATE some_db.some_table SET foo="bar" while having selected a different or no database. If you need cross database updates to work, make sure you have 3.23.28 or later, and use --replicate-wild-do-table=db_name.%. Please read the notes that follow this option list. Example of what does not work as you could expect it: if the slave is started with --replicate-do-db=sales, and you do USE prices; UPDATE sales.january SET amount=amount+1000;, this query will not be replicated. If you need cross database updates to work, use --replicate-wild-do-table=db_name.% instead. The main reason for this ``just-check-the-current-database'' behavior is that it's hard from the command alone to know if a query should be replicated or not; for example if you are using multiple-table-delete or multiple-table-update commands that go across multiple databases. It's also very fast to just check the current database.
--replicate-ignore-db=database_name Tells the slave to not replicate any command where the current database (that is, the one selected by USE) is database_name. To specify more than one database to ignore, use the directive multiple times, once for each database. You should not use this directive if you are using cross table updates and you don't want these update to be replicated. Please read the notes that follow this option list. Example of what does not work as you could expect it: if the slave is started with --replicate-ignore-db=sales, and you do USE prices; UPDATE sales.january SET amount=amount+1000;, this query will be replicated. If you need cross database updates to work, use --replicate-wild-ignore-table=db_name.% instead.
--replicate-rewrite-db=from_name->to_name Tells the slave to translate the current database (that is, the one selected by USE) to to_name if it was from_name on the master. Only statements involving tables may be affected (CREATE DATABASE, DROP DATABASE won't), and only if from_name was the current database on the master. This will not work for cross-database updates. Note that the translation is done before --replicate-* rules are tested. Example: replicate-rewrite-db=master_db_name->slave_db_name
--report-host=host The hostname or IP number of the slave to be reported to the master during slave registration. Will appear in the output of SHOW SLAVE HOSTS. Leave unset if you do not want the slave to register itself with the master. Note that it is not sufficient for the master to simply read the IP number of the slave from the TCP/IP socket once the slave connects. Due to NAT and other routing issues, that IP may not be valid for connecting to the slave from the master or other hosts. This option is available as of MySQL 4.0.0.
--report-port=port_number Port for connecting to slave reported to the master during slave registration. Set it only if the slave is listening on a non-default port or if you have a special tunnel from the master or other clients to the slave. If not sure, leave this option unset. This option is available as of MySQL 4.0.0.
--skip-slave-start Tells the slave server not to start the slave threads on server startup. The user can start them later with START SLAVE.
--slave_compressed_protocol=# If 1, then use compression on the slave/client protocol if both slave and master support this.
--slave-load-tmpdir=filename This option is by default equal to the value of the tmpdir variable. When the slave SQL thread replicates a LOAD DATA INFILE command, it extracts the to-be-loaded file from the relay log into temporary files, then loads these into the table. If the file loaded on the master was huge, the temporary files on the slave will be huge, too; therefore you may wish/have to tell the slave to put the temporary files on some large disk different from tmpdir, using this option. In that case, you may also use the --relay-log option, as relay logs will be huge, too. --slave-load-tmpdir should point to a disk-based filesystem; not a memory-based one. Because the slave needs the temporary files used to replicate LOAD DATA INFILE) to survive a machine's reboot.
--slave-net-timeout=# Number of seconds to wait for more data from the master before aborting the read, considering the connection broken and retrying to connect. The first retry occurs immediately after timeout. The interval between retries is controlled by the --master-connect-retry option.
--slave-skip-errors= [err_code1,err_code2,... | all] Tells the slave SQL thread to continue replication when a query returns an error from the provided list. Normally, replication will discontinue when an error is encountered, giving the user a chance to resolve the inconsistency in the data manually. Do not use this option unless you fully understand why you are getting the errors. If there are no bugs in your replication setup and client programs, and no bugs in MySQL itself, you should never get an abort with error. Indiscriminate use of this option will result in slaves being hopelessly out of sync with the master and you having no idea how the problem happened. For error codes, you should use the numbers provided by the error message in your slave error log and in the output of SHOW SLAVE STATUS. A full list of error messages can be found in the source distribution in Docs/mysqld_error.txt. The server error codes also are listed at Error-returns. You can (but should not) also use a very non-recommended value of all which will ignore all error messages and keep barging along regardless. Needless to say, if you use it, we make no promises regarding your data integrity. Please do not complain if your data on the slave is not anywhere close to what it is on the master in this case --- you have been warned. Examples:
    --slave-skip-errors=1062,1053
    --slave-skip-errors=all
    

Some of these options, like all --replicate-* options, can only be set at the slave server's startup, not on-the-fly. We plan to fix this.

Here is the order of evaluation of the r--eplicate-* rules, to decide if the query is going to be executed by the slave or ignored by it:

  1. Are there some --replicate-do-db or --replicate-ignore-db rules?

    • Yes: test them like for --binlog-do-db and --binlog-ignore-db (see Binary log). What is the result of the test?

      • ignore the query: ignore it and exit.

      • execute the query: don't execute it immediately, defer the decision, go to step below.

    • No: go to step below.

  2. Are there some --replicate-*-table rules?

    • No: execute the query and exit.

    • Yes: go to step below. Only tables which are to be updated will be compared to rules (INSERT INTO sales SELECT * from prices: only sales will be compared to rules). If several tables are to be updated (multiple-table statement), the first matching table (matching ``do'' or ``ignore'') wins (that is, the first table is compared to rules, then if no decision could be taken the second table is compared to rules, etc).

  3. Are there some --replicate-do-table rules?

    • Yes: does the table match any of them?

      • Yes: execute the query and exit.

      • No: go to step below.

    • No: go to step below.

  4. Are there some --replicate-ignore-table rules?

    • Yes: does the table match any of them?

      • Yes: ignore the query and exit.

      • No: go to step below.

    • No: go to step below.

  5. Are there some --replicate-wild-do-table rules?

    • Yes: does the table match any of them?

      • Yes: execute the query and exit.

      • No: go to step below.

    • No: go to step below.

  6. Are there some --replicate-wild-ignore-table rules?

    • Yes: does the table match any of them?

      • Yes: ignore the query and exit.

      • No: go to step below.

    • No: go to step below.

  7. No --replicate-*-table rule was matched. Is there another table to test against these rules?

    • Yes: loop.

    • No: we have tested all tables to be updated, could not match any rule. Are there --replicate-do-table or --replicate-wild-do-table rules ?

      • Yes: ignore the query and exit.

      • No: execute the query and exit.