1994.4.109
by Marisa Plumb
slave plugin docs |
1 |
How to use replication: An example
|
2 |
====================================
|
|
3 |
||
2369.1.1
by kent.bozlinski at datadifferential
replication example doc update |
4 |
A simple replication setup (using a single master and a single slave) between two Drizzle servers is done with the replication slave plugin. With Drizzle replication, you can also provision a new slave into an existing setup. |
1994.4.109
by Marisa Plumb
slave plugin docs |
5 |
|
1994.4.115
by Marisa Plumb
updating and fixing slave plugin example |
6 |
Replication setup begins with making certain that both master and slave share the same version of Drizzle to avoid any potential incompatibility issues. |
1994.4.109
by Marisa Plumb
slave plugin docs |
7 |
|
8 |
Master Setup
|
|
9 |
-------------
|
|
10 |
||
2369.1.1
by kent.bozlinski at datadifferential
replication example doc update |
11 |
Setting up the master is the first step. An important requirement is to start the master Drizzle database server with the --innodb.replication-log option, and a few other options in most circumstances. More options can be found in the options documentation. These are the most common options needed for a replication master. For example: |
12 |
||
13 |
master> usr/local/sbin/drizzled \ |
|
14 |
--innodb.replication-log \ |
|
15 |
--pid-file=/var/run/drizzled/drizzled.pid \ |
|
16 |
--drizzle-protocol.bind-address=0.0.0.0 \ |
|
17 |
--mysql-protocol.bind-address=0.0.0.0 \ |
|
18 |
--daemon |
|
19 |
||
20 |
||
21 |
Several options are required on most setups. They are set on Drizzle Startup with a --optionname. The most important ones are: |
|
22 |
||
23 |
||
24 |
The InnoDB replication log must be running: |
|
25 |
||
26 |
--innodb.replication-log |
|
27 |
||
28 |
||
29 |
PID must be set: |
|
30 |
||
31 |
--pid-file=/var/run/drizzled/drizzled.pid |
|
32 |
||
33 |
||
34 |
the address binding for Drizzle's default port (4427): |
|
35 |
||
36 |
--drizzle-protocol.bind-address=0.0.0.0 |
|
37 |
||
38 |
||
39 |
The address binding for systems replicating through MySQL's default port (3306): |
|
40 |
||
41 |
--mysql-protocol.bind-address=0.0.0.0 |
|
42 |
||
43 |
||
44 |
Data Directory can be set other than default: |
|
45 |
||
46 |
--datadir=$PWD/var |
|
47 |
||
48 |
||
49 |
For more complex setups, the server id option may be appropriate to use: |
|
50 |
||
51 |
--server-id |
|
52 |
||
53 |
||
54 |
To run Drizzle in the background, thereby keeping the database running if the user logs out: |
|
55 |
||
56 |
--daemon |
|
57 |
||
58 |
||
1994.4.109
by Marisa Plumb
slave plugin docs |
59 |
|
1994.4.115
by Marisa Plumb
updating and fixing slave plugin example |
60 |
With the master running, you can optionally now create a backup of any databases to be imported on the new slave by using :doc:`../../clients/drizzledump`. This example, however, assumes that we are starting with a fresh database with no data. |
1994.4.109
by Marisa Plumb
slave plugin docs |
61 |
|
62 |
Slave Setup
|
|
63 |
-------------
|
|
64 |
||
2369.1.1
by kent.bozlinski at datadifferential
replication example doc update |
65 |
Starting the slave is very similar to starting the master. There are two Drizzle database server options required for the slave: --plugin-add=slave and --slave.config-file. For example: ::
|
66 |
||
67 |
slave> /usr/local/sbin/drizzled \
|
|
68 |
--plugin-add=slave \
|
|
69 |
--slave.config-file=/usr/local/etc//slave.cfg
|
|
70 |
||
71 |
A more typical startup will need more options: |
|
72 |
||
73 |
slave> /usr/local/sbin/drizzled \ |
|
74 |
--plugin-add=slave \ |
|
75 |
--slave.config-file=/usr/local/etc//slave.cfg \ |
|
76 |
--pid-file=/var/run/drizzled/drizzled.pid \ |
|
77 |
--drizzle-protocol.bind-address=0.0.0.0 \ |
|
78 |
--mysql-protocol.bind-address=0.0.0.0 \ |
|
79 |
--daemon |
|
80 |
||
81 |
Similar to the Master setup, there are a number of options that can be selected. Please see the Plugin Documentation for the relevent options. |
|
1994.4.109
by Marisa Plumb
slave plugin docs |
82 |
|
83 |
These options tell the server to load the slave plugin, and then tell the slave plugin where to find the slave host configuration file. This configuration file has options to specify the master host and a few options to control how the slave operates. You can read more about the available configuration options in the replication slave plugin documentation. Below is a simple example: ::
|
|
84 |
||
2369.1.1
by kent.bozlinski at datadifferential
replication example doc update |
85 |
master-host = master.location.com
|
86 |
master-port = 4427
|
|
87 |
||
88 |
Some options that can be set other than default, but are otherwise not necessary, are: |
|
89 |
||
1994.4.115
by Marisa Plumb
updating and fixing slave plugin example |
90 |
master-user = dino_slave |
1994.4.109
by Marisa Plumb
slave plugin docs |
91 |
master-pass = my_password |
92 |
io-thread-sleep = 10 |
|
93 |
applier-thread-sleep = 10 |
|
94 |
||
1994.4.115
by Marisa Plumb
updating and fixing slave plugin example |
95 |
The slave will immediately connect to the master host specified in the configuration file and begin pulling events from the InnoDB-based transaction log. By default, a freshly provisioned slave will begin pulling from the beginning of this transaction log. Once all replication messages have been pulled from the master and stored locally on the slave host, the IO thread will sleep and periodically awaken to check for more messages. This is straightforward for an initial replication setup. See below to learn about inserting another slave host into an already existing replication architecture. |
1994.4.109
by Marisa Plumb
slave plugin docs |
96 |
|
97 |
Provisioning a New Slave Host
|
|
98 |
-------------------------------
|
|
99 |
||
1994.4.115
by Marisa Plumb
updating and fixing slave plugin example |
100 |
The basic formula for creating a new slave host for an existing replication setup is: |
1994.4.109
by Marisa Plumb
slave plugin docs |
101 |
|
102 |
1. Make a backup of the master databases.
|
|
103 |
2. Record the state of the master transaction log at the point the backup was made.
|
|
104 |
3. Restore the backup on the new slave machine.
|
|
105 |
4. Start the new slave and tell it to begin reading the transaction log from the point recorded in #2.
|
|
106 |
||
107 |
Steps #1 and #2 are covered with the drizzledump client program. If you use the --single-transaction option to drizzledump, it will place a comment near the beginning of the dump output with the InnoDB transaction log metadata. For example: ::
|
|
108 |
||
109 |
master> drizzledump --all-databases --single-transaction > master.backup
|
|
110 |
master> head -1 master.backup
|
|
111 |
-- SYS_REPLICATION_LOG: COMMIT_ID = 33426, ID = 35074
|
|
112 |
||
113 |
The SYS_REPLICATION_LOG line provides the replication log metadata needed when starting a new slave. It has two pieces of information: |
|
114 |
||
115 |
* **COMMIT_ID**: This value is the commit sequence number recorded for the most recently executed transaction stored in the transaction log. We can use this value to determine proper commit order within the log. The unique transaction ID cannot be used since that value is assigned when the transaction is started, not when it is committed. |
|
116 |
* **ID**: This is the unique transaction identifier associated with the most recently executed transaction stored in the transaction log. |
|
117 |
||
1994.4.115
by Marisa Plumb
updating and fixing slave plugin example |
118 |
Next, steps #3 and #4 must be completed to start the new slave. First, you must start the slave WITHOUT the replication slave plugin enabled, to prevent it from reading from the master until the backup is imported. To start it without the plugin enabled, import your backup, then shutdown the server: ::
|
1994.4.109
by Marisa Plumb
slave plugin docs |
119 |
|
120 |
slave> sbin/drizzled --datadir=$PWD/var &
|
|
121 |
slave> drizzle < master.backup
|
|
122 |
slave> drizzle --shutdown
|
|
123 |
||
124 |
Now that the backup is imported, restart the slave with the replication slave plugin enabled and use a new option, --slave.max-commit-id, to force the slave to begin reading the master's transaction log at the proper location: |
|
125 |
||
126 |
slave> sbin/drizzled --datadir=$PWD/var \ |
|
127 |
--plugin-add=slave \ |
|
2369.1.1
by kent.bozlinski at datadifferential
replication example doc update |
128 |
--slave.config-file=/user/local/etc/slave.cfg \ |
1994.4.109
by Marisa Plumb
slave plugin docs |
129 |
--slave.max-commit-id=33426 & |
130 |
||
131 |
||
132 |
We give the --slave.max-commit-id the value from the comment in the master dump file, which defines the maximum COMMIT_ID value (the latest transaction) represented by the slave's contents. |
|
133 |
||
134 |
This is the full cycle for a simple replication example. Please see the other Drizzle slave plugin docs for more information on replication and configuration options. |