← Back to branch summary

~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to plugin/slave/docs/user_example.rst

Merged Marisa: Docs fixes

Show diffs side-by-side

added added

removed removed

Lines of Context:
plugin/slave/docs/user_example.rst
1
1
How to use replication: An example
2
2
====================================
3
3
 
4
 
This page covers how to complete a simple replication setup between two Drizzle servers using the replication slave plugin. Some of the concepts are very similar to MySQL replication. This is the simplest of examples (single master, single slave), with additional explanation on how to provision a new slave into an existing setup.
 
4
Simple replication setup (using a single master and a single slave) between two Drizzle servers is straightforward with the replication slave plugin. With Drizzle replication, you can also provision a new slave into an existing setup.
5
5
 
6
 
Replication setup begins with making certain that both master and slave share the same version of Drizzle to avoid any potential incompatibility issues. Then you set up the master.
 
6
Replication setup begins with making certain that both master and slave share the same version of Drizzle to avoid any potential incompatibility issues.
7
7
 
8
8
Master Setup
9
9
-------------
10
10
 
11
 
Setting up the master is the easiest step. The only real requirement for this step is to make sure that the master Drizzle database server is started with the --innodb.replication-log option. This will look something like:
 
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. For example:
12
12
 
13
13
    master> sbin/drizzled --datadir=$PWD/var --innodb.replication-log &
14
14
 
15
15
 
16
 
For more complex setups, you'll also want to consider using the --server-id option, but the default is fine for this example. That option is documented here.
 
16
For more complex setups, the --server-id option may be appropriate to use.
17
17
 
18
 
With the master running, you can optionally now create a backup of any databases to be imported on the new slave. You would use :doc:`../../clients/drizzledump` to make such a backup. For the sake of simplicity, this example assumes that we are starting with a fresh database with no data.
 
18
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.
19
19
 
20
20
Slave Setup
21
21
-------------
22
22
 
23
 
Once the master is running, the next step is to set up the slave. Starting the slave is almost as simple as starting the master. There are two Drizzle database server options required for the slave: --plugin-add=slave and --slave.config-file. This will look something like: ::
 
23
Starting the slave is almost as simple as starting the master. There are two Drizzle database server options required for the slave: --plugin-add=slave and --slave.config-file. For example: ::
24
24
 
25
25
        slave> sbin/drizzled --datadir=$PWD/var \
26
26
                                    --plugin-add=slave \
29
29
 
30
30
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: ::
31
31
 
32
 
        master-host = kodiak
 
32
        master-host = dino
33
33
        master-port = 3306
34
 
        master-user = kodiak_slave
 
34
        master-user = dino_slave
35
35
        master-pass = my_password
36
36
        io-thread-sleep = 10
37
37
        applier-thread-sleep = 10
38
38
 
39
 
Most of these options have sensible defaults, and it should be pretty obvious what most of them are for. The plugin documentation referenced above describes them in more complete detail if you need more information.
40
 
 
41
 
So once you start the slave as described above, it 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. That's all fine and dandy for your first slave machine in a brand new replication setup, but how do you insert another slave host into an already existing replication architecture? I'm glad you asked!
 
39
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.
42
40
 
43
41
Provisioning a New Slave Host
44
42
-------------------------------
45
43
 
46
 
Provisioning a new slave host very easy. The basic formula for creating a new slave host for an existing replication setup is:
 
44
The basic formula for creating a new slave host for an existing replication setup is:
47
45
 
48
46
   1. Make a backup of the master databases.
49
47
   2. Record the state of the master transaction log at the point the backup was made.
61
59
* **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.
62
60
* **ID**:  This is the unique transaction identifier associated with the most recently executed transaction stored in the transaction log.
63
61
 
64
 
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. We don't want it reading from the master until the backup is imported. To start it without the plugin enabled, import your backup, then shutdown the server: ::
 
62
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: ::
65
63
 
66
64
        slave> sbin/drizzled --datadir=$PWD/var &
67
65
        slave> drizzle < master.backup