Merge lp:~drizzle-developers/drizzle/replication-docs-7.1 into lp:~drizzle-trunk/drizzle/development
- replication-docs-7.1
- Merge into development
Proposed by
Brian Aker
Status: | Merged |
---|---|
Approved by: | Brian Aker |
Approved revision: | 2533 |
Merged at revision: | 2531 |
Proposed branch: | lp:~drizzle-developers/drizzle/replication-docs-7.1 |
Merge into: | lp:~drizzle-trunk/drizzle/development |
Diff against target: |
3638 lines (+2031/-1287) (has conflicts) 37 files modified
docs/administration/authentication.rst (+2/-0) docs/administration/authorization.rst (+2/-0) docs/administration/index.rst (+4/-2) docs/administration/plugins.rst (+3/-1) docs/clients/drizzledump.rst (+2/-0) docs/configuration/drizzled.rst (+37/-28) docs/configuration/options.rst (+2/-2) docs/functions/datetime.rst (+4/-0) docs/index.rst (+7/-2) docs/replication/appliers/index.rst (+33/-0) docs/replication/appliers/rabbitmq.rst (+199/-0) docs/replication/appliers/rabbitmq/changelog.rst (+13/-0) docs/replication/appliers/slave.rst (+64/-0) docs/replication/appliers/slave/administration.rst (+332/-0) docs/replication/appliers/slave/changelog.rst (+27/-0) docs/replication/appliers/slave/configuration.rst (+229/-0) docs/replication/appliers/slave/details.rst (+11/-0) docs/replication/appliers/zeromq.rst (+55/-0) docs/replication/drizzle.rst (+0/-324) docs/replication/examples/index.rst (+32/-0) docs/replication/examples/rabbitmq/basic.rst (+55/-0) docs/replication/examples/slave/provision_new_slave.rst (+61/-0) docs/replication/examples/slave/simple_master_slave.rst (+172/-0) docs/replication/index.rst (+172/-0) docs/replication/messages/index.rst (+251/-0) docs/replication/replicators/default.rst (+64/-0) docs/replication/replicators/filtered.rst (+143/-0) docs/replication/replicators/index.rst (+28/-0) plugin/default_replicator/docs/index.rst (+1/-63) plugin/filtered_replicator/docs/index.rst (+1/-142) plugin/innobase/docs/index.rst (+19/-2) plugin/rabbitmq/docs/index.rst (+3/-240) plugin/slave/docs/admin.rst (+0/-136) plugin/slave/docs/index.rst (+1/-162) plugin/slave/docs/user_example.rst (+0/-134) plugin/slave/module.cc (+1/-1) plugin/zeromq/docs/index.rst (+1/-48) Text conflict in docs/functions/datetime.rst |
To merge this branch: | bzr merge lp:~drizzle-developers/drizzle/replication-docs-7.1 |
Related bugs: | |
Related blueprints: |
Documentation focus areas for 7.1 release
(Undefined)
|
Reviewer | Review Type | Date Requested | Status |
---|---|---|---|
Drizzle Merge Team | Pending | ||
Review via email: mp+98078@code.launchpad.net |
Commit message
Description of the change
To post a comment you must log in.
Revision history for this message
Sekhar (msekharmca) wrote : | # |
Preview Diff
[H/L] Next/Prev Comment, [J/K] Next/Prev File, [N/P] Next/Prev Hunk
1 | === modified file 'docs/administration/authentication.rst' |
2 | --- docs/administration/authentication.rst 2011-11-14 22:29:19 +0000 |
3 | +++ docs/administration/authentication.rst 2012-03-18 00:36:19 +0000 |
4 | @@ -1,3 +1,5 @@ |
5 | +.. _authentication: |
6 | + |
7 | Authentication |
8 | ============== |
9 | |
10 | |
11 | === modified file 'docs/administration/authorization.rst' |
12 | --- docs/administration/authorization.rst 2011-11-14 22:29:19 +0000 |
13 | +++ docs/administration/authorization.rst 2012-03-18 00:36:19 +0000 |
14 | @@ -1,3 +1,5 @@ |
15 | +.. _authorization: |
16 | + |
17 | Authorization |
18 | ============= |
19 | |
20 | |
21 | === renamed file 'docs/administration/getting_started.rst' => 'docs/administration/index.rst' |
22 | --- docs/administration/getting_started.rst 2011-10-23 16:01:37 +0000 |
23 | +++ docs/administration/index.rst 2012-03-18 00:36:19 +0000 |
24 | @@ -1,5 +1,7 @@ |
25 | -Getting Started |
26 | -=============== |
27 | +.. _administering_drizzle: |
28 | + |
29 | +Administering Drizzle |
30 | +===================== |
31 | |
32 | Drizzle is a unique database server because most of its functionality is |
33 | provided by plugins. In fact, the primary job of :program:`drizzled`, |
34 | |
35 | === modified file 'docs/administration/plugins.rst' |
36 | --- docs/administration/plugins.rst 2012-03-03 02:42:42 +0000 |
37 | +++ docs/administration/plugins.rst 2012-03-18 00:36:19 +0000 |
38 | @@ -1,5 +1,7 @@ |
39 | .. program:: drizzled |
40 | |
41 | +.. _plugins: |
42 | + |
43 | Plugins |
44 | ======= |
45 | |
46 | @@ -24,7 +26,7 @@ |
47 | * :ref:`connection_id_plugin` - Return the current connection_id (connection_id) |
48 | * console_plugin - Console Client (console) (TODO: documentation missing) |
49 | * :ref:`crc32_plugin` - CRC32 Function (crc32) |
50 | - * :ref:`default_replicator_plugin` - Default Replicator (default_replicator) |
51 | + * :ref:`default_replicator` - Default Replicator (default_replicator) |
52 | * :ref:`drizzle_protocol_plugin` - Drizzle Protocol (drizzle_protocol) |
53 | * :ref:`errmsg_stderr_plugin` - Error Messages to stderr (errmsg_stderr) |
54 | * :ref:`error_dictionary_plugin` - Data Dictionary for Errors. (error_dictionary) |
55 | |
56 | === modified file 'docs/clients/drizzledump.rst' |
57 | --- docs/clients/drizzledump.rst 2012-03-08 00:54:48 +0000 |
58 | +++ docs/clients/drizzledump.rst 2012-03-18 00:36:19 +0000 |
59 | @@ -1,3 +1,5 @@ |
60 | +.. _drizzledump: |
61 | + |
62 | drizzledump Backup Tool |
63 | ======================= |
64 | |
65 | |
66 | === modified file 'docs/configuration/drizzled.rst' |
67 | --- docs/configuration/drizzled.rst 2012-03-08 00:54:48 +0000 |
68 | +++ docs/configuration/drizzled.rst 2012-03-18 00:36:19 +0000 |
69 | @@ -15,6 +15,10 @@ |
70 | General Options |
71 | ^^^^^^^^^^^^^^^ |
72 | |
73 | +.. option:: --daemon, -d |
74 | + |
75 | + Run :program:`drizzled` as a daemon. |
76 | + |
77 | .. option:: --help, -? |
78 | |
79 | Display this help and exit. |
80 | @@ -23,6 +27,20 @@ |
81 | |
82 | Display this help and exit after initializing plugins. |
83 | |
84 | +.. option:: --user, -u ARG |
85 | + |
86 | + :Default: |
87 | + :Variable: |
88 | + |
89 | + Run drizzled daemon as user. |
90 | + |
91 | +.. option:: --version, -V |
92 | + |
93 | + :Default: |
94 | + :Variable: ``version`` |
95 | + |
96 | + Print the version of Drizzle and exit. |
97 | + |
98 | .. _drizzled_config_file_options: |
99 | |
100 | Config File Options |
101 | @@ -93,6 +111,25 @@ |
102 | |
103 | --plugin_remove=syslog,md5 |
104 | |
105 | +.. _drizzled_replication_options: |
106 | + |
107 | +Replication Options |
108 | +^^^^^^^^^^^^^^^^^^^ |
109 | + |
110 | +.. option:: --replicate-query |
111 | + |
112 | + :Default: |
113 | + :Variable: ``replicate_query`` |
114 | + |
115 | + Include the SQL query in replicated protobuf messages. |
116 | + |
117 | +.. option:: --transaction-message-threshold |
118 | + |
119 | + :Default: 1048576 |
120 | + :Variable: ``transaction_message_threshold`` |
121 | + |
122 | + Max message size written to transaction log, valid values 131072 - 1048576 bytes. |
123 | + |
124 | .. _drizzled_kernel_options: |
125 | |
126 | Kernel Options |
127 | @@ -421,13 +458,6 @@ |
128 | A global constraint for read-rnd-buffer-size for all clients, cannot be set |
129 | lower than --read-rnd-buffer-size. Setting to 0 means unlimited. |
130 | |
131 | -.. option:: --replicate-query |
132 | - |
133 | - :Default: |
134 | - :Variable: ``replicate_query`` |
135 | - |
136 | - Include the SQL query in replicated protobuf messages. |
137 | - |
138 | .. option:: --scheduler ARG |
139 | |
140 | :Default: multi-thread |
141 | @@ -539,27 +569,6 @@ |
142 | |
143 | Default transaction isolation level. |
144 | |
145 | -.. option:: --transaction-message-threshold |
146 | - |
147 | - :Default: 1048576 |
148 | - :Variable: ``transaction_message_threshold`` |
149 | - |
150 | - Max message size written to transaction log, valid values 131072 - 1048576 bytes. |
151 | - |
152 | -.. option:: --user, -u ARG |
153 | - |
154 | - :Default: |
155 | - :Variable: |
156 | - |
157 | - Run drizzled daemon as user. |
158 | - |
159 | -.. option:: --version, -V |
160 | - |
161 | - :Default: |
162 | - :Variable: ``version`` |
163 | - |
164 | - Output version information and exit. |
165 | - |
166 | .. _drizzled_variables: |
167 | |
168 | Variables |
169 | |
170 | === modified file 'docs/configuration/options.rst' |
171 | --- docs/configuration/options.rst 2011-11-14 22:29:19 +0000 |
172 | +++ docs/configuration/options.rst 2012-03-18 00:36:19 +0000 |
173 | @@ -129,8 +129,8 @@ |
174 | ^^^^^^^^^^^^^^^^^^^^ |
175 | |
176 | Command line options have the form ``--option-name=value`` (the ``=`` is |
177 | -optional). This form works for both :ref:`drizzled_options` and all |
178 | -plugin options. For example:: |
179 | +optional). This form works for :ref:`drizzled options <drizzled_options>` |
180 | +and all plugin options. For example:: |
181 | |
182 | drizzled --basedir=/opt/drizzle --innodb.buffer-pool-size=500M |
183 | |
184 | |
185 | === modified file 'docs/functions/datetime.rst' |
186 | --- docs/functions/datetime.rst 2012-03-14 19:16:59 +0000 |
187 | +++ docs/functions/datetime.rst 2012-03-18 00:36:19 +0000 |
188 | @@ -29,7 +29,11 @@ |
189 | |statement_timestamp() |timestamp with time zone* |Current date and time (start of current statement) | |
190 | +-----------------------------------+-------------------------------------+-----------------------------------------------------------------+ |
191 | |
192 | +<<<<<<< TREE |
193 | Drizzle timezone is always UTC. |
194 | +======= |
195 | +*Drizzle timezone is always UTC*. |
196 | +>>>>>>> MERGE-SOURCE |
197 | |
198 | Extract |
199 | ------- |
200 | |
201 | === modified file 'docs/index.rst' |
202 | --- docs/index.rst 2012-01-30 21:09:19 +0000 |
203 | +++ docs/index.rst 2012-03-18 00:36:19 +0000 |
204 | @@ -73,7 +73,7 @@ |
205 | .. toctree:: |
206 | :maxdepth: 2 |
207 | |
208 | - administration/getting_started |
209 | + administration/index |
210 | administration/drizzled |
211 | administration/authentication |
212 | administration/authorization |
213 | @@ -85,8 +85,13 @@ |
214 | ----------- |
215 | .. toctree:: |
216 | :maxdepth: 2 |
217 | + :glob: |
218 | |
219 | - replication/drizzle |
220 | + replication/index |
221 | + replication/replicators/index |
222 | + replication/appliers/index |
223 | + replication/messages/index |
224 | + replication/examples/index |
225 | |
226 | SQL Language |
227 | ------------ |
228 | |
229 | === added directory 'docs/replication/appliers' |
230 | === added file 'docs/replication/appliers/index.rst' |
231 | --- docs/replication/appliers/index.rst 1970-01-01 00:00:00 +0000 |
232 | +++ docs/replication/appliers/index.rst 2012-03-18 00:36:19 +0000 |
233 | @@ -0,0 +1,33 @@ |
234 | +.. _appliers: |
235 | + |
236 | +.. _replication_appliers: |
237 | + |
238 | +Appliers |
239 | +======== |
240 | + |
241 | +Appliers are the other end point of a |
242 | +:ref:`replication stream <replication_streams>`, the first being |
243 | +:ref:`replicators`. Appliers provide an |
244 | +interface between replicators and a service. The service can be anything: |
245 | +another Drizzle server, a different database server, a message queue, etc. |
246 | +Appliers receive replication events from replicators and apply them to the |
247 | +service, although the term "apply" is used loosely. Appliers can do anything |
248 | +with replication events that provides useful behavior for the service. |
249 | +For example, an applier may write the replicaiton event to a file on disk, |
250 | +or it may send it over the network to some other service to be processed. |
251 | + |
252 | +Appliers are implemented by plugins and specify the unique name of a replicator with which Drizzle should pair it to create a replicaiton stream. Applier plugins default to using the :ref:`default_replicator`, but they can be configured to use another replicator. |
253 | + |
254 | +Most applier plugins are loaded and ran on the :ref:`originating_server`, |
255 | +but this is not a requirement. For example, the :ref:`slave_applier` is |
256 | +loaded on one server (the slave) and connects to and pairs with the |
257 | +:ref:`default_replicator` on another server (the master). |
258 | + |
259 | +Drizzle includes the following applier plugins: |
260 | + |
261 | +.. toctree:: |
262 | + :maxdepth: 1 |
263 | + |
264 | + slave |
265 | + rabbitmq |
266 | + zeromq |
267 | |
268 | === added directory 'docs/replication/appliers/rabbitmq' |
269 | === added file 'docs/replication/appliers/rabbitmq.rst' |
270 | --- docs/replication/appliers/rabbitmq.rst 1970-01-01 00:00:00 +0000 |
271 | +++ docs/replication/appliers/rabbitmq.rst 2012-03-18 00:36:19 +0000 |
272 | @@ -0,0 +1,199 @@ |
273 | +.. _rabbitmq_applier: |
274 | + |
275 | +RabbitMQ Applier |
276 | +================ |
277 | + |
278 | +The RabbitMQ applier plugin, named ``rabbitmq``, applies replication events to a `RabbitMQ <http://www.rabbitmq.com>`_ server. This can be used to create advanced replication solutions, to visualize data, or to build triggers. |
279 | + |
280 | +Loading |
281 | +------- |
282 | + |
283 | +To load this plugin, start :program:`drizzled` with:: |
284 | + |
285 | + --plugin-add=rabbitmq |
286 | + |
287 | +Loading the plugin may not enable or configure it. See the plugin's |
288 | +:ref:`rabbitmq_configuration` and :ref:`rabbitmq_variables`. |
289 | + |
290 | +.. seealso:: :ref:`drizzled_plugin_options` for more information about adding and removing plugins. |
291 | + |
292 | +.. _rabbitmq_configuration: |
293 | + |
294 | +Configuration |
295 | +------------- |
296 | + |
297 | +These command line options configure the plugin when :program:`drizzled` |
298 | +is started. See :ref:`command_line_options` for more information about |
299 | +specifying command line options. |
300 | + |
301 | +.. program:: drizzled |
302 | + |
303 | +.. option:: --rabbitmq.exchange ARG |
304 | + |
305 | + :Default: ReplicationExchange |
306 | + :Variable: :ref:`rabbitmq_exchange <rabbitmq_exchange>` |
307 | + |
308 | + Name of RabbitMQ exchange to publish to |
309 | + |
310 | +.. option:: --rabbitmq.host ARG |
311 | + |
312 | + :Default: localhost |
313 | + :Variable: :ref:`rabbitmq_host <rabbitmq_host>` |
314 | + |
315 | + Host name to connect to |
316 | + |
317 | +.. option:: --rabbitmq.password ARG |
318 | + |
319 | + :Default: guest |
320 | + :Variable: :ref:`rabbitmq_password <rabbitmq_password>` |
321 | + |
322 | + RabbitMQ password |
323 | + |
324 | +.. option:: --rabbitmq.port ARG |
325 | + |
326 | + :Default: 5672 |
327 | + :Variable: :ref:`rabbitmq_port <rabbitmq_port>` |
328 | + |
329 | + Port to connect to |
330 | + |
331 | +.. option:: --rabbitmq.routingkey ARG |
332 | + |
333 | + :Default: ReplicationRoutingKey |
334 | + :Variable: :ref:`rabbitmq_routingkey <rabbitmq_routingkey>` |
335 | + |
336 | + Name of RabbitMQ routing key to use |
337 | + |
338 | +.. option:: --rabbitmq.use-replicator ARG |
339 | + |
340 | + :Default: default_replicator |
341 | + :Variable: |
342 | + |
343 | + Name of the replicator plugin to use (default='default_replicator') |
344 | + |
345 | +.. option:: --rabbitmq.username ARG |
346 | + |
347 | + :Default: guest |
348 | + :Variable: :ref:`rabbitmq_username <rabbitmq_username>` |
349 | + |
350 | + RabbitMQ username |
351 | + |
352 | +.. option:: --rabbitmq.virtualhost ARG |
353 | + |
354 | + :Default: / |
355 | + :Variable: :ref:`rabbitmq_virtualhost <rabbitmq_virtualhost>` |
356 | + |
357 | + RabbitMQ virtualhost |
358 | + |
359 | +.. _rabbitmq_variables: |
360 | + |
361 | +Variables |
362 | +--------- |
363 | + |
364 | +These variables show the running configuration of the plugin. |
365 | +See `variables` for more information about querying and setting variables. |
366 | + |
367 | +.. _rabbitmq_exchange: |
368 | + |
369 | +* ``rabbitmq_exchange`` |
370 | + |
371 | + :Scope: Global |
372 | + :Dynamic: No |
373 | + :Option: :option:`--rabbitmq.exchange` |
374 | + |
375 | + Name of RabbitMQ exchange to publish to |
376 | + |
377 | +.. _rabbitmq_host: |
378 | + |
379 | +* ``rabbitmq_host`` |
380 | + |
381 | + :Scope: Global |
382 | + :Dynamic: No |
383 | + :Option: :option:`--rabbitmq.host` |
384 | + |
385 | + Host name to connect to |
386 | + |
387 | +.. _rabbitmq_password: |
388 | + |
389 | +* ``rabbitmq_password`` |
390 | + |
391 | + :Scope: Global |
392 | + :Dynamic: No |
393 | + :Option: :option:`--rabbitmq.password` |
394 | + |
395 | + RabbitMQ password |
396 | + |
397 | +.. _rabbitmq_port: |
398 | + |
399 | +* ``rabbitmq_port`` |
400 | + |
401 | + :Scope: Global |
402 | + :Dynamic: No |
403 | + :Option: :option:`--rabbitmq.port` |
404 | + |
405 | + Port to connect to |
406 | + |
407 | +.. _rabbitmq_routingkey: |
408 | + |
409 | +* ``rabbitmq_routingkey`` |
410 | + |
411 | + :Scope: Global |
412 | + :Dynamic: No |
413 | + :Option: :option:`--rabbitmq.routingkey` |
414 | + |
415 | + Name of RabbitMQ routing key to use |
416 | + |
417 | +.. _rabbitmq_username: |
418 | + |
419 | +* ``rabbitmq_username`` |
420 | + |
421 | + :Scope: Global |
422 | + :Dynamic: No |
423 | + :Option: :option:`--rabbitmq.username` |
424 | + |
425 | + RabbitMQ username |
426 | + |
427 | +.. _rabbitmq_virtualhost: |
428 | + |
429 | +* ``rabbitmq_virtualhost`` |
430 | + |
431 | + :Scope: Global |
432 | + :Dynamic: No |
433 | + :Option: :option:`--rabbitmq.virtualhost` |
434 | + |
435 | + RabbitMQ virtualhost |
436 | + |
437 | + |
438 | +Implementation Details |
439 | +---------------------- |
440 | + |
441 | +* :program:`drizzled` will not sart if the rabbitmq server is not available. |
442 | +* If the rabbitmq server goes away, the plugin will try to reconnect and resend the message 3 times, after that, the transaction is rolled back. |
443 | + |
444 | +.. _rabbitmq_version: |
445 | + |
446 | +Version |
447 | +------- |
448 | + |
449 | +This documentation applies to :ref:`rabbitmq_0.1_drizzle_7.0`. |
450 | + |
451 | +To see which version of the ``rabbitmq`` plugin a Drizzle server is running, |
452 | +execute: |
453 | + |
454 | +.. code-block:: mysql |
455 | + |
456 | + SELECT MODULE_VERSION FROM DATA_DICTIONARY.MODULES WHERE MODULE_NAME='rabbitmq' |
457 | + |
458 | +Changelog |
459 | +--------- |
460 | + |
461 | +.. toctree:: |
462 | + :maxdepth: 2 |
463 | + |
464 | + rabbitmq/changelog |
465 | + |
466 | +.. _rabbitmq_authors: |
467 | + |
468 | +Authors |
469 | +------- |
470 | + |
471 | +Marcus Eriksson |
472 | |
473 | === added file 'docs/replication/appliers/rabbitmq/changelog.rst' |
474 | --- docs/replication/appliers/rabbitmq/changelog.rst 1970-01-01 00:00:00 +0000 |
475 | +++ docs/replication/appliers/rabbitmq/changelog.rst 2012-03-18 00:36:19 +0000 |
476 | @@ -0,0 +1,13 @@ |
477 | +.. _rabbitmq_changelog: |
478 | + |
479 | +rabbitmq Changelog |
480 | +================== |
481 | + |
482 | +.. _rabbitmq_0.1_drizzle_7.0: |
483 | + |
484 | +rabbitmq 0.1 (Drizzle 7.0) |
485 | +-------------------------- |
486 | + |
487 | +:Released: March 15, 2011 |
488 | + |
489 | +* First release. |
490 | |
491 | === added directory 'docs/replication/appliers/slave' |
492 | === added file 'docs/replication/appliers/slave.rst' |
493 | --- docs/replication/appliers/slave.rst 1970-01-01 00:00:00 +0000 |
494 | +++ docs/replication/appliers/slave.rst 2012-03-18 00:36:19 +0000 |
495 | @@ -0,0 +1,64 @@ |
496 | +.. _slave: |
497 | + |
498 | +.. _slave_applier: |
499 | + |
500 | +Slave Applier |
501 | +============= |
502 | + |
503 | +The slave applier plugin, named ``slave``, provides a native implementation |
504 | +of replication between Drizzle servers by applying replication events from |
505 | +multiple "master" servers to a "slave" server. A slave is a server on which |
506 | +the ``slave`` plugin is loaded, configured, and ran. Slaves can connect to up |
507 | +to ten masters at once over the network and pair with the |
508 | +:ref:`default_replicator` on each them. Slaves apply every replication |
509 | +event from every master; conequently, they contain the same schemas and |
510 | +data as their masters. |
511 | + |
512 | +Replication chains are supported: slaves can also be masters and replicate |
513 | +events to other slaves. There is no limit to the number of levels in which |
514 | +masters and slaves can be enchained. |
515 | + |
516 | +Replication circles, or master-master replication, are not currently supported. |
517 | +Replication will break on one of the masters if this is attempted. |
518 | + |
519 | +The next two sections, :ref:`slave_configuration` and :ref:`slave_administration`, contain necessary information for configuring and administering slave-based replication. The third section, :ref:`slave_details`, covers technical details about how the ``slave`` plugin and slave-based replication work. |
520 | + |
521 | +.. toctree:: |
522 | + :maxdepth: 2 |
523 | + |
524 | + slave/configuration |
525 | + slave/administration |
526 | + slave/details |
527 | + |
528 | +.. _slave_version: |
529 | + |
530 | +Version |
531 | +------- |
532 | + |
533 | +This documentation applies to :ref:`slave_1.1_drizzle_7.1`. |
534 | + |
535 | +To see which version of the ``slave`` plugin a Drizzle server is running, |
536 | +execute: |
537 | + |
538 | +.. code-block:: mysql |
539 | + |
540 | + SELECT MODULE_VERSION FROM DATA_DICTIONARY.MODULES WHERE MODULE_NAME='slave' |
541 | + |
542 | +Changelog |
543 | +--------- |
544 | + |
545 | +.. toctree:: |
546 | + :maxdepth: 2 |
547 | + |
548 | + slave/changelog |
549 | + |
550 | +.. _slave_authors: |
551 | + |
552 | +Authors |
553 | +------- |
554 | + |
555 | +David Shrewsbury |
556 | + Original ``slave`` plugin code. Multi-master code. |
557 | + |
558 | +Daniel Nichter |
559 | + Documentation for :ref:`slave_1.1_drizzle_7.1`. |
560 | |
561 | === added file 'docs/replication/appliers/slave/administration.rst' |
562 | --- docs/replication/appliers/slave/administration.rst 1970-01-01 00:00:00 +0000 |
563 | +++ docs/replication/appliers/slave/administration.rst 2012-03-18 00:36:19 +0000 |
564 | @@ -0,0 +1,332 @@ |
565 | +.. _slave_administration: |
566 | + |
567 | +.. _slave_admin: |
568 | + |
569 | +Slave Administration |
570 | +******************** |
571 | + |
572 | +.. _slave_threads: |
573 | + |
574 | +Slave Threads |
575 | +============= |
576 | + |
577 | +The :ref:`slave` plugin uses two threads per master to read and apply replication events: |
578 | + |
579 | +* An IO (or producer) thread |
580 | +* An applier (or consumer) thread |
581 | + |
582 | +The IO thread connects to a master and reads replication events from the :ref:`slave_innodb_transaction_log` on the master. The applier thread applies the replication events from the IO thread to the slave. In other words, the IO thread produces replication events from the master, and the applier thread consumes and applies them to the slave. |
583 | + |
584 | +There is currently no way to stop, start, or restart the threads. Unless a replication error occurs, the threads should function continuously and remain in :ref:`RUNNING <slave_thread_running_status>` status. If a replication error does occur, the Drizzle server must be stopped, the error fixed, and the server restarted. |
585 | + |
586 | +.. _slave_thread_statuses: |
587 | + |
588 | +Statuses |
589 | +-------- |
590 | + |
591 | +Slave thread statuses are indicated by the ``status`` columns of the :ref:`sys_replication_tables`. A slave thread status is always one of these values: |
592 | + |
593 | +.. _slave_thread_running_status: |
594 | + |
595 | +RUNNING |
596 | + The thread is working properly, applying replicaiton events. |
597 | + |
598 | +.. _slave_thread_stopped_status: |
599 | + |
600 | +STOPPED |
601 | + The thread has stopped due to an error; replication events are not being applied. |
602 | + |
603 | +.. _sys_replication_tables: |
604 | + |
605 | +sys_replication Tables |
606 | +====================== |
607 | + |
608 | +The ``sys_replication`` schema on the slave has tables with information about the state of :ref:`slave_threads` and other replication-related information: |
609 | + |
610 | +.. code-block:: mysql |
611 | + |
612 | + drizzle> SHOW TABLES FROM sys_replication; |
613 | + +---------------------------+ |
614 | + | Tables_in_sys_replication | |
615 | + +---------------------------+ |
616 | + | applier_state | |
617 | + | io_state | |
618 | + | queue | |
619 | + +---------------------------+ |
620 | + |
621 | +If the ``sys_replication`` table is not available, then the :ref:`slave` plugin failed to load. |
622 | + |
623 | +.. _sys_replication_io_state: |
624 | + |
625 | +io_state |
626 | +-------- |
627 | + |
628 | +``sys_replication.io_state`` contains the state of IO threads, one per row: |
629 | + |
630 | +.. code-block:: mysql |
631 | + |
632 | + drizzle> SELECT * FROM sys_replication.io_state; |
633 | + *************************** 1. row *************************** |
634 | + master_id: 1 |
635 | + status: RUNNING |
636 | + error_msg: |
637 | + |
638 | +master_id |
639 | + ID (number) of the master to which the thread is connected. The number corresponds to the the master number in the :ref:`slave_config_file`. |
640 | + |
641 | +status |
642 | + :ref:`Status <slave_thread_statuses>` of the IO thread. |
643 | + |
644 | +error_msg |
645 | + Error message explaining why the thread has :ref:`STOPPED <slave_thread_statuses>`. |
646 | + |
647 | +.. _sys_replication_applier_state: |
648 | + |
649 | +applier_state |
650 | +------------- |
651 | + |
652 | +``sys_replication.applier_state`` contains the state of applier threads, one per row: |
653 | + |
654 | +.. code-block:: mysql |
655 | + |
656 | + drizzle> SELECT * FROM sys_replication.applier_state\G |
657 | + *************************** 1. row *************************** |
658 | + master_id: 1 |
659 | + last_applied_commit_id: 18 |
660 | + originating_server_uuid: 9908C6AA-A982-4763-B9BA-4EF5F933D219 |
661 | + originating_commit_id: 18 |
662 | + status: RUNNING |
663 | + error_msg: |
664 | + |
665 | +master_id |
666 | + ID (number) of the master from which the thread is applying replication events. The number corresponds to the the master number in the :ref:`slave_config_file`. |
667 | + |
668 | +last_applied_commit_id |
669 | + Value of the ``COMMIT_ID`` from the master's replication log of the most recently executed transaction. See definition of the data_dictionary.sys_replication_log table. |
670 | + |
671 | +originating_server_uuid |
672 | + UUID of the :ref:`originating_server`. |
673 | + |
674 | +originating_commit_id |
675 | + ``COMMIT_ID`` from the :ref:`originating_server`. |
676 | + |
677 | +status |
678 | + :ref:`Status <slave_thread_statuses>` of the applier thread. |
679 | + |
680 | +error_msg |
681 | + Error message explaining why the thread has :ref:`STOPPED <slave_thread_stopped_status>`. |
682 | + |
683 | +.. _sys_replication_queue: |
684 | + |
685 | +queue |
686 | +----- |
687 | + |
688 | +``sys_replication.io_state`` contains replication events that have not yet been applied by the applier thread, one per row: |
689 | + |
690 | +.. code-block:: mysql |
691 | + |
692 | + drizzle> SELECT * FROM sys_replication.queue\G |
693 | + *************************** 1. row *************************** |
694 | + trx_id: 925 |
695 | + seg_id: 1 |
696 | + commit_order: 12 |
697 | + originating_server_uuid: 9908C6AA-A982-4763-B9BA-4EF5F933D219 |
698 | + originating_commit_id: 12 |
699 | + msg: transaction_context { |
700 | + server_id: 1 |
701 | + transaction_id: 925 |
702 | + start_timestamp: 1330211976689868 |
703 | + end_timestamp: 1330211976689874 |
704 | + } |
705 | + statement { |
706 | + type: DROP_SCHEMA |
707 | + start_timestamp: 1330211976689872 |
708 | + end_timestamp: 1330211976689873 |
709 | + drop_schema_statement { |
710 | + schema_name: "foo" |
711 | + } |
712 | + } |
713 | + segment_id: 1 |
714 | + end_segment: true |
715 | + master_id: 1 |
716 | + |
717 | +.. _slave_lag: |
718 | + |
719 | +Slave Lag |
720 | +========= |
721 | + |
722 | +Slaves intentionally lag masters by at least :ref:`applier-thread-sleep <slave_cfg_common_options>` or :ref:`io-thread-sleep <slave_cfg_common_options>` seconds. Since :ref:`replication_events` are transactions, *slave lag is the number of committed transactions behind a master*. To determine a slave's lag, first query the last committed transaction ID on the master: |
723 | + |
724 | +.. code-block:: mysql |
725 | + |
726 | + drizzle> SELECT MAX(COMMIT_ID) FROM DATA_DICTIONARY.SYS_REPLICATION_LOG; |
727 | + +----------------+ |
728 | + | MAX(COMMIT_ID) | |
729 | + +----------------+ |
730 | + | 6 | |
731 | + +----------------+ |
732 | + |
733 | +Then query the last applied transaction ID on the slave: |
734 | + |
735 | +.. code-block:: mysql |
736 | + |
737 | + drizzle> SELECT MAX(last_applied_commit_id) FROM sys_replication.applier_state; |
738 | + +-----------------------------+ |
739 | + | MAX(last_applied_commit_id) | |
740 | + +-----------------------------+ |
741 | + | 6 | |
742 | + +-----------------------------+ |
743 | + |
744 | +In this example, the slave is caught up to the master because both the last commited transaction ID on the master and the last applied transaction ID on the slave are 6. |
745 | + |
746 | +If the last applied transaction ID on a slave is less than the last committed transaciton ID on a master, then the slave lags the master by *N transactions* (not seconds) where N is the difference of the two transaction ID values. |
747 | + |
748 | +Master Connections |
749 | +================== |
750 | + |
751 | +Slaves connect to masters like normal users by specifying a username and password (see the :ref:`slave_cfg_master_options`). Therefore, slave connections on a master are visible in the master's processlist and sessions, but they are not specially indicated. If the :ref:`slave_user_account` uses slave-specific usernames like "slave1", then the slave connections can be viewed like: |
752 | + |
753 | +.. code-block:: mysql |
754 | + |
755 | + drizzle> SELECT * FROM DATA_DICTIONARY.PROCESSLIST WHERE USERNAME LIKE 'slave%'\G |
756 | + *************************** 1. row *************************** |
757 | + ID: 2 |
758 | + USERNAME: slave |
759 | + HOST: 127.0.0.1 |
760 | + DB: NULL |
761 | + COMMAND: Sleep |
762 | + TIME: 0 |
763 | + STATE: NULL |
764 | + INFO: NULL |
765 | + HAS_GLOBAL_LOCK: 0 |
766 | + |
767 | +The ``DATA_DICTIONARY.SESSIONS`` table can be queried similarly: |
768 | + |
769 | +.. code-block:: mysql |
770 | + |
771 | + drizzle> SELECT * FROM DATA_DICTIONARY.SESSIONS WHERE SESSION_USERNAME LIKE 'slave%'\G |
772 | + *************************** 1. row *************************** |
773 | + SESSION_ID: 2 |
774 | + SESSION_USERNAME: slave1 |
775 | + SESSION_HOST: 127.0.0.1 |
776 | + SESSION_CATALOG: LOCAL |
777 | + SESSION_SCHEMA: NULL |
778 | + COMMAND: Sleep |
779 | + STATE: NULL |
780 | + QUERY: NULL |
781 | + HAS_GLOBAL_LOCK: 0 |
782 | + IS_INTERACTIVE: 0 |
783 | + IS_CONSOLE: 0 |
784 | + |
785 | +Or, slave connections can be viewed by specifying the slave server's hostname, like: |
786 | + |
787 | +.. code-block:: mysql |
788 | + |
789 | + drizzle> SELECT * FROM DATA_DICTIONARY.PROCESSLIST WHERE HOSTNAME = '192.168.1.5'\G |
790 | + *************************** 1. row *************************** |
791 | + ID: 3 |
792 | + USERNAME: slave |
793 | + HOST: 192.168.1.5 |
794 | + DB: NULL |
795 | + COMMAND: Sleep |
796 | + TIME: 0 |
797 | + STATE: NULL |
798 | + INFO: NULL |
799 | + HAS_GLOBAL_LOCK: 0 |
800 | + |
801 | +.. _slave_innodb_transaction_log: |
802 | + |
803 | +InnoDB Transaction Log |
804 | +====================== |
805 | + |
806 | +The :ref:`slave` requires the :ref:`innodb_transaction_log` on the master to retrieve replication events. This transaction log is stored as an internal table within InnoDB, but there are two tables which provide access to its data: |
807 | + |
808 | +* ``DATA_DICTIONARY.SYS_REPLICATION_LOG`` |
809 | +* ``DATA_DICTIONARY.INNODB_REPLICATION_LOG`` |
810 | + |
811 | +The :ref:`IO thread <slave_threads>` from a slave (which connects to a master) reads transactions (replicaiton events) directly from ``DATA_DICTIONARY.SYS_REPLICATION_LOG``. The transaction messages are binary which makes the table data unreadable by most humans: |
812 | + |
813 | +.. code-block:: mysql |
814 | + |
815 | + drizzle> SELECT * from DATA_DICTIONARY.SYS_REPLICATION_LOG\G |
816 | + *************************** 1. row *************************** |
817 | + ID: 772 |
818 | + SEGID: 1 |
819 | + COMMIT_ID: 1 |
820 | + END_TIMESTAMP: 1331841800496546 |
821 | + ORIGINATING_SERVER_UUID: 98ECEA09-BA65-489D-9382-F8D15098B1AE |
822 | + ORIGINATING_COMMIT_ID: 1 |
823 | + MESSAGE_LEN: 33 |
824 | + MESSAGE: ????????? |
825 | + |
826 | +The last column, ``MESSAGE``, contains the actual transaction data that the client renders as question marks because the data is binary, not text. |
827 | + |
828 | +The ``DATA_DICTIONARY.INNODB_REPLICATION_LOG`` table contains the same data as the ``DATA_DICTIONARY.SYS_REPLICATION_LOG`` table, but it converts the transaction data to text: |
829 | + |
830 | +.. code-block:: mysql |
831 | + |
832 | + drizzle> SELECT * from DATA_DICTIONARY.INNODB_REPLICATION_LOG\G |
833 | + *************************** 1. row *************************** |
834 | + TRANSACTION_ID: 772 |
835 | + TRANSACTION_SEGMENT_ID: 1 |
836 | + COMMIT_ID: 1 |
837 | + END_TIMESTAMP: 1331841800496546 |
838 | + ORIGINATING_SERVER_UUID: 98ECEA09-BA65-489D-9382-F8D15098B1AE |
839 | + ORIGINATING_COMMIT_ID: 1 |
840 | + TRANSACTION_MESSAGE_STRING: transaction_context { |
841 | + server_id: 1 |
842 | + transaction_id: 772 |
843 | + start_timestamp: 1331841800496542 |
844 | + end_timestamp: 1331841800496546 |
845 | + } |
846 | + event { |
847 | + type: STARTUP |
848 | + } |
849 | + segment_id: 1 |
850 | + end_segment: true |
851 | + TRANSACTION_LENGTH: 33 |
852 | + |
853 | +The ``TRANSACTION_MESSAGE_STRING`` column contains the text representation of the ``MESSAGE`` column from the ``DATA_DICTIONARY.SYS_REPLICATION_LOG`` table. |
854 | + |
855 | + |
856 | +``DATA_DICTIONARY.INNODB_REPLICATION_LOG`` is read-only, but ``DATA_DICTIONARY.SYS_REPLICATION_LOG`` can be modified which allows the transaction log to be maintained, as described in the next section. |
857 | + |
858 | +Transaction Log Maintenance |
859 | +--------------------------- |
860 | + |
861 | +Currently, the InnoDB transaction log grows without bounds and old transactions are never deleted. The InnoDB transaction log must be maintained manually by carefully deleting old transactions that are no longer needed from the ``DATA_DICTIONARY.SYS_REPLICATION_LOG`` table. |
862 | + |
863 | +.. warning:: Care must be taken to avoid deleting transactions that slaves have not yet applied else data will be lost and replication will break. |
864 | + |
865 | +Follow these steps to trim the InnoDB transaction log without affecting slave function: |
866 | + |
867 | +#. Query each slave for the ``last_applied_commit_id`` value from the :ref:`sys_replication.applier_state <sys_replication_applier_state>` table. |
868 | +#. Choose the **minimum** value obtained from step one. This is the marker value for the slave that is the furthest behind the master. |
869 | +#. Using the marker value from the previous step, delete rows from ``DATA_DICTIONARY.SYS_REPLICATION_LOG`` that have a ``COMMIT_ID`` less than the marker value. |
870 | + |
871 | +For example, if there are two slaves, query each one for the minimum ``last_applied_commit_id``: |
872 | + |
873 | +.. code-block:: mysql |
874 | + |
875 | + slave1> SELECT last_applied_commit_id FROM sys_replicaiton.applier_state; |
876 | + +------------------------+ |
877 | + | last_applied_commit_id | |
878 | + +------------------------+ |
879 | + | 3000 | |
880 | + +------------------------+ |
881 | + |
882 | + slave2> SELECT last_applied_commit_id FROM sys_replicaiton.applier_state; |
883 | + +------------------------+ |
884 | + | last_applied_commit_id | |
885 | + +------------------------+ |
886 | + | 2877 | |
887 | + +------------------------+ |
888 | + |
889 | +slave2 has the smallest value for ``last_applied_commit_id``, 2877, so this value is the marker for deleting records from the master's transaction log: |
890 | + |
891 | +.. code-block:: mysql |
892 | + |
893 | + master> DELETE FROM DATA_DICTIONARY.SYS_REPLICATION_LOG |
894 | + -> WHERE COMMIT_ID < 2877; |
895 | + |
896 | +This permanently deletes all old, unneeded records from the InnoDB transaction log. |
897 | |
898 | === added file 'docs/replication/appliers/slave/changelog.rst' |
899 | --- docs/replication/appliers/slave/changelog.rst 1970-01-01 00:00:00 +0000 |
900 | +++ docs/replication/appliers/slave/changelog.rst 2012-03-18 00:36:19 +0000 |
901 | @@ -0,0 +1,27 @@ |
902 | +.. _slave_changelog: |
903 | + |
904 | +slave Changelog |
905 | +=============== |
906 | + |
907 | +.. _slave_1.1_drizzle_7.1: |
908 | + |
909 | +slave 1.1 (Drizzle 7.1) |
910 | +----------------------- |
911 | + |
912 | +:Released: |
913 | + |
914 | +* Added multi-master-support (https://blueprints.launchpad.net/drizzle/+spec/slave-multi-master). |
915 | + |
916 | + * Changed all options, except ``--slave.config-file``, from command line options to slave config file options. |
917 | + * Added ``ignore-errors`` option for slave config file. |
918 | + |
919 | +* Rewrote :ref:`slave` docs (https://blueprints.launchpad.net/drizzle/+spec/docs71-focus-areas). |
920 | + |
921 | +.. _slave_1.0_drizzle_7.0: |
922 | + |
923 | +slave 1.0 (Drizzle 7.0) |
924 | +----------------------- |
925 | + |
926 | +:Released: March 15, 2011 |
927 | + |
928 | +* First release. |
929 | |
930 | === added file 'docs/replication/appliers/slave/configuration.rst' |
931 | --- docs/replication/appliers/slave/configuration.rst 1970-01-01 00:00:00 +0000 |
932 | +++ docs/replication/appliers/slave/configuration.rst 2012-03-18 00:36:19 +0000 |
933 | @@ -0,0 +1,229 @@ |
934 | +.. program:: drizzled |
935 | + |
936 | +.. _slave_configuration: |
937 | + |
938 | +.. _slave_config: |
939 | + |
940 | +Slave Configuration |
941 | +******************* |
942 | + |
943 | +Configuring a Drizzle :ref:`replication stream <replication_streams>` using the :ref:`slave` requires: |
944 | + |
945 | +#. Load a :ref:`replicator plugin <replicators>` on the masters |
946 | +#. Enabling :option:`--innodb.replication-log` on the masters |
947 | +#. Creating user accounts for the slaves on the masters |
948 | +#. Writing a :ref:`slave_config_file` for :option:`--slave.config-file` on the slave |
949 | +#. Loading and configure the ``slave`` plugin on the slave |
950 | + |
951 | +The first three steps are performed on a master, and the last two steps are performed on a slave. |
952 | + |
953 | +.. _configuring_a_master: |
954 | + |
955 | +Configuring a Master |
956 | +==================== |
957 | + |
958 | +A single slave can apply replication events from up to ten masters at once. |
959 | +There are three requirements for each master: |
960 | + |
961 | +#. :ref:`replicators` |
962 | +#. :option:`--innodb.replication-log` |
963 | +#. :ref:`slave_user_account` |
964 | + |
965 | +A :ref:`replicator plugin <replicators>` must be loaded on each master. The :ref:`default_replicator` is loaded by default. To verify that it is loaded on a master, execute: |
966 | + |
967 | +.. code-block:: sql |
968 | + |
969 | + drizzle> SELECT * FROM DATA_DICTIONARY.PLUGINS WHERE PLUGIN_NAME = 'default_replicator'; |
970 | + +--------------------+-----------------------+-----------+--------------------+ |
971 | + | PLUGIN_NAME | PLUGIN_TYPE | IS_ACTIVE | MODULE_NAME | |
972 | + +--------------------+-----------------------+-----------+--------------------+ |
973 | + | default_replicator | TransactionReplicator | 1 | default_replicator | |
974 | + +--------------------+-----------------------+-----------+--------------------+ |
975 | + |
976 | +If the plugin is not loaded, verify that the server was *not* started with |
977 | +``--plugin-remove default_replicator``. If it was, remove that option and |
978 | +restart the server. |
979 | + |
980 | +To use a different replicator, :ref:`configure Drizzle <configuring_drizzle>` to load the replicator plugin on startup, and specify the replicator name with :option:`--innodb.use-replicator`. |
981 | + |
982 | +Each master must also be started with :option:`--innodb.replication-log` |
983 | +to enable the :ref:`innodb_transaction_log` which is not enabled by default. |
984 | +Therefore, Drizzle must be configured with this option at startup. |
985 | +See :ref:`configuring_drizzle` for more information. To verify that the |
986 | +InnoDB replication log is active, execute: |
987 | + |
988 | +.. code-block:: mysql |
989 | + |
990 | + drizzle> SELECT * FROM DATA_DICTIONARY.GLOBAL_VARIABLES WHERE VARIABLE_NAME = 'innodb_replication_log'; |
991 | + +------------------------+----------------+ |
992 | + | VARIABLE_NAME | VARIABLE_VALUE | |
993 | + +------------------------+----------------+ |
994 | + | innodb_replication_log | ON | |
995 | + +------------------------+----------------+ |
996 | + |
997 | + drizzle> SELECT * FROM DATA_DICTIONARY.INNODB_REPLICATION_LOG LIMIT 1; |
998 | + -- The query should return one row showing a replication event. |
999 | + |
1000 | +.. _slave_user_account: |
1001 | + |
1002 | +Slave User Account |
1003 | +------------------ |
1004 | + |
1005 | +A user account is required on the master for slave connections, unless no :ref:`authentication` is used (which is highly inadvisable). One user account can be used for all slaves, or individual user accounts can be used for each slave. In either case, the user account credentials (username and password) for a master are specified in the :ref:`slave_config_file`. |
1006 | + |
1007 | +:ref:`authorization` must be configured on the master to allow slave user accounts to access the ``DATA_DICTIONARY`` schema, else the :ref:`slave IO thread <slave_threads>` will fail to start on the slave: |
1008 | + |
1009 | +.. code-block:: mysql |
1010 | + |
1011 | + drizzle> SELECT * FROM sys_replication.io_state\G |
1012 | + *************************** 1. row *************************** |
1013 | + master_id: 1 |
1014 | + status: STOPPED |
1015 | + error_msg: Replication slave: Access denied for user 'slave' to schema 'data_dictionary' |
1016 | + |
1017 | +The :ref:`sys_replication_tables` are discussed in :ref:`slave_admin`. |
1018 | + |
1019 | +:ref:`authorization` cannot be used to filter which schemas or tables are replicated because slave connections do no access individual schemas and tables, they only access the :ref:`innodb_transaction_log`. To filter which schemas or tables are replicated, configure the master to use a filtering replicator like :ref:`filtered_replicator`, as described above. |
1020 | + |
1021 | +.. _configuring_a_slave: |
1022 | + |
1023 | +Configuring a Slave |
1024 | +=================== |
1025 | + |
1026 | +After :ref:`configuring_a_master`, configuring a slave requires only: |
1027 | + |
1028 | +#. :ref:`slave_config_file` |
1029 | +#. :ref:`slave_plugin` |
1030 | + |
1031 | +.. _slave_config_file: |
1032 | + |
1033 | +Slave Config File |
1034 | +----------------- |
1035 | + |
1036 | +A slave config file is a plain text file that contains connection and configuration options for each master. At least one master must be specifed, and masters must be numbered sequentially from 1 to 10. The general syntax of a slave config file is: |
1037 | + |
1038 | +.. code-block:: ini |
1039 | + |
1040 | + # comment |
1041 | + common-option=value |
1042 | + [masterN] |
1043 | + master-specific-option=value |
1044 | + |
1045 | +There are two types of options: common options which apply to all masters, and master-specific options which only apply to the preceding ``[masterN]`` header where ``N`` is the sequentially numbered master, starting with 1. Whitespace |
1046 | +before and after lines and around ``=`` (equal signs) is ignored. |
1047 | + |
1048 | +The simplest possible slave config file is: |
1049 | + |
1050 | +.. code-block:: ini |
1051 | + |
1052 | + [master1] |
1053 | + master-host=<master hostname> |
1054 | + master-user=slave1 |
1055 | + |
1056 | +See :ref:`slave_examples` for complete, working examples. |
1057 | + |
1058 | +.. _slave_cfg_common_options: |
1059 | + |
1060 | +Common Options |
1061 | +-------------- |
1062 | + |
1063 | +These options must be specified first, before any ``[masterN]`` headers. |
1064 | + |
1065 | +.. confval:: applier-thread-sleep |
1066 | + |
1067 | + :Default: 5 |
1068 | + |
1069 | + The number of seconds the applier (consumer) thread sleeps between applying |
1070 | + replication events from the local queue. |
1071 | + |
1072 | +.. confval:: ignore-errors |
1073 | + |
1074 | + Ignore errors and continue applying replication events. It is generally |
1075 | + a bad idea to use this option! |
1076 | + |
1077 | +.. confval:: io-thread-sleep |
1078 | + |
1079 | + :Default: 5 |
1080 | + |
1081 | + The number of seconds the IO (producer) thread sleeps between queries to the |
1082 | + master for more replication events. |
1083 | + |
1084 | +.. confval:: seconds-between-reconnects |
1085 | + |
1086 | + :Default: 30 |
1087 | + |
1088 | + The number of seconds to wait between reconnect attempts when the master |
1089 | + server becomes unreachable. |
1090 | + |
1091 | +.. _slave_cfg_master_options: |
1092 | + |
1093 | +Master-specific Options |
1094 | +----------------------- |
1095 | + |
1096 | +These options must be specified after a ``[masterN]`` header. |
1097 | + |
1098 | +.. confval:: master-host |
1099 | + |
1100 | + Hostname/IP address of the master server. |
1101 | + |
1102 | +.. confval:: master-port |
1103 | + |
1104 | + :Default: 3306 |
1105 | + |
1106 | + Drizzle port used by the master server. |
1107 | + |
1108 | +.. confval:: master-user |
1109 | + |
1110 | + Username to use for connecting to the master server. |
1111 | + See :ref:`slave_user_account`. |
1112 | + |
1113 | +.. confval:: master-pass |
1114 | + |
1115 | + Password associated with the username given by :confval:`master-user`. |
1116 | + See :ref:`slave_user_account`. |
1117 | + |
1118 | +.. program:: drizzledump |
1119 | + |
1120 | +.. confval:: max-commit-id |
1121 | + |
1122 | + Maximum commit ID the slave is assumed to have applied from the master. |
1123 | + This value will be used by the slave to determine where to begin retrieving |
1124 | + replication events from the master transaction log. This option can be used |
1125 | + to provision a new slave by setting it to the value output from the |
1126 | + :ref:`drizzledump` when used with the :option:`--single-transaction` option. |
1127 | + |
1128 | +.. confval:: max-reconnects |
1129 | + |
1130 | + :Default: 10 |
1131 | + |
1132 | + The number of reconnection attempts the slave plugin will try if the |
1133 | + master server becomes unreachable. |
1134 | + |
1135 | +.. _slave_plugin: |
1136 | + |
1137 | +slave Plugin |
1138 | +------------ |
1139 | + |
1140 | +A slave must load the ``slave`` plugin which is not loaded by default. |
1141 | +This plugin has only one option: |
1142 | + |
1143 | +.. program:: drizzled |
1144 | + |
1145 | +.. option:: --slave.config-file FILE |
1146 | + |
1147 | + :Default: :file:`BASEDIR/etc/slave.cfg` |
1148 | + :Variable: |
1149 | + |
1150 | + Full path to a :ref:`slave_config_file`. |
1151 | + By default, the plugin looks for a file named :file:`slave.cfg` |
1152 | + in :file:`BASEDIR/etc/` where :file:`BASEDIR` is determined by |
1153 | + :option:`--basedir`. |
1154 | + |
1155 | +Since a slave can connect to multiple masters, all other options are set |
1156 | +in the :ref:`slave_config_file`. Once a slave config file has been written, start Drizzle with the ``slave`` plugin like: |
1157 | + |
1158 | +.. code-block:: bash |
1159 | + |
1160 | + $ drizzled --plugin-add slave --slave.config-file /etc/drizzled/slave.conf |
1161 | + |
1162 | +If the masters are configured properly, and the slave config file is correct, and the slave plugin loads successfully, the :ref:`sys_replication_tables` will be accessible on the slave as described in the next topic, :ref:`slave_admin`. |
1163 | |
1164 | === added file 'docs/replication/appliers/slave/details.rst' |
1165 | --- docs/replication/appliers/slave/details.rst 1970-01-01 00:00:00 +0000 |
1166 | +++ docs/replication/appliers/slave/details.rst 2012-03-18 00:36:19 +0000 |
1167 | @@ -0,0 +1,11 @@ |
1168 | +.. _slave_details: |
1169 | + |
1170 | +Slave Details |
1171 | +============= |
1172 | + |
1173 | +The following sections dive into the technical aspects of the :ref:`slave`. In general, it should not be necessary to know this information to :ref:`configure <slave_configuration>` or :ref:`adminster <slave_admin>` a slave. This information is useful for troubleshooting, developers, hackers, and those who wish to "look under the hood." |
1174 | + |
1175 | +Slave Plugin Class |
1176 | +------------------ |
1177 | + |
1178 | +Although the documentation for the :ref:`slave` calls the plugin an applier, which implies that the plugin subclasses the TransactionApplier class, the :ref:`slave_plugin` is not in fact a TransactionApplier, it is a Daemon. The :ref:`innodb_transaction_log` is a TransactionApplier which defaults to using with the :ref:`default_replicator` (see :file:`plugin/innobase/handler/replication_log.h`). |
1179 | |
1180 | === added file 'docs/replication/appliers/zeromq.rst' |
1181 | --- docs/replication/appliers/zeromq.rst 1970-01-01 00:00:00 +0000 |
1182 | +++ docs/replication/appliers/zeromq.rst 2012-03-18 00:36:19 +0000 |
1183 | @@ -0,0 +1,55 @@ |
1184 | +.. _zeromq: |
1185 | + |
1186 | +.. _zeromq_applier: |
1187 | + |
1188 | +ZeroMQ Applier |
1189 | +============== |
1190 | + |
1191 | +ZeroMQ is a messaging library that allows you to easily build complex |
1192 | +communication systems. The ZeroMQ plugin allows drizzle to publish |
1193 | +transactions to a local PUB socket. Many clients can subscribe to |
1194 | +these transactions. The first frame of the message sent out is the |
1195 | +schema name the transaction touched - this enables clients to only |
1196 | +subscribe to the interesting schemas (note that certain "transactions" |
1197 | +are without a schema, like SET xyz for example, for these, the first |
1198 | +frame is empty). |
1199 | + |
1200 | +Getting started |
1201 | +--------------- |
1202 | + |
1203 | +First, install zeromq, get the code from `zeromq.org |
1204 | +<http://zeromq.org>`_, then you can build drizzle, watch the |
1205 | +./configure output to verify that drizzle finds the libraries needed. |
1206 | + |
1207 | +Now you are good to go, simply start drizzle with --plugin-add=zeromq |
1208 | +and drizzle will start publishing transactions. The only configuration |
1209 | +parameter available is: |
1210 | + |
1211 | +.. code-block:: bash |
1212 | + |
1213 | + --zeromq.endpoint arg (=tcp://*:9999) - the endpoint to expose. |
1214 | + |
1215 | +Now you can write a simple python script to verify that it works, |
1216 | +something like this will work: |
1217 | + |
1218 | +.. code-block:: python |
1219 | + |
1220 | + import zmq |
1221 | + |
1222 | + ctx = zmq.Context() |
1223 | + s = ctx.socket(zmq.SUB) |
1224 | + s.setsockopt(zmq.SUBSCRIBE, '') |
1225 | + s.connect('tcp://localhost:9999') |
1226 | + i = 0 |
1227 | + while True: |
1228 | + i = i+1 |
1229 | + s.recv_multipart() |
1230 | + print i |
1231 | + |
1232 | +and then you can generate some load: |
1233 | + |
1234 | +.. code-block:: bash |
1235 | + |
1236 | + bin/drizzleslap -c 10 -a --auto-generate-sql-add-autoincrement --burnin |
1237 | + |
1238 | +which creates 10 threads and generates random queries. |
1239 | |
1240 | === removed file 'docs/replication/drizzle.rst' |
1241 | --- docs/replication/drizzle.rst 2011-10-23 05:45:09 +0000 |
1242 | +++ docs/replication/drizzle.rst 1970-01-01 00:00:00 +0000 |
1243 | @@ -1,324 +0,0 @@ |
1244 | -******************* |
1245 | -Drizzle Replication |
1246 | -******************* |
1247 | - |
1248 | -Replication events are recorded using messages in the `Google Protocol Buffer |
1249 | -<http://code.google.com/p/protobuf/>`_ (GPB) format. GPB messages can contain |
1250 | -sub-messages. There is a single main "envelope" message, Transaction, that |
1251 | -is passed to plugins that subscribe to the replication stream. |
1252 | - |
1253 | -Configuration Options |
1254 | -##################### |
1255 | - |
1256 | -**transaction_message_threshold** |
1257 | - |
1258 | - Controls the size, in bytes, of the Transaction messages. When a Transaction |
1259 | - message exceeds this size, a new Transaction message with the same |
1260 | - transaction ID will be created to continue the replication events. |
1261 | - See :ref:`bulk-operations` below. |
1262 | - |
1263 | - |
1264 | -**replicate_query** |
1265 | - |
1266 | - Controls whether the originating SQL query will be included within each |
1267 | - Statement message contained in the enclosing Transaction message. The |
1268 | - default global value is FALSE which will not include the query in the |
1269 | - messages. It can be controlled per session, as well. For example: |
1270 | - |
1271 | - .. code-block:: mysql |
1272 | - |
1273 | - drizzle> set @@replicate_query = 1; |
1274 | - |
1275 | - The stored query should be used as a guide only, and never executed |
1276 | - on a slave to perform replication as this will lead to incorrect results. |
1277 | - |
1278 | -Message Definitions |
1279 | -################### |
1280 | - |
1281 | -The GPB messages are defined in .proto files in the drizzled/message |
1282 | -directory of the Drizzle source code. The primary definition file is |
1283 | -transaction.proto. Messages defined in this file are related in the |
1284 | -following ways:: |
1285 | - |
1286 | - |
1287 | - ------------------------------------------------------------------ |
1288 | - | | |
1289 | - | Transaction message | |
1290 | - | | |
1291 | - | ----------------------------------------------------------- | |
1292 | - | | | | |
1293 | - | | TransactionContext message | | |
1294 | - | | | | |
1295 | - | ----------------------------------------------------------- | |
1296 | - | ----------------------------------------------------------- | |
1297 | - | | | | |
1298 | - | | Statement message 1 | | |
1299 | - | | | | |
1300 | - | ----------------------------------------------------------- | |
1301 | - | ----------------------------------------------------------- | |
1302 | - | | | | |
1303 | - | | Statement message 2 | | |
1304 | - | | | | |
1305 | - | ----------------------------------------------------------- | |
1306 | - | ... | |
1307 | - | ----------------------------------------------------------- | |
1308 | - | | | | |
1309 | - | | Statement message N | | |
1310 | - | | | | |
1311 | - | ----------------------------------------------------------- | |
1312 | - ------------------------------------------------------------------ |
1313 | - |
1314 | -with each Statement message looking like so:: |
1315 | - |
1316 | - ------------------------------------------------------------------ |
1317 | - | | |
1318 | - | Statement message | |
1319 | - | | |
1320 | - | ----------------------------------------------------------- | |
1321 | - | | | | |
1322 | - | | Common information | | |
1323 | - | | | | |
1324 | - | | - Type of Statement (INSERT, DELETE, etc) | | |
1325 | - | | - Start Timestamp | | |
1326 | - | | - End Timestamp | | |
1327 | - | | - (OPTIONAL) Actual SQL query string | | |
1328 | - | | | | |
1329 | - | ----------------------------------------------------------- | |
1330 | - | ----------------------------------------------------------- | |
1331 | - | | | | |
1332 | - | | Statement subclass message 1 (see below) | | |
1333 | - | | | | |
1334 | - | ----------------------------------------------------------- | |
1335 | - | ... | |
1336 | - | ----------------------------------------------------------- | |
1337 | - | | | | |
1338 | - | | Statement subclass message N (see below) | | |
1339 | - | | | | |
1340 | - | ----------------------------------------------------------- | |
1341 | - ------------------------------------------------------------------ |
1342 | - |
1343 | -The Transaction Message |
1344 | -####################### |
1345 | - |
1346 | -The main "envelope" message which represents an atomic transaction |
1347 | -which changed the state of a server is the Transaction message class. |
1348 | - |
1349 | -The Transaction message contains two pieces: |
1350 | - |
1351 | -#. A TransactionContext message containing information about the |
1352 | - transaction as a whole, such as the ID of the executing server, |
1353 | - the start and end timestamp of the transaction, segmenting |
1354 | - metadata and a unique identifier for the transaction. |
1355 | -#. A vector of Statement messages representing the distinct SQL |
1356 | - statements which modified the state of the server. The Statement |
1357 | - message is, itself, a generic envelope message containing a |
1358 | - sub-message which describes the specific data modification which |
1359 | - occurred on the server (such as, for instance, an INSERT statement). |
1360 | - |
1361 | -The Statement Message |
1362 | -##################### |
1363 | - |
1364 | -The generic "envelope" message containing information common to each |
1365 | -SQL statement executed against a server (such as a start and end timestamp |
1366 | -and the type of the SQL statement) as well as a Statement subclass message |
1367 | -describing the specific data modification event on the server. |
1368 | - |
1369 | -Each Statement message contains a type member which indicates how readers |
1370 | -of the Statement should construct the inner Statement subclass representing |
1371 | -a data change. |
1372 | - |
1373 | -Statements are recorded separately as sometimes individual statements |
1374 | -have to be rolled back. |
1375 | - |
1376 | - |
1377 | -.. _bulk-operations: |
1378 | - |
1379 | -How Bulk Operations Work |
1380 | -######################## |
1381 | - |
1382 | -Certain operations which change large volumes of data on a server |
1383 | -present a specific set of problems for a transaction coordinator or |
1384 | -replication service. If all operations must complete atomically on a |
1385 | -publishing server before replicas are delivered the complete |
1386 | -transactional unit: |
1387 | - |
1388 | -#. The publishing server could consume a large amount of memory |
1389 | - building an in-memory Transaction message containing all the |
1390 | - operations contained in the entire transaction. |
1391 | -#. A replica, or subscribing server, is wasting time waiting on the |
1392 | - eventual completion (commit) of the large transaction on the |
1393 | - publishing server. It could be applying pieces of the large |
1394 | - transaction in the meantime... |
1395 | - |
1396 | -In order to prevent the problems inherent in (1) and (2) above, Drizzle's |
1397 | -replication system uses a mechanism which provides bulk change |
1398 | -operations. |
1399 | - |
1400 | -A single transaction in the database can possibly be represented with |
1401 | -multiple protobuf Transaction messages if the message grows too large. |
1402 | -This can happen if you have a bulk transaction, or a single statement |
1403 | -affecting a very large number of rows, or just a large transaction with |
1404 | -many statements/changes. |
1405 | - |
1406 | -For the first two examples, it is likely that the Statement sub-message |
1407 | -itself will get segmented, causing another Transaction message to be |
1408 | -created to hold the rest of the Statement's row changes. In these cases, |
1409 | -it is enough to look at the segment information stored in the Statement |
1410 | -message (see example below). |
1411 | - |
1412 | -For the last example, the Statement sub-messages may or may not be |
1413 | -segmented, but we could still need to split the individual Statements up into |
1414 | -multiple Transaction messages to keep the Transaction message size from |
1415 | -growing too large. In this case, the segment information in the Statement |
1416 | -submessages is not helpful if the Statement isn't segmented. We need this |
1417 | -information in the Transaction message itself. |
1418 | - |
1419 | -Segmenting a Single SQL Statement |
1420 | -********************************* |
1421 | - |
1422 | -When a regular SQL statement modifies or inserts more rows than a |
1423 | -certain threshold, Drizzle's replication services component will begin |
1424 | -sending Transaction messages to replicas which contain a chunk |
1425 | -(or "segment") of the data which has been changed on the publisher. |
1426 | - |
1427 | -When data is inserted, updated, or modified in the database, a |
1428 | -header containing information about modified tables and fields is |
1429 | -matched with one or more data segments which contain the actual |
1430 | -values changed in the statement. |
1431 | - |
1432 | -It's easiest to understand this mechanism by following through a real-world |
1433 | -scenario. |
1434 | - |
1435 | -Suppose the following table: |
1436 | - |
1437 | -.. code-block:: mysql |
1438 | - |
1439 | - CREATE TABLE test.person |
1440 | - ( |
1441 | - id INT NOT NULL AUTO_INCREMENT PRIMARY KEY |
1442 | - , first_name VARCHAR(50) |
1443 | - , last_name VARCHAR(50) |
1444 | - , is_active CHAR(1) NOT NULL DEFAULT 'Y' |
1445 | - ); |
1446 | - |
1447 | -Also suppose that test.t1 contains 1 million records. |
1448 | - |
1449 | -Next, suppose a client issues the SQL statement: |
1450 | - |
1451 | -.. code-block:: mysql |
1452 | - |
1453 | - UPDATE test.person SET is_active = 'N'; |
1454 | - |
1455 | -It is clear that one million records could be updated by this statement |
1456 | -(we say, "could be" since Drizzle does not actually update a record if |
1457 | -the UPDATE would not change the existing record...). |
1458 | - |
1459 | -In order to prevent the publishing server from having to construct an |
1460 | -enormous Transaction message, Drizzle's replication services component |
1461 | -will do the following: |
1462 | - |
1463 | -#. Construct a Transaction message with a transaction context containing |
1464 | - information about the originating server, the transaction ID, and |
1465 | - timestamp information. |
1466 | -#. Construct an UpdateHeader message with information about the tables |
1467 | - and fields involved in the UPDATE statement. Push this UpdateHeader |
1468 | - message onto the Transaction message's statement vector. |
1469 | -#. Construct an UpdateData message. Set the *segment_id* member to 1. |
1470 | - Set the *end_segment* member to true. |
1471 | -#. For every record updated in a storage engine, the ReplicationServices |
1472 | - component builds a new UpdateRecord message and appends this message |
1473 | - to the aforementioned UpdateData message's record vector. |
1474 | -#. After a certain threshold of records is reached, the |
1475 | - ReplicationServices component sets the current UpdateData message's |
1476 | - *end_segment* member to false, and proceeds to send the Transaction |
1477 | - message to replicators. |
1478 | -#. The ReplicationServices component then constructs a new Transaction |
1479 | - message and constructs a transaction context with the same |
1480 | - transaction ID and server information. |
1481 | -#. A new UpdateData message is created. The message's *segment_id* is |
1482 | - set to N+1 and as new records are updated, new UpdateRecord messages |
1483 | - are appended to the UpdateData message's record vector. |
1484 | -#. While records are being updated, we repeat steps 5 through 7, with |
1485 | - only the final UpdateData message having its *end_segment* member set |
1486 | - to true. |
1487 | - |
1488 | -Segmenting a Transaction |
1489 | -************************ |
1490 | - |
1491 | -The Transaction protobuf message also contains *segment_id* member and a |
1492 | -*end_segment* member. These values are also set appropriately when a |
1493 | -Statement sub-message is segmented, as described above. |
1494 | - |
1495 | -These values are also set when a Transaction must be segmented along |
1496 | -individual Statement boundaries (i.e., the Statement message itself |
1497 | -is **not** segmented). In either case, it is enough to check the |
1498 | -*end_segment* and *segment_id* values of the Transaction message |
1499 | -to determine if this is a multi-message transaction. |
1500 | - |
1501 | -Handling ROLLBACKs |
1502 | -################## |
1503 | - |
1504 | -Both transactions and individual statements may be rolled back. |
1505 | - |
1506 | -When a transaction is rolled back, one of two things happen depending |
1507 | -on whether the transaction is made up of either a single Transaction |
1508 | -message, or if it is made up of multiple Transaction messages (e.g, bulk |
1509 | -load). |
1510 | - |
1511 | -* For a transaction encapsulated entirely within a single Transaction |
1512 | - message, the entire message is simply discarded and not sent through |
1513 | - the replication stream. |
1514 | -* For a transaction which is made up of multiple messages, and at least |
1515 | - one message has already been sent through the replication stream, then |
1516 | - the Transaction message will contain a Statement message with type = |
1517 | - ROLLBACK. This signifies to rollback the entire transaction. |
1518 | - |
1519 | -A special Statement message type, ROLLBACK_STATEMENT, is used when |
1520 | -we have a segmented Statement message (see above) and we need to tell the |
1521 | -receiver to undo any changes made for this single statement, but not |
1522 | -for the entire transaction. If the receiver cannot handle rolling back |
1523 | -a single statement, then a message buffering strategy should be employed |
1524 | -to guarantee that a statement was indeed applied successfully before |
1525 | -executing on the receiver. |
1526 | - |
1527 | -.. _replication_streams: |
1528 | - |
1529 | -Replication Streams |
1530 | -################### |
1531 | - |
1532 | -The Drizzle kernel handles delivering replication messages to plugins by |
1533 | -maintaining a list of replication streams. A stream is represented as a |
1534 | -registered *replicator* and *applier* pair. |
1535 | - |
1536 | -When a replication message is generated within the kernel, the replication |
1537 | -services module of the kernel will send this message to each registered |
1538 | -*replicator*. The *replicator* will then do something useful with it and |
1539 | -send it to each *applier* with which it is associated. |
1540 | - |
1541 | -Replicators |
1542 | -*********** |
1543 | - |
1544 | -A registered *replicator* is a plugin that implements the TransactionReplicator |
1545 | -API. Each replicator will be plugged into the kernel to receive the Google |
1546 | -Protobuf messages that are generated as the database is changed. Ideally, |
1547 | -each registered replicator will transform or modify the messages it receives |
1548 | -to implement a specific behavior. For example, filtering by schema name. |
1549 | - |
1550 | -Each registered replicator should have a unique name. The default replicator, |
1551 | -cleverly named **default_replicator**, does no transformation at all on the |
1552 | -replication messages. |
1553 | - |
1554 | -Appliers |
1555 | -******** |
1556 | - |
1557 | -A registered *applier* is a plugin that implements the TransactionApplier |
1558 | -API. Appliers are responsible for applying the replication messages that it |
1559 | -will receive from a registered replicator. The word "apply" is used loosely |
1560 | -here. An applier may do anything with the replication messages that provides |
1561 | -useful behavior. For example, an applier may simply write the messages to a |
1562 | -file on disk, or it may send the messages over the network to some other |
1563 | -service to be processed. |
1564 | - |
1565 | -At the point of registration with the Drizzle kernel, each applier specifies |
1566 | -the name of a registered replicator that it should be attached to in order to |
1567 | -make the replication stream pair. |
1568 | |
1569 | === added directory 'docs/replication/examples' |
1570 | === added file 'docs/replication/examples/index.rst' |
1571 | --- docs/replication/examples/index.rst 1970-01-01 00:00:00 +0000 |
1572 | +++ docs/replication/examples/index.rst 2012-03-18 00:36:19 +0000 |
1573 | @@ -0,0 +1,32 @@ |
1574 | +.. _replication_examples: |
1575 | + |
1576 | +Examples |
1577 | +======== |
1578 | + |
1579 | +These replication examples require a working knowledge of: |
1580 | + |
1581 | +* :ref:`configuring_drizzle` |
1582 | +* :ref:`administering_drizzle` |
1583 | +* :ref:`drizzle_replication` |
1584 | + |
1585 | +The examples are complete, but they may not explain every step in detail, and they probably need to be adapted to other environments. In other words: the examples are guides, not drop-in solutions. Free and commercial :ref:`help` is available. |
1586 | + |
1587 | +.. _slave_examples: |
1588 | + |
1589 | +Slave Applier |
1590 | +------------- |
1591 | + |
1592 | +.. toctree:: |
1593 | + :maxdepth: 1 |
1594 | + :glob: |
1595 | + |
1596 | + slave/* |
1597 | + |
1598 | +RabbitMQ Applier |
1599 | +---------------- |
1600 | + |
1601 | +.. toctree:: |
1602 | + :maxdepth: 1 |
1603 | + :glob: |
1604 | + |
1605 | + rabbitmq/* |
1606 | |
1607 | === added directory 'docs/replication/examples/rabbitmq' |
1608 | === added file 'docs/replication/examples/rabbitmq/basic.rst' |
1609 | --- docs/replication/examples/rabbitmq/basic.rst 1970-01-01 00:00:00 +0000 |
1610 | +++ docs/replication/examples/rabbitmq/basic.rst 2012-03-18 00:36:19 +0000 |
1611 | @@ -0,0 +1,55 @@ |
1612 | +.. _basic_rabbitmq_example: |
1613 | + |
1614 | +Basic RabbitMQ |
1615 | +============== |
1616 | + |
1617 | +:Synopsis: Set up replication to a RabbitMQ server |
1618 | +:Replicator: :ref:`default_replicator` |
1619 | +:Applier: :ref:`rabbitmq_applier` |
1620 | +:Version: :ref:`rabbitmq_0.1_drizzle_7.0` |
1621 | +:Authors: Marcus Eriksson |
1622 | + |
1623 | +First install a recent version of RabbitMQ, then install librabbitmq, the C library for talking to the RabbitMQ server: |
1624 | + |
1625 | +.. code-block:: bash |
1626 | + |
1627 | + $ hg clone http://hg.rabbitmq.com/rabbitmq-codegen/ |
1628 | + $ hg clone http://hg.rabbitmq.com/rabbitmq-c/ |
1629 | + $ cd rabbitmq-c |
1630 | + $ autoreconf -f -i |
1631 | + $ ./configure |
1632 | + $ make |
1633 | + $ make install |
1634 | + |
1635 | +Now you probably need to rebuild Drizzle since the :program:`rabbitmq` plugin is not built if librabbitmq is not installed. |
1636 | + |
1637 | +Finally, start :program:`drizzled` like: |
1638 | + |
1639 | +.. code-block:: bash |
1640 | + |
1641 | + sbin/drizzled \ |
1642 | + --daemon \ |
1643 | + --pid-file /var/run/drizzled.pid \ |
1644 | + --plugin-add rabbitmq \ |
1645 | + >> /var/log/drizzled.log 2>&1 |
1646 | + |
1647 | +To verify that it works, you can start a generic rabbitmq listener from librabbitmq: |
1648 | + |
1649 | +.. code-block:: bash |
1650 | + |
1651 | + $ amqp_listen localhost 5672 ReplicationExchange ReplicationRoutingKey |
1652 | + |
1653 | +And you should see something like this when you do an INSERT/CREATE/.. (just not a select) in your newly built Drizzle instance:: |
1654 | + |
1655 | + Result 0 |
1656 | + Frame type 1, channel 1 |
1657 | + Method AMQP_BASIC_DELIVER_METHOD |
1658 | + Delivery 1, exchange ReplicationExchange routingkey ReplicationRoutingKey |
1659 | + |
1660 | + 00000000: 0A 17 08 01 10 87 36 18 : F0 FA D9 99 FA F1 A7 02 ......6......... |
1661 | + 00000010: 20 99 81 DA 99 FA F1 A7 : 02 12 40 08 01 10 F2 FA .........@..... |
1662 | + 00000020: D9 99 FA F1 A7 02 18 FC : FA D9 99 FA F1 A7 02 2A ...............* |
1663 | + 00000030: 17 0A 06 0A 01 62 12 01 : 61 12 06 08 04 12 02 69 .....b..a......i |
1664 | + 00000040: 64 12 05 08 01 12 01 74 : 32 11 08 01 10 01 1A 0B d......t2....... |
1665 | + 00000050: 0A 01 32 0A 02 61 61 10 : 00 10 00 20 01 28 01 ..2..aa.... .(. |
1666 | + 0000005F: |
1667 | |
1668 | === added directory 'docs/replication/examples/slave' |
1669 | === added file 'docs/replication/examples/slave/provision_new_slave.rst' |
1670 | --- docs/replication/examples/slave/provision_new_slave.rst 1970-01-01 00:00:00 +0000 |
1671 | +++ docs/replication/examples/slave/provision_new_slave.rst 2012-03-18 00:36:19 +0000 |
1672 | @@ -0,0 +1,61 @@ |
1673 | +.. _provision_new_slave_example: |
1674 | + |
1675 | +Provision New Slave |
1676 | +=================== |
1677 | + |
1678 | +:Synopsis: Provision a new slave from a backup of a master |
1679 | +:Replicator: :ref:`default_replicator` |
1680 | +:Applier: :ref:`slave` |
1681 | +:Version: :ref:`slave_1.1_drizzle_7.1` |
1682 | +:Authors: Marisa Plumb, Kent Bozlinski, Daniel Nichter |
1683 | + |
1684 | +The basic formula for creating a new slave for an existing master is: |
1685 | + |
1686 | +#. Make a backup of the master databases. |
1687 | +#. Record the max committed transaction ID of the master at the point the backup was made. |
1688 | +#. Restore the backup on the new slave. |
1689 | +#. Start the new slave from the recorded max committed transaction ID of the master. |
1690 | + |
1691 | +.. program:: drizzledump |
1692 | + |
1693 | +Steps #1 and #2 are performed using the :ref:`drizzledump` and its :option:`--single-transaction` option which prints a comment near the beginning of the dump output with the InnoDB transaction log metadata: |
1694 | + |
1695 | +.. code-block:: bash |
1696 | + |
1697 | + master$ drizzledump --all-databases --single-transaction > master-backup.sql |
1698 | + |
1699 | + master$ grep SYS_REPLICATION_LOG master-backup.sql |
1700 | + -- SYS_REPLICATION_LOG: COMMIT_ID = 3303, ID = 3500 |
1701 | + |
1702 | +The ``SYS_REPLICATION_LOG`` comment provides the replication log metadata needed to start a new slave. There are two values: |
1703 | + |
1704 | +COMMIT_ID |
1705 | + The commit sequence number recorded for the most recently executed transaction stored in the transaction log. This value is used to determine proper commit order within the log. ``ID``, the unique transaction identifier, cannot be used because it is assigned when the transaction is started, not when it is committed. |
1706 | + |
1707 | +ID |
1708 | + The unique transaction identifier associated with the most recently executed transaction stored in the transaction log. |
1709 | + |
1710 | +For step #3, start the slave *without* the :ref:`slave_plugin` to prevent it from reading from the master until the backup is imported. Then import the backup on the slave: |
1711 | + |
1712 | +.. code-block:: bash |
1713 | + |
1714 | + slave$ drizzle < master-backup.sql |
1715 | + |
1716 | +Stop the slave once the backup finishes importing. |
1717 | + |
1718 | +For step #4, add the :ref:`max-commit-id option <slave_cfg_master_options>` to the :ref:`slave_config_file`: |
1719 | + |
1720 | +.. code-block:: ini |
1721 | + |
1722 | + # Example of existing lines |
1723 | + [master1] |
1724 | + master-host=10.0.0.1 |
1725 | + master-user=slave |
1726 | + master-pass=foo |
1727 | + |
1728 | + # Add this line |
1729 | + max-commit-id=3303 |
1730 | + |
1731 | +The value for :ref:`max-commit-id <slave_cfg_master_options>` is the ``COMMIT_ID`` value from the ``SYS_REPLICATION_LOG`` comment in the master dump file (steps #1 and #2). This value defines the committed transaction ID on the master from which the slave will start applying transactions. |
1732 | + |
1733 | +Finally, start the slave *with* the :ref:`slave_plugin` and verify that replication is working (see :ref:`slave_admin`). |
1734 | |
1735 | === added file 'docs/replication/examples/slave/simple_master_slave.rst' |
1736 | --- docs/replication/examples/slave/simple_master_slave.rst 1970-01-01 00:00:00 +0000 |
1737 | +++ docs/replication/examples/slave/simple_master_slave.rst 2012-03-18 00:36:19 +0000 |
1738 | @@ -0,0 +1,172 @@ |
1739 | +.. program:: drizzled |
1740 | + |
1741 | +.. _simple_master_slave_example: |
1742 | + |
1743 | +Simple Master-Slave |
1744 | +=================== |
1745 | + |
1746 | +:Synopsis: Set up one master and one slave, neither of which have existing data |
1747 | +:Replicator: :ref:`default_replicator` |
1748 | +:Applier: :ref:`slave` |
1749 | +:Version: :ref:`slave_1.1_drizzle_7.1` |
1750 | +:Authors: Daniel Nichter |
1751 | + |
1752 | +This example uses new servers that are not yet configured and do not yet have any data. If Drizzle was installed from a binary package or repository, then it may already be configured, in which case the following steps may not work or conflict with the existing configuration. In any case, the principles in this example can be adapted to different configurations. |
1753 | + |
1754 | +Master Setup |
1755 | +------------ |
1756 | + |
1757 | +First, temporarily start the master server with no :ref:`authentication` in order to create the user accounts. |
1758 | + |
1759 | +.. code-block:: bash |
1760 | + |
1761 | + sbin/drizzled >> /var/log/drizzled.log 2>&1 & |
1762 | + |
1763 | +Once Drizzle is running, create the user accounts: |
1764 | + |
1765 | +.. code-block:: mysql |
1766 | + |
1767 | + drizzle> CREATE SCHEMA auth; |
1768 | + |
1769 | + drizzle> USE auth; |
1770 | + |
1771 | + drizzle> CREATE TABLE users ( |
1772 | + -> user VARCHAR(255) NOT NULL, |
1773 | + -> password VARCHAR(40), |
1774 | + -> UNIQUE INDEX user_idx (user) |
1775 | + -> ); |
1776 | + |
1777 | + drizzle> INSERT INTO auth.users (user, password) |
1778 | + -> VALUES ('root', MYSQL_PASSWORD('foo')), |
1779 | + -> ('slave', MYSQL_PASSWORD('foo')); |
1780 | + |
1781 | + drizzle> shutdown; |
1782 | + |
1783 | +Once Drizzle has stopped running, restart it with the :ref:`auth_schema_plugin` plugin and other plugins required for :ref:`configuring_a_master`: |
1784 | + |
1785 | +.. code-block:: bash |
1786 | + |
1787 | + sbin/drizzled \ |
1788 | + --daemon \ |
1789 | + --pid-file /var/run/drizzled/drizzled.pid \ |
1790 | + --plugin-remove auth_all \ |
1791 | + --plugin-add auth_schema \ |
1792 | + --innodb.replication-log \ |
1793 | + >> /var/log/drizzled.log 2>&1 |
1794 | + |
1795 | +See the options used to start Drizzle for more information: |
1796 | + |
1797 | +* :option:`--daemon` |
1798 | +* :option:`--pid-file` |
1799 | +* :option:`--plugin-add` |
1800 | +* :option:`--innodb.replication-log` |
1801 | + |
1802 | +Other options and :ref:`plugins` can be used if necessary. |
1803 | + |
1804 | +Verify that the master is running and writing :ref:`replication_events` to the :ref:`innodb_transaction_log`: |
1805 | + |
1806 | +.. code-block:: mysql |
1807 | + |
1808 | + $ drizzle --user=root --password=foo |
1809 | + |
1810 | + drizzle> SELECT ID FROM DATA_DICTIONARY.SYS_REPLICATION_LOG LIMIT 1; |
1811 | + +------+ |
1812 | + | ID | |
1813 | + +------+ |
1814 | + | 772 | |
1815 | + +------+ |
1816 | + |
1817 | +The query should return a row. This is the table from which slaves read replication events. |
1818 | + |
1819 | +The master is now ready to replicate to slaves. |
1820 | + |
1821 | +Slave Setup |
1822 | +----------- |
1823 | + |
1824 | +The slave must be on a different sever than the master, else the two servers will have port conflicts. |
1825 | + |
1826 | +Since the slave is new and has no data, it will replicate all data from the master, including the :ref:`auth_schema_plugin` table just created. |
1827 | + |
1828 | +First, write a :ref:`slave_config_file`: |
1829 | + |
1830 | +.. code-block:: ini |
1831 | + |
1832 | + [master1] |
1833 | + master-host=10.0.0.1 |
1834 | + master-user=slave |
1835 | + master-pass=foo |
1836 | + |
1837 | +The :ref:`master-host option <slave_cfg_master_options>` must be set to the master server's address. 10.0.0.1 is just an example. |
1838 | + |
1839 | +Save the config file in :file:`/etc/drizzle/slave.cfg`. |
1840 | + |
1841 | +Then start the slave with the plugins required for :ref:`configuring_a_slave`: |
1842 | + |
1843 | +.. code-block:: bash |
1844 | + |
1845 | + sbin/drizzled \ |
1846 | + --daemon \ |
1847 | + --pid-file /var/run/drizzled/drizzled.pid \ |
1848 | + --plugin-add slave \ |
1849 | + --slave.config-file /etc/drizzle/slave.cfg \ |
1850 | + >> /var/log/drizzled.log 2>&1 |
1851 | + |
1852 | +Verify that the slave is running and applying replication events from the master: |
1853 | + |
1854 | +.. code-block:: mysql |
1855 | + |
1856 | + $ drizzle --user=root --password=foo |
1857 | + |
1858 | + drizzle> SELECT * FROM sys_replication.io_state\G |
1859 | + *************************** 1. row *************************** |
1860 | + master_id: 1 |
1861 | + status: RUNNING |
1862 | + error_msg: |
1863 | + |
1864 | + drizzle> SELECT * FROM sys_replication.applier_state\G |
1865 | + *************************** 1. row *************************** |
1866 | + master_id: 1 |
1867 | + last_applied_commit_id: 23 |
1868 | + originating_server_uuid: 98ECEA09-BA65-489D-9382-F8D15098B1AE |
1869 | + originating_commit_id: 23 |
1870 | + status: RUNNING |
1871 | + error_msg: |
1872 | + |
1873 | +The column values will vary, but the important column is ``status`` :ref:`RUNNING <slave_thread_statuses>` for both tables. |
1874 | + |
1875 | +After at least :ref:`applier-thread-sleep <slave_cfg_common_options>` or :ref:`io-thread-sleep <slave_cfg_common_options>` seconds, the :ref:`auth_schema_plugin` table should replicate from the master: |
1876 | + |
1877 | +.. code-block:: mysql |
1878 | + |
1879 | + drizzle> SELECT * FROM auth.users; |
1880 | + +-------+------------------------------------------+ |
1881 | + | user | password | |
1882 | + +-------+------------------------------------------+ |
1883 | + | root | F3A2A51A9B0F2BE2468926B4132313728C250DBF | |
1884 | + | slave | F3A2A51A9B0F2BE2468926B4132313728C250DBF | |
1885 | + +-------+------------------------------------------+ |
1886 | + |
1887 | +If not, then check the error log (:file:`/var/log/drizzled.log`) for errors. |
1888 | + |
1889 | +Check the :ref:`slave_lag` to ensure that the slave has applied all committed transactions from the master. |
1890 | + |
1891 | +Once the slave is fully caught up to the master, stop it, then start it again with the :ref:`auth_schema_plugin` plugin: |
1892 | + |
1893 | +.. code-block:: bash |
1894 | + |
1895 | + sbin/drizzled \ |
1896 | + --daemon \ |
1897 | + --pid-file /var/run/drizzled/drizzled.pid \ |
1898 | + --plugin-add slave \ |
1899 | + --slave.config-file /etc/drizzle/slave.cfg \ |
1900 | + --plugin-remove auth_all \ |
1901 | + --plugin-add auth_schema \ |
1902 | + >> /var/log/drizzled.log 2>&1 |
1903 | + |
1904 | +The root username and password should be required: |
1905 | + |
1906 | +.. code-block:: bash |
1907 | + |
1908 | + $ drizzle --user=root --password=foo |
1909 | + |
1910 | +The :ref:`sys_replication_tables` should still show that the :ref:`slave_threads` are :ref:`RUNNING <slave_thread_statuses>`. Any changes on the master should replicate to the slave within a few seconds. If any problems occur, consult the :ref:`slave` documentation or ask for :ref:`help`. Else, congratulations: you are up and running with slave-based Drizzle replication! Be sure to familiarize yourself with :ref:`slave_admin`. |
1911 | |
1912 | === added file 'docs/replication/index.rst' |
1913 | --- docs/replication/index.rst 1970-01-01 00:00:00 +0000 |
1914 | +++ docs/replication/index.rst 2012-03-18 00:36:19 +0000 |
1915 | @@ -0,0 +1,172 @@ |
1916 | +.. program:: drizzled |
1917 | + |
1918 | +.. _drizzle_replication: |
1919 | + |
1920 | +Drizzle Replication |
1921 | +=================== |
1922 | + |
1923 | +.. topic:: Want to skip the details and setup Drizzle replicaiton as quickly as possible? |
1924 | + |
1925 | + Then start with the |
1926 | + :ref:`Simple Master-Slave example <simple_master_slave_example>`. |
1927 | + Otherwise, start here and read each section in sequence for a complete |
1928 | + understanding of Drizzle replication. |
1929 | + |
1930 | +Drizzle encodes replication events as |
1931 | +`Google Protocol Buffer <http://code.google.com/p/protobuf/>`_ (GPB) messages |
1932 | +and transmits them asynchronously through replication streams. A replication |
1933 | +stream is a pair of one replicator and one applier. The kernel encodes |
1934 | +replication events, sends them to all available replicators, which in turn send |
1935 | +them to their paired appliers. For Drizzle, the replication process ends at |
1936 | +this point, but appliers are responsible for applying replication events to a |
1937 | +service: another Drizzle server (a slave), a message queue, etc. |
1938 | + |
1939 | +.. code-block:: none |
1940 | + |
1941 | + Drizzle External |
1942 | + ========================================================== ======== |
1943 | + User Kernel Plugins |
1944 | + ===== ================= ========================= |
1945 | + Replication Streams |
1946 | + ========================= |
1947 | + event --> encode GBP(event) +--> replicator1 +--> applier1 --> service1 |
1948 | + | | |
1949 | + | +--> applier2 --> service2 |
1950 | + | |
1951 | + +--> replicator2 +--> applier3 --> service3 |
1952 | + |
1953 | +Replicators and appliers are implemented by plugins, so Drizzle replication |
1954 | +is extensible and varies depending on which plugins are used. Drizzle |
1955 | +includes plugins to implement several replication systems: |
1956 | + |
1957 | +* :ref:`Master-slave replication, including multi-master <slave_applier>` |
1958 | +* :ref:`Replication to a RabbitMQ server <rabbitmq_applier>` |
1959 | +* :ref:`Replication to a ZeroMQ socket <zeromq_applier>` |
1960 | + |
1961 | +Master-slave is the most common replication system; it resembles other |
1962 | +database servers like MySQL. |
1963 | + |
1964 | +Unlike other database servers, the Drizzle kernel plays only a minimal role |
1965 | +in the replication process: it simply encodes and sends replication events |
1966 | +to available replicators. Consequently, there are very few |
1967 | +:ref:`drizzled replication options <drizzled_replication_options>`, and |
1968 | +Drizzle replication is primarily configured by replicator and applier |
1969 | +plugin options. |
1970 | + |
1971 | +In summary, Drizzle replication: |
1972 | + |
1973 | +* is asynchronous |
1974 | +* encodes replication events as Google Buffer Protocol messages |
1975 | +* sends replication events through replication streams (unique replicator-applier pairs) |
1976 | +* only uses the kernel to encode and send replication events to avaiable replicators |
1977 | +* is primarily implemented and configured by replicator and applier plugins |
1978 | +* is extensible |
1979 | + |
1980 | +Learned enough? Ready to start using Drizzle replication? Then jump to the |
1981 | +:ref:`replication examples <replication_examples>`. Otherwise, continue |
1982 | +reading for more details about all the parts and processes of Drizzle |
1983 | +replication. |
1984 | + |
1985 | +.. _replication_events: |
1986 | + |
1987 | +Replication Events |
1988 | +------------------ |
1989 | + |
1990 | +Replication events are, in general, any SQL statements which change data or |
1991 | +schema objects on a server. :doc:`/dml` queries are the primary cause of |
1992 | +replication events, but other statements like setting global variables or |
1993 | +altering schemas or tables may also cause replication events. |
1994 | + |
1995 | +The Drizzle kernel sends every replication event to every applier (that is |
1996 | +to say, every loaded applier plugin), but appliers determine if replicaiton |
1997 | +events are sent to their paired appliers. For example, a replicator may |
1998 | +filter certain replication events. Likewise, appliers determine if (and how) |
1999 | +replication events are ultimately applied. |
2000 | + |
2001 | +Replication events are not logged or saved by the Drizzle kernel or any |
2002 | +replicators that ship with Drizzle. An applier may log replication events |
2003 | +that it receives from its replicator. |
2004 | + |
2005 | +Every replication event is encapsulated as an atomic transaction, including |
2006 | +bulk and mutli-statement events. |
2007 | + |
2008 | +Drizzle relinquishes all control of replication events once they enter a |
2009 | +replication stream. Replicators and appliers are responsbile for handling |
2010 | +replication events correctly and efficiently. |
2011 | + |
2012 | +.. _replication_streams: |
2013 | + |
2014 | +Replication Streams |
2015 | +------------------- |
2016 | + |
2017 | +Replication stream are logical conduits created by pairing one replicator |
2018 | +with one applier. As logical entities, replicaiton streams exist only inside |
2019 | +the :program:`drizzled` process and cannot be accessed externally. However, |
2020 | +some appliers create or access ports or sockets which allows indirect access |
2021 | +to the replication stream. Since replicators and appliers are implemented |
2022 | +by plugins, one could in theory program a custom applier or replicator to |
2023 | +provide a socket or port for direct access into the replication stream. |
2024 | + |
2025 | +When :program:`drizlzed` starts, it creates replication streams automatically |
2026 | +based on which replicators are loaded and which appliers are loaded and |
2027 | +configured to use them. For example, an applier plugin may be configured |
2028 | +to use a specific replicator, in which case :program:`drizzled` pairs the |
2029 | +applier to the specified replicator. The user does not need to perform |
2030 | +special steps to create a replication stream. |
2031 | + |
2032 | +Replication stream cannot be dynamically recreated; the user must stop |
2033 | +Drizzle, reconfigure the replicator or applier, and then restart Drizzle to |
2034 | +let it automatically recreate the new replication stream. |
2035 | + |
2036 | +.. _originating_server: |
2037 | + |
2038 | +Originating Server |
2039 | +------------------ |
2040 | + |
2041 | +The originating server of a replication event is the server on which the |
2042 | +SQL statement that caused the replication was first executed. Since one |
2043 | +replicaiton event may be applied to several services (by passing through |
2044 | +multiple replication streams), the originating server uniquely identifies |
2045 | +the true origin of a replication event versus its most immediate upstream |
2046 | +origin which may have received the replication event from any number of |
2047 | +additional upstream sources. |
2048 | + |
2049 | +Drizzle automatically generates a UUID for every server, saved in the |
2050 | +:file:`server.uuid` file in the :option:`--datadir` directory. This UUID |
2051 | +is included with every replication event that originates from the server. |
2052 | + |
2053 | +An originating server may or may not contain both end points of a replication |
2054 | +stream. Replicators are always local to (loaded and ran from) the originating |
2055 | +server from which they receive replication events, but appliers may be local |
2056 | +or remote (loaded and ran on a different server). The external service to |
2057 | +which the applier applies replication events is usually another server, |
2058 | +not the originating server, but an applier could, in theory, apply events |
2059 | +from and to the same originating server. |
2060 | + |
2061 | +Configuration |
2062 | +------------- |
2063 | + |
2064 | +Drizzle replication is primarily configured by options specific to |
2065 | +each :ref:`replicator <replicators>` and :ref:`applier <appliers>`. |
2066 | + |
2067 | +The Drizzle kernel has very few :ref:`drizzled_replication_options` which |
2068 | +typically do not need to be changed: |
2069 | + |
2070 | +:option:`--transaction-message-threshold` |
2071 | + Controls the size, in bytes, of the transaction messages. |
2072 | + When a transaction message exceeds this size, a new transaction message |
2073 | + with the same transaction ID will be created to continue the replication |
2074 | + events. See :ref:`bulk-operations`. |
2075 | + |
2076 | +:option:`--replicate-query` |
2077 | + Controls whether the originating SQL query will be included within each |
2078 | + statement message contained in the enclosing transaction message. The |
2079 | + default global value is FALSE which will not include the query in the |
2080 | + messages. It can be controlled per session, as well. For example: |
2081 | + |
2082 | + .. code-block:: mysql |
2083 | + |
2084 | + drizzle> SET @@replicate_query = 1; |
2085 | + |
2086 | + The stored query should be used as a guide only, and never executed |
2087 | + on a slave to perform replication as this will lead to incorrect results. |
2088 | |
2089 | === added directory 'docs/replication/messages' |
2090 | === added file 'docs/replication/messages/index.rst' |
2091 | --- docs/replication/messages/index.rst 1970-01-01 00:00:00 +0000 |
2092 | +++ docs/replication/messages/index.rst 2012-03-18 00:36:19 +0000 |
2093 | @@ -0,0 +1,251 @@ |
2094 | +Messages |
2095 | +******** |
2096 | + |
2097 | +Message Definitions |
2098 | +=================== |
2099 | + |
2100 | +The GPB messages are defined in .proto files in the drizzled/message |
2101 | +directory of the Drizzle source code. The primary definition file is |
2102 | +transaction.proto. Messages defined in this file are related in the |
2103 | +following ways:: |
2104 | + |
2105 | + |
2106 | + ------------------------------------------------------------------ |
2107 | + | | |
2108 | + | Transaction message | |
2109 | + | | |
2110 | + | ----------------------------------------------------------- | |
2111 | + | | | | |
2112 | + | | TransactionContext message | | |
2113 | + | | | | |
2114 | + | ----------------------------------------------------------- | |
2115 | + | ----------------------------------------------------------- | |
2116 | + | | | | |
2117 | + | | Statement message 1 | | |
2118 | + | | | | |
2119 | + | ----------------------------------------------------------- | |
2120 | + | ----------------------------------------------------------- | |
2121 | + | | | | |
2122 | + | | Statement message 2 | | |
2123 | + | | | | |
2124 | + | ----------------------------------------------------------- | |
2125 | + | ... | |
2126 | + | ----------------------------------------------------------- | |
2127 | + | | | | |
2128 | + | | Statement message N | | |
2129 | + | | | | |
2130 | + | ----------------------------------------------------------- | |
2131 | + ------------------------------------------------------------------ |
2132 | + |
2133 | +with each Statement message looking like so:: |
2134 | + |
2135 | + ------------------------------------------------------------------ |
2136 | + | | |
2137 | + | Statement message | |
2138 | + | | |
2139 | + | ----------------------------------------------------------- | |
2140 | + | | | | |
2141 | + | | Common information | | |
2142 | + | | | | |
2143 | + | | - Type of Statement (INSERT, DELETE, etc) | | |
2144 | + | | - Start Timestamp | | |
2145 | + | | - End Timestamp | | |
2146 | + | | - (OPTIONAL) Actual SQL query string | | |
2147 | + | | | | |
2148 | + | ----------------------------------------------------------- | |
2149 | + | ----------------------------------------------------------- | |
2150 | + | | | | |
2151 | + | | Statement subclass message 1 (see below) | | |
2152 | + | | | | |
2153 | + | ----------------------------------------------------------- | |
2154 | + | ... | |
2155 | + | ----------------------------------------------------------- | |
2156 | + | | | | |
2157 | + | | Statement subclass message N (see below) | | |
2158 | + | | | | |
2159 | + | ----------------------------------------------------------- | |
2160 | + ------------------------------------------------------------------ |
2161 | + |
2162 | +The Transaction Message |
2163 | +======================= |
2164 | + |
2165 | +The main "envelope" message which represents an atomic transaction |
2166 | +which changed the state of a server is the Transaction message class. |
2167 | + |
2168 | +The Transaction message contains two pieces: |
2169 | + |
2170 | +#. A TransactionContext message containing information about the |
2171 | + transaction as a whole, such as the ID of the executing server, |
2172 | + the start and end timestamp of the transaction, segmenting |
2173 | + metadata and a unique identifier for the transaction. |
2174 | +#. A vector of Statement messages representing the distinct SQL |
2175 | + statements which modified the state of the server. The Statement |
2176 | + message is, itself, a generic envelope message containing a |
2177 | + sub-message which describes the specific data modification which |
2178 | + occurred on the server (such as, for instance, an INSERT statement). |
2179 | + |
2180 | +The Statement Message |
2181 | +===================== |
2182 | + |
2183 | +The generic "envelope" message containing information common to each |
2184 | +SQL statement executed against a server (such as a start and end timestamp |
2185 | +and the type of the SQL statement) as well as a Statement subclass message |
2186 | +describing the specific data modification event on the server. |
2187 | + |
2188 | +Each Statement message contains a type member which indicates how readers |
2189 | +of the Statement should construct the inner Statement subclass representing |
2190 | +a data change. |
2191 | + |
2192 | +Statements are recorded separately as sometimes individual statements |
2193 | +have to be rolled back. |
2194 | + |
2195 | + |
2196 | +.. _bulk-operations: |
2197 | + |
2198 | +How Bulk Operations Work |
2199 | +======================== |
2200 | + |
2201 | +Certain operations which change large volumes of data on a server |
2202 | +present a specific set of problems for a transaction coordinator or |
2203 | +replication service. If all operations must complete atomically on a |
2204 | +publishing server before replicas are delivered the complete |
2205 | +transactional unit: |
2206 | + |
2207 | +#. The publishing server could consume a large amount of memory |
2208 | + building an in-memory Transaction message containing all the |
2209 | + operations contained in the entire transaction. |
2210 | +#. A replica, or subscribing server, is wasting time waiting on the |
2211 | + eventual completion (commit) of the large transaction on the |
2212 | + publishing server. It could be applying pieces of the large |
2213 | + transaction in the meantime... |
2214 | + |
2215 | +In order to prevent the problems inherent in (1) and (2) above, Drizzle's |
2216 | +replication system uses a mechanism which provides bulk change |
2217 | +operations. |
2218 | + |
2219 | +A single transaction in the database can possibly be represented with |
2220 | +multiple protobuf Transaction messages if the message grows too large. |
2221 | +This can happen if you have a bulk transaction, or a single statement |
2222 | +affecting a very large number of rows, or just a large transaction with |
2223 | +many statements/changes. |
2224 | + |
2225 | +For the first two examples, it is likely that the Statement sub-message |
2226 | +itself will get segmented, causing another Transaction message to be |
2227 | +created to hold the rest of the Statement's row changes. In these cases, |
2228 | +it is enough to look at the segment information stored in the Statement |
2229 | +message (see example below). |
2230 | + |
2231 | +For the last example, the Statement sub-messages may or may not be |
2232 | +segmented, but we could still need to split the individual Statements up into |
2233 | +multiple Transaction messages to keep the Transaction message size from |
2234 | +growing too large. In this case, the segment information in the Statement |
2235 | +submessages is not helpful if the Statement isn't segmented. We need this |
2236 | +information in the Transaction message itself. |
2237 | + |
2238 | +Segmenting a Single SQL Statement |
2239 | +================================= |
2240 | + |
2241 | +When a regular SQL statement modifies or inserts more rows than a |
2242 | +certain threshold, Drizzle's replication services component will begin |
2243 | +sending Transaction messages to replicas which contain a chunk |
2244 | +(or "segment") of the data which has been changed on the publisher. |
2245 | + |
2246 | +When data is inserted, updated, or modified in the database, a |
2247 | +header containing information about modified tables and fields is |
2248 | +matched with one or more data segments which contain the actual |
2249 | +values changed in the statement. |
2250 | + |
2251 | +It's easiest to understand this mechanism by following through a real-world |
2252 | +scenario. |
2253 | + |
2254 | +Suppose the following table: |
2255 | + |
2256 | +.. code-block:: mysql |
2257 | + |
2258 | + CREATE TABLE test.person |
2259 | + ( |
2260 | + id INT NOT NULL AUTO_INCREMENT PRIMARY KEY |
2261 | + , first_name VARCHAR(50) |
2262 | + , last_name VARCHAR(50) |
2263 | + , is_active CHAR(1) NOT NULL DEFAULT 'Y' |
2264 | + ); |
2265 | + |
2266 | +Also suppose that test.t1 contains 1 million records. |
2267 | + |
2268 | +Next, suppose a client issues the SQL statement: |
2269 | + |
2270 | +.. code-block:: mysql |
2271 | + |
2272 | + UPDATE test.person SET is_active = 'N'; |
2273 | + |
2274 | +It is clear that one million records could be updated by this statement |
2275 | +(we say, "could be" since Drizzle does not actually update a record if |
2276 | +the UPDATE would not change the existing record...). |
2277 | + |
2278 | +In order to prevent the publishing server from having to construct an |
2279 | +enormous Transaction message, Drizzle's replication services component |
2280 | +will do the following: |
2281 | + |
2282 | +#. Construct a Transaction message with a transaction context containing |
2283 | + information about the originating server, the transaction ID, and |
2284 | + timestamp information. |
2285 | +#. Construct an UpdateHeader message with information about the tables |
2286 | + and fields involved in the UPDATE statement. Push this UpdateHeader |
2287 | + message onto the Transaction message's statement vector. |
2288 | +#. Construct an UpdateData message. Set the *segment_id* member to 1. |
2289 | + Set the *end_segment* member to true. |
2290 | +#. For every record updated in a storage engine, the ReplicationServices |
2291 | + component builds a new UpdateRecord message and appends this message |
2292 | + to the aforementioned UpdateData message's record vector. |
2293 | +#. After a certain threshold of records is reached, the |
2294 | + ReplicationServices component sets the current UpdateData message's |
2295 | + *end_segment* member to false, and proceeds to send the Transaction |
2296 | + message to replicators. |
2297 | +#. The ReplicationServices component then constructs a new Transaction |
2298 | + message and constructs a transaction context with the same |
2299 | + transaction ID and server information. |
2300 | +#. A new UpdateData message is created. The message's *segment_id* is |
2301 | + set to N+1 and as new records are updated, new UpdateRecord messages |
2302 | + are appended to the UpdateData message's record vector. |
2303 | +#. While records are being updated, we repeat steps 5 through 7, with |
2304 | + only the final UpdateData message having its *end_segment* member set |
2305 | + to true. |
2306 | + |
2307 | +Segmenting a Transaction |
2308 | +======================== |
2309 | + |
2310 | +The Transaction protobuf message also contains *segment_id* member and a |
2311 | +*end_segment* member. These values are also set appropriately when a |
2312 | +Statement sub-message is segmented, as described above. |
2313 | + |
2314 | +These values are also set when a Transaction must be segmented along |
2315 | +individual Statement boundaries (i.e., the Statement message itself |
2316 | +is **not** segmented). In either case, it is enough to check the |
2317 | +*end_segment* and *segment_id* values of the Transaction message |
2318 | +to determine if this is a multi-message transaction. |
2319 | + |
2320 | +Handling ROLLBACKs |
2321 | +================== |
2322 | + |
2323 | +Both transactions and individual statements may be rolled back. |
2324 | + |
2325 | +When a transaction is rolled back, one of two things happen depending |
2326 | +on whether the transaction is made up of either a single Transaction |
2327 | +message, or if it is made up of multiple Transaction messages (e.g, bulk |
2328 | +load). |
2329 | + |
2330 | +* For a transaction encapsulated entirely within a single Transaction |
2331 | + message, the entire message is simply discarded and not sent through |
2332 | + the replication stream. |
2333 | +* For a transaction which is made up of multiple messages, and at least |
2334 | + one message has already been sent through the replication stream, then |
2335 | + the Transaction message will contain a Statement message with type = |
2336 | + ROLLBACK. This signifies to rollback the entire transaction. |
2337 | + |
2338 | +A special Statement message type, ROLLBACK_STATEMENT, is used when |
2339 | +we have a segmented Statement message (see above) and we need to tell the |
2340 | +receiver to undo any changes made for this single statement, but not |
2341 | +for the entire transaction. If the receiver cannot handle rolling back |
2342 | +a single statement, then a message buffering strategy should be employed |
2343 | +to guarantee that a statement was indeed applied successfully before |
2344 | +executing on the receiver. |
2345 | |
2346 | === added directory 'docs/replication/replicators' |
2347 | === added file 'docs/replication/replicators/default.rst' |
2348 | --- docs/replication/replicators/default.rst 1970-01-01 00:00:00 +0000 |
2349 | +++ docs/replication/replicators/default.rst 2012-03-18 00:36:19 +0000 |
2350 | @@ -0,0 +1,64 @@ |
2351 | +.. _default_replicator: |
2352 | + |
2353 | +Default Replicator |
2354 | +================== |
2355 | + |
2356 | +The default replicator plugin, cleverly named ``default_replicator``, |
2357 | +does not modify or filter any replication events; it simply sends every |
2358 | +replication event it receives from the Drizzle kernel to every applier |
2359 | +with which it is paired. |
2360 | + |
2361 | +:ref:`appliers` default to this replicator. |
2362 | + |
2363 | +.. _default_replicator_loading: |
2364 | + |
2365 | +Loading |
2366 | +------- |
2367 | + |
2368 | +This plugin is loaded by default. To stop the plugin from loading by |
2369 | +default, start :program:`drizzled` with:: |
2370 | + |
2371 | + --plugin-remove=default_replicator |
2372 | + |
2373 | +.. seealso:: :ref:`drizzled_plugin_options` for more information about adding and removing plugins. |
2374 | + |
2375 | +.. _default_replicator_configuration: |
2376 | + |
2377 | +Configuration |
2378 | +------------- |
2379 | + |
2380 | +This plugin does not have any command line options. |
2381 | + |
2382 | +.. _default_replicator_variables: |
2383 | + |
2384 | +Variables |
2385 | +--------- |
2386 | + |
2387 | +This plugin does not register any variables. |
2388 | + |
2389 | +.. _default_replicator_authors: |
2390 | + |
2391 | +Authors |
2392 | +------- |
2393 | + |
2394 | +Jay Pipes |
2395 | + |
2396 | +.. _default_replicator_version: |
2397 | + |
2398 | +Version |
2399 | +------- |
2400 | + |
2401 | +This documentation applies to **default_replicator 1.0**. |
2402 | + |
2403 | +To see which version of the plugin a Drizzle server is running, execute: |
2404 | + |
2405 | +.. code-block:: mysql |
2406 | + |
2407 | + SELECT MODULE_VERSION FROM DATA_DICTIONARY.MODULES WHERE MODULE_NAME='default_replicator' |
2408 | + |
2409 | +Changelog |
2410 | +--------- |
2411 | + |
2412 | +v1.0 |
2413 | +^^^^ |
2414 | +* First release. |
2415 | |
2416 | === added file 'docs/replication/replicators/filtered.rst' |
2417 | --- docs/replication/replicators/filtered.rst 1970-01-01 00:00:00 +0000 |
2418 | +++ docs/replication/replicators/filtered.rst 2012-03-18 00:36:19 +0000 |
2419 | @@ -0,0 +1,143 @@ |
2420 | +.. _filtered_replicator: |
2421 | + |
2422 | +Filtered Replicator |
2423 | +=================== |
2424 | + |
2425 | +The filtered replicator plugin, named ``filtered_replicator``, filters |
2426 | +replication events based on schema name or table name. Regular expressions |
2427 | +can be used for the schema and table names. |
2428 | + |
2429 | +.. _filtered_replicator_loading: |
2430 | + |
2431 | +Loading |
2432 | +------- |
2433 | + |
2434 | +To load this plugin, start :program:`drizzled` with:: |
2435 | + |
2436 | + --plugin-add=filtered_replicator |
2437 | + |
2438 | +Loading the plugin may not enable or configure it. See the plugin's |
2439 | +:ref:`filtered_replicator_configuration` and :ref:`filtered_replicator_variables`. |
2440 | + |
2441 | +.. seealso:: :ref:`drizzled_plugin_options` for more information about adding and removing plugins. |
2442 | + |
2443 | +.. _filtered_replicator_configuration: |
2444 | + |
2445 | +Configuration |
2446 | +------------- |
2447 | + |
2448 | +These command line options configure the plugin when :program:`drizzled` |
2449 | +is started. See :ref:`command_line_options` for more information about |
2450 | +specifying command line options. |
2451 | + |
2452 | +.. program:: drizzled |
2453 | + |
2454 | +.. option:: --filtered-replicator.filteredschemas ARG |
2455 | + |
2456 | + :Default: |
2457 | + :Variable: :ref:`filtered_replicator_filteredschemas <filtered_replicator_filteredschemas>` |
2458 | + |
2459 | + Comma-separated list of schemas to exclude from replication. |
2460 | + |
2461 | +.. option:: --filtered-replicator.filteredtables ARG |
2462 | + |
2463 | + :Default: |
2464 | + :Variable: :ref:`filtered_replicator_filteredtables <filtered_replicator_filteredtables>` |
2465 | + |
2466 | + Comma-separated list of tables to exclude from replication. |
2467 | + |
2468 | +.. option:: --filtered-replicator.schemaregex ARG |
2469 | + |
2470 | + :Default: |
2471 | + :Variable: :ref:`filtered_replicator_schemaregex <filtered_replicator_schemaregex>` |
2472 | + |
2473 | + Regular expression to apply to schemas to exclude from replication. |
2474 | + |
2475 | +.. option:: --filtered-replicator.tableregex ARG |
2476 | + |
2477 | + :Default: |
2478 | + :Variable: :ref:`filtered_replicator_tableregex <filtered_replicator_tableregex>` |
2479 | + |
2480 | + Regular expression to apply to tables to exclude from replication. |
2481 | + |
2482 | +.. _filtered_replicator_variables: |
2483 | + |
2484 | +Variables |
2485 | +--------- |
2486 | + |
2487 | +These variables show the running configuration of the plugin. |
2488 | +See `variables` for more information about querying and setting variables. |
2489 | + |
2490 | +.. _filtered_replicator_filteredschemas: |
2491 | + |
2492 | +* ``filtered_replicator_filteredschemas`` |
2493 | + |
2494 | + :Scope: Global |
2495 | + :Dynamic: No |
2496 | + :Option: :option:`--filtered-replicator.filteredschemas` |
2497 | + |
2498 | + Comma-separated list of schemas to exclude from replication. |
2499 | + |
2500 | +.. _filtered_replicator_filteredtables: |
2501 | + |
2502 | +* ``filtered_replicator_filteredtables`` |
2503 | + |
2504 | + :Scope: Global |
2505 | + :Dynamic: No |
2506 | + :Option: :option:`--filtered-replicator.filteredtables` |
2507 | + |
2508 | + Comma-separated list of tables to exclude from replication. |
2509 | + |
2510 | +.. _filtered_replicator_schemaregex: |
2511 | + |
2512 | +* ``filtered_replicator_schemaregex`` |
2513 | + |
2514 | + :Scope: Global |
2515 | + :Dynamic: No |
2516 | + :Option: :option:`--filtered-replicator.schemaregex` |
2517 | + |
2518 | + Regular expression to apply to schemas to exclude from replication. |
2519 | + |
2520 | +.. _filtered_replicator_tableregex: |
2521 | + |
2522 | +* ``filtered_replicator_tableregex`` |
2523 | + |
2524 | + :Scope: Global |
2525 | + :Dynamic: No |
2526 | + :Option: :option:`--filtered-replicator.tableregex` |
2527 | + |
2528 | + Regular expression to apply to tables to exclude from replication. |
2529 | + |
2530 | +.. _filtered_replicator_examples: |
2531 | + |
2532 | +Examples |
2533 | +-------- |
2534 | + |
2535 | +Sorry, there are no examples for this plugin. |
2536 | + |
2537 | +.. _filtered_replicator_authors: |
2538 | + |
2539 | +Authors |
2540 | +------- |
2541 | + |
2542 | +Padraig O Sullivan |
2543 | + |
2544 | +.. _filtered_replicator_version: |
2545 | + |
2546 | +Version |
2547 | +------- |
2548 | + |
2549 | +This documentation applies to **filtered_replicator 0.2**. |
2550 | + |
2551 | +To see which version of the plugin a Drizzle server is running, execute: |
2552 | + |
2553 | +.. code-block:: mysql |
2554 | + |
2555 | + SELECT MODULE_VERSION FROM DATA_DICTIONARY.MODULES WHERE MODULE_NAME='filtered_replicator' |
2556 | + |
2557 | +Chagnelog |
2558 | +--------- |
2559 | + |
2560 | +v0.2 |
2561 | +^^^^ |
2562 | +* First release. |
2563 | |
2564 | === added file 'docs/replication/replicators/index.rst' |
2565 | --- docs/replication/replicators/index.rst 1970-01-01 00:00:00 +0000 |
2566 | +++ docs/replication/replicators/index.rst 2012-03-18 00:36:19 +0000 |
2567 | @@ -0,0 +1,28 @@ |
2568 | +.. _replicators: |
2569 | + |
2570 | +.. _replication_replicators: |
2571 | + |
2572 | +Replicators |
2573 | +=========== |
2574 | + |
2575 | +Replicators are one end point of a |
2576 | +:ref:`replication stream <replication_streams>` which provide an interface |
2577 | +between the Drizzle kernel and :ref:`appliers`. The Drizzle kernel sends |
2578 | +replication events, encoded as Google Buffer Protocol message, to every |
2579 | +replicator that was loaded when Drizzled was stared. |
2580 | +Replicators implement specific behaviors by modifying or filtering |
2581 | +replication events before sending them to their paired appliers. |
2582 | +For example, a replicator may filter replication events from specific schemas |
2583 | +or tables. There are no restrictions on how a replicator can modify |
2584 | +replication events. |
2585 | + |
2586 | +Replicators are implemented by plugins and have unique names. Most appliers |
2587 | +can be configured to use a specific replicator by specifying its unique name. |
2588 | + |
2589 | +Drizzle includes the following replicator plugins: |
2590 | + |
2591 | +.. toctree:: |
2592 | + :maxdepth: 1 |
2593 | + :glob: |
2594 | + |
2595 | + * |
2596 | |
2597 | === modified file 'plugin/default_replicator/docs/index.rst' |
2598 | --- plugin/default_replicator/docs/index.rst 2011-10-23 05:45:09 +0000 |
2599 | +++ plugin/default_replicator/docs/index.rst 2012-03-18 00:36:19 +0000 |
2600 | @@ -1,66 +1,4 @@ |
2601 | -.. _default_replicator_plugin: |
2602 | - |
2603 | Default Replicator |
2604 | ================== |
2605 | |
2606 | -:program:`default_replicator` is a simple replicator which replicates all |
2607 | -write events to all appliers. |
2608 | - |
2609 | -.. seealso:: :doc:`/replication/drizzle` |
2610 | - |
2611 | -.. _default_replicator_loading: |
2612 | - |
2613 | -Loading |
2614 | -------- |
2615 | - |
2616 | -This plugin is loaded by default, but it may need to be configured. See |
2617 | -the plugin's :ref:`default_replicator_configuration` and |
2618 | -:ref:`default_replicator_variables`. |
2619 | - |
2620 | -To stop the plugin from loading by default, start :program:`drizzled` |
2621 | -with:: |
2622 | - |
2623 | - --plugin-remove=default_replicator |
2624 | - |
2625 | -.. seealso:: :ref:`drizzled_plugin_options` for more information about adding and removing plugins. |
2626 | - |
2627 | -.. _default_replicator_configuration: |
2628 | - |
2629 | -Configuration |
2630 | -------------- |
2631 | - |
2632 | -This plugin does not have any command line options. |
2633 | - |
2634 | -.. _default_replicator_variables: |
2635 | - |
2636 | -Variables |
2637 | ---------- |
2638 | - |
2639 | -This plugin does not register any variables. |
2640 | - |
2641 | -.. _default_replicator_authors: |
2642 | - |
2643 | -Authors |
2644 | -------- |
2645 | - |
2646 | -Jay Pipes |
2647 | - |
2648 | -.. _default_replicator_version: |
2649 | - |
2650 | -Version |
2651 | -------- |
2652 | - |
2653 | -This documentation applies to **default_replicator 1.0**. |
2654 | - |
2655 | -To see which version of the plugin a Drizzle server is running, execute: |
2656 | - |
2657 | -.. code-block:: mysql |
2658 | - |
2659 | - SELECT MODULE_VERSION FROM DATA_DICTIONARY.MODULES WHERE MODULE_NAME='default_replicator' |
2660 | - |
2661 | -Changelog |
2662 | ---------- |
2663 | - |
2664 | -v1.0 |
2665 | -^^^^ |
2666 | -* First release. |
2667 | +See :ref:`default_replicator`. |
2668 | |
2669 | === modified file 'plugin/filtered_replicator/docs/index.rst' |
2670 | --- plugin/filtered_replicator/docs/index.rst 2011-10-23 05:45:09 +0000 |
2671 | +++ plugin/filtered_replicator/docs/index.rst 2012-03-18 00:36:19 +0000 |
2672 | @@ -1,145 +1,4 @@ |
2673 | -.. _filtered_replicator_plugin: |
2674 | - |
2675 | Filtered Replicator |
2676 | =================== |
2677 | |
2678 | -The Filtered Replicator plugin registers itself in the Drizzle kernel |
2679 | -replication stream process as a new replicator (see :ref:`replication_streams` |
2680 | -for more information). It provides a way to filter replication messages by |
2681 | -schema name or table name. Regular expressions can be used for the schema and |
2682 | -table names. |
2683 | - |
2684 | -.. _filtered_replicator_loading: |
2685 | - |
2686 | -Loading |
2687 | -------- |
2688 | - |
2689 | -To load this plugin, start :program:`drizzled` with:: |
2690 | - |
2691 | - --plugin-add=filtered_replicator |
2692 | - |
2693 | -Loading the plugin may not enable or configure it. See the plugin's |
2694 | -:ref:`filtered_replicator_configuration` and :ref:`filtered_replicator_variables`. |
2695 | - |
2696 | -.. seealso:: :ref:`drizzled_plugin_options` for more information about adding and removing plugins. |
2697 | - |
2698 | -.. _filtered_replicator_configuration: |
2699 | - |
2700 | -Configuration |
2701 | -------------- |
2702 | - |
2703 | -These command line options configure the plugin when :program:`drizzled` |
2704 | -is started. See :ref:`command_line_options` for more information about specifying |
2705 | -command line options. |
2706 | - |
2707 | -.. program:: drizzled |
2708 | - |
2709 | -.. option:: --filtered-replicator.filteredschemas ARG |
2710 | - |
2711 | - :Default: |
2712 | - :Variable: :ref:`filtered_replicator_filteredschemas <filtered_replicator_filteredschemas>` |
2713 | - |
2714 | - Comma-separated list of schemas to exclude from replication. |
2715 | - |
2716 | -.. option:: --filtered-replicator.filteredtables ARG |
2717 | - |
2718 | - :Default: |
2719 | - :Variable: :ref:`filtered_replicator_filteredtables <filtered_replicator_filteredtables>` |
2720 | - |
2721 | - Comma-separated list of tables to exclude from replication. |
2722 | - |
2723 | -.. option:: --filtered-replicator.schemaregex ARG |
2724 | - |
2725 | - :Default: |
2726 | - :Variable: :ref:`filtered_replicator_schemaregex <filtered_replicator_schemaregex>` |
2727 | - |
2728 | - Regular expression to apply to schemas to exclude from replication. |
2729 | - |
2730 | -.. option:: --filtered-replicator.tableregex ARG |
2731 | - |
2732 | - :Default: |
2733 | - :Variable: :ref:`filtered_replicator_tableregex <filtered_replicator_tableregex>` |
2734 | - |
2735 | - Regular expression to apply to tables to exclude from replication. |
2736 | - |
2737 | -.. _filtered_replicator_variables: |
2738 | - |
2739 | -Variables |
2740 | ---------- |
2741 | - |
2742 | -These variables show the running configuration of the plugin. |
2743 | -See `variables` for more information about querying and setting variables. |
2744 | - |
2745 | -.. _filtered_replicator_filteredschemas: |
2746 | - |
2747 | -* ``filtered_replicator_filteredschemas`` |
2748 | - |
2749 | - :Scope: Global |
2750 | - :Dynamic: No |
2751 | - :Option: :option:`--filtered-replicator.filteredschemas` |
2752 | - |
2753 | - Comma-separated list of schemas to exclude from replication. |
2754 | - |
2755 | -.. _filtered_replicator_filteredtables: |
2756 | - |
2757 | -* ``filtered_replicator_filteredtables`` |
2758 | - |
2759 | - :Scope: Global |
2760 | - :Dynamic: No |
2761 | - :Option: :option:`--filtered-replicator.filteredtables` |
2762 | - |
2763 | - Comma-separated list of tables to exclude from replication. |
2764 | - |
2765 | -.. _filtered_replicator_schemaregex: |
2766 | - |
2767 | -* ``filtered_replicator_schemaregex`` |
2768 | - |
2769 | - :Scope: Global |
2770 | - :Dynamic: No |
2771 | - :Option: :option:`--filtered-replicator.schemaregex` |
2772 | - |
2773 | - Regular expression to apply to schemas to exclude from replication. |
2774 | - |
2775 | -.. _filtered_replicator_tableregex: |
2776 | - |
2777 | -* ``filtered_replicator_tableregex`` |
2778 | - |
2779 | - :Scope: Global |
2780 | - :Dynamic: No |
2781 | - :Option: :option:`--filtered-replicator.tableregex` |
2782 | - |
2783 | - Regular expression to apply to tables to exclude from replication. |
2784 | - |
2785 | -.. _filtered_replicator_examples: |
2786 | - |
2787 | -Examples |
2788 | --------- |
2789 | - |
2790 | -Sorry, there are no examples for this plugin. |
2791 | - |
2792 | -.. _filtered_replicator_authors: |
2793 | - |
2794 | -Authors |
2795 | -------- |
2796 | - |
2797 | -Padraig O Sullivan |
2798 | - |
2799 | -.. _filtered_replicator_version: |
2800 | - |
2801 | -Version |
2802 | -------- |
2803 | - |
2804 | -This documentation applies to **filtered_replicator 0.2**. |
2805 | - |
2806 | -To see which version of the plugin a Drizzle server is running, execute: |
2807 | - |
2808 | -.. code-block:: mysql |
2809 | - |
2810 | - SELECT MODULE_VERSION FROM DATA_DICTIONARY.MODULES WHERE MODULE_NAME='filtered_replicator' |
2811 | - |
2812 | -Chagnelog |
2813 | ---------- |
2814 | - |
2815 | -v0.2 |
2816 | -^^^^ |
2817 | -* First release. |
2818 | +See :ref:`filtered_replicator`. |
2819 | |
2820 | === modified file 'plugin/innobase/docs/index.rst' |
2821 | --- plugin/innobase/docs/index.rst 2012-03-08 00:54:48 +0000 |
2822 | +++ plugin/innobase/docs/index.rst 2012-03-18 00:36:19 +0000 |
2823 | @@ -49,10 +49,10 @@ |
2824 | |
2825 | .. _innodb_transaction_log: |
2826 | |
2827 | -InnoDB Transaction Log |
2828 | +InnoDB Replicaiton Log |
2829 | ---------------------- |
2830 | |
2831 | -The :program:`innodb` plugin provides a mechanism to store replication |
2832 | +The ``innodb`` plugin provides a mechanism to store replication |
2833 | events in an InnoDB table. When enabled, this transaction log can be accessed |
2834 | through the SYS_REPLICATION_LOG and INNODB_REPLICATION_LOG tables in the |
2835 | DATA_DICTIONARY schema. |
2836 | @@ -524,6 +524,13 @@ |
2837 | |
2838 | Use InnoDB's internal memory allocator instead of the system's malloc. |
2839 | |
2840 | +.. option:: --innodb.use-replicator |
2841 | + |
2842 | + :Default: default |
2843 | + :Variable: `innodb_use_replicator <innodb_use_sys_malloc>` |
2844 | + |
2845 | + Use this replicator for the :ref:`innodb_transaction_log`. |
2846 | + |
2847 | .. option:: --innodb.version ARG |
2848 | |
2849 | :Default: |
2850 | @@ -1110,6 +1117,16 @@ |
2851 | |
2852 | If system or internal malloc() is being used. |
2853 | |
2854 | +.. _innodb_use_replicator: |
2855 | + |
2856 | +* ``innodb_use_replicator`` |
2857 | + |
2858 | + :Scope: Global |
2859 | + :Dynamic: No |
2860 | + :Option: :option:`--innodb.use-replicator` |
2861 | + |
2862 | + Replicator to which the :ref:`innodb_transaction_log` is paired. |
2863 | + |
2864 | .. _innodb_version_var: |
2865 | |
2866 | * ``innodb_version`` |
2867 | |
2868 | === modified file 'plugin/rabbitmq/docs/index.rst' |
2869 | --- plugin/rabbitmq/docs/index.rst 2011-10-23 05:45:09 +0000 |
2870 | +++ plugin/rabbitmq/docs/index.rst 2012-03-18 00:36:19 +0000 |
2871 | @@ -1,243 +1,6 @@ |
2872 | .. _rabbitmq_plugin: |
2873 | |
2874 | RabbitMQ Integration |
2875 | -====================== |
2876 | - |
2877 | -It is possible to replicate transactions directly to a `RabbitMQ <http://www.rabbitmq.org>`_ server from drizzle, this could be used to create advanced replication solutions, to visualize data, or to build triggers. For example, `RabbitReplication <http://www.rabbitreplication.org>`_ has been built to consume the messages from rabbitmq, transform them, and persist the data in drizzle, mysql, many nosql stores and even replicating directly to websockets for data visualization. |
2878 | - |
2879 | -Loading |
2880 | -------- |
2881 | - |
2882 | -To load this plugin, start :program:`drizzled` with:: |
2883 | - |
2884 | - --plugin-add=rabbitmq |
2885 | - |
2886 | -Loading the plugin may not enable or configure it. See the plugin's |
2887 | -:ref:`rabbitmq_configuration` and :ref:`rabbitmq_variables`. |
2888 | - |
2889 | -.. seealso:: :ref:`drizzled_plugin_options` for more information about adding and removing plugins. |
2890 | - |
2891 | -.. _rabbitmq_configuration: |
2892 | - |
2893 | -Configuration |
2894 | -------------- |
2895 | - |
2896 | -These command line options configure the plugin when :program:`drizzled` |
2897 | -is started. See :ref:`command_line_options` for more information about specifying |
2898 | -command line options. |
2899 | - |
2900 | -.. program:: drizzled |
2901 | - |
2902 | -.. option:: --rabbitmq.exchange ARG |
2903 | - |
2904 | - :Default: ReplicationExchange |
2905 | - :Variable: :ref:`rabbitmq_exchange <rabbitmq_exchange>` |
2906 | - |
2907 | - Name of RabbitMQ exchange to publish to |
2908 | - |
2909 | -.. option:: --rabbitmq.host ARG |
2910 | - |
2911 | - :Default: localhost |
2912 | - :Variable: :ref:`rabbitmq_host <rabbitmq_host>` |
2913 | - |
2914 | - Host name to connect to |
2915 | - |
2916 | -.. option:: --rabbitmq.password ARG |
2917 | - |
2918 | - :Default: guest |
2919 | - :Variable: :ref:`rabbitmq_password <rabbitmq_password>` |
2920 | - |
2921 | - RabbitMQ password |
2922 | - |
2923 | -.. option:: --rabbitmq.port ARG |
2924 | - |
2925 | - :Default: 5672 |
2926 | - :Variable: :ref:`rabbitmq_port <rabbitmq_port>` |
2927 | - |
2928 | - Port to connect to |
2929 | - |
2930 | -.. option:: --rabbitmq.routingkey ARG |
2931 | - |
2932 | - :Default: ReplicationRoutingKey |
2933 | - :Variable: :ref:`rabbitmq_routingkey <rabbitmq_routingkey>` |
2934 | - |
2935 | - Name of RabbitMQ routing key to use |
2936 | - |
2937 | -.. option:: --rabbitmq.use-replicator ARG |
2938 | - |
2939 | - :Default: default_replicator |
2940 | - :Variable: |
2941 | - |
2942 | - Name of the replicator plugin to use (default='default_replicator') |
2943 | - |
2944 | -.. option:: --rabbitmq.username ARG |
2945 | - |
2946 | - :Default: guest |
2947 | - :Variable: :ref:`rabbitmq_username <rabbitmq_username>` |
2948 | - |
2949 | - RabbitMQ username |
2950 | - |
2951 | -.. option:: --rabbitmq.virtualhost ARG |
2952 | - |
2953 | - :Default: / |
2954 | - :Variable: :ref:`rabbitmq_virtualhost <rabbitmq_virtualhost>` |
2955 | - |
2956 | - RabbitMQ virtualhost |
2957 | - |
2958 | -.. _rabbitmq_variables: |
2959 | - |
2960 | -Variables |
2961 | ---------- |
2962 | - |
2963 | -These variables show the running configuration of the plugin. |
2964 | -See `variables` for more information about querying and setting variables. |
2965 | - |
2966 | -.. _rabbitmq_exchange: |
2967 | - |
2968 | -* ``rabbitmq_exchange`` |
2969 | - |
2970 | - :Scope: Global |
2971 | - :Dynamic: No |
2972 | - :Option: :option:`--rabbitmq.exchange` |
2973 | - |
2974 | - Name of RabbitMQ exchange to publish to |
2975 | - |
2976 | -.. _rabbitmq_host: |
2977 | - |
2978 | -* ``rabbitmq_host`` |
2979 | - |
2980 | - :Scope: Global |
2981 | - :Dynamic: No |
2982 | - :Option: :option:`--rabbitmq.host` |
2983 | - |
2984 | - Host name to connect to |
2985 | - |
2986 | -.. _rabbitmq_password: |
2987 | - |
2988 | -* ``rabbitmq_password`` |
2989 | - |
2990 | - :Scope: Global |
2991 | - :Dynamic: No |
2992 | - :Option: :option:`--rabbitmq.password` |
2993 | - |
2994 | - RabbitMQ password |
2995 | - |
2996 | -.. _rabbitmq_port: |
2997 | - |
2998 | -* ``rabbitmq_port`` |
2999 | - |
3000 | - :Scope: Global |
3001 | - :Dynamic: No |
3002 | - :Option: :option:`--rabbitmq.port` |
3003 | - |
3004 | - Port to connect to |
3005 | - |
3006 | -.. _rabbitmq_routingkey: |
3007 | - |
3008 | -* ``rabbitmq_routingkey`` |
3009 | - |
3010 | - :Scope: Global |
3011 | - :Dynamic: No |
3012 | - :Option: :option:`--rabbitmq.routingkey` |
3013 | - |
3014 | - Name of RabbitMQ routing key to use |
3015 | - |
3016 | -.. _rabbitmq_username: |
3017 | - |
3018 | -* ``rabbitmq_username`` |
3019 | - |
3020 | - :Scope: Global |
3021 | - :Dynamic: No |
3022 | - :Option: :option:`--rabbitmq.username` |
3023 | - |
3024 | - RabbitMQ username |
3025 | - |
3026 | -.. _rabbitmq_virtualhost: |
3027 | - |
3028 | -* ``rabbitmq_virtualhost`` |
3029 | - |
3030 | - :Scope: Global |
3031 | - :Dynamic: No |
3032 | - :Option: :option:`--rabbitmq.virtualhost` |
3033 | - |
3034 | - RabbitMQ virtualhost |
3035 | - |
3036 | -.. _rabbitmq_examples: |
3037 | - |
3038 | -Examples |
3039 | --------- |
3040 | - |
3041 | -First install a recent version of RabbitMQ, then install librabbitmq, the C library for talking to the RabbitMQ server: |
3042 | - |
3043 | -.. code-block:: bash |
3044 | - |
3045 | - $ hg clone http://hg.rabbitmq.com/rabbitmq-codegen/ |
3046 | - $ hg clone http://hg.rabbitmq.com/rabbitmq-c/ |
3047 | - $ cd rabbitmq-c |
3048 | - $ autoreconf -f -i |
3049 | - $ ./configure |
3050 | - $ make |
3051 | - $ make install |
3052 | - |
3053 | -Now you probably need to rebuild Drizzle since the :program:`rabbitmq` plugin is not built if librabbitmq is not installed. |
3054 | - |
3055 | -Finally, start :program:`drizzled` like: |
3056 | - |
3057 | -.. code-block:: bash |
3058 | - |
3059 | - sbin/drizzled --plugin-add rabbitmq,default-replicator \ |
3060 | - --rabbitmq.use-replicator default |
3061 | - |
3062 | -To verify that it works, you can start a generic rabbitmq listener from librabbitmq: |
3063 | - |
3064 | -.. code-block:: bash |
3065 | - |
3066 | - $ amqp_listen localhost 5672 ReplicationExchange ReplicationRoutingKey |
3067 | - |
3068 | -And you should see something like this when you do an INSERT/CREATE/.. (just not a select) in your newly built Drizzle instance:: |
3069 | - |
3070 | - Result 0 |
3071 | - Frame type 1, channel 1 |
3072 | - Method AMQP_BASIC_DELIVER_METHOD |
3073 | - Delivery 1, exchange ReplicationExchange routingkey ReplicationRoutingKey |
3074 | - |
3075 | - 00000000: 0A 17 08 01 10 87 36 18 : F0 FA D9 99 FA F1 A7 02 ......6......... |
3076 | - 00000010: 20 99 81 DA 99 FA F1 A7 : 02 12 40 08 01 10 F2 FA .........@..... |
3077 | - 00000020: D9 99 FA F1 A7 02 18 FC : FA D9 99 FA F1 A7 02 2A ...............* |
3078 | - 00000030: 17 0A 06 0A 01 62 12 01 : 61 12 06 08 04 12 02 69 .....b..a......i |
3079 | - 00000040: 64 12 05 08 01 12 01 74 : 32 11 08 01 10 01 1A 0B d......t2....... |
3080 | - 00000050: 0A 01 32 0A 02 61 61 10 : 00 10 00 20 01 28 01 ..2..aa.... .(. |
3081 | - 0000005F: |
3082 | - |
3083 | -Implementation Details |
3084 | ----------------------- |
3085 | - |
3086 | -* :program:`drizzled` will not sart if the rabbitmq server is not available. |
3087 | -* If the rabbitmq server goes away, the plugin will try to reconnect and resend the message 3 times, after that, the transaction is rolled back. |
3088 | - |
3089 | -.. _rabbitmq_authors: |
3090 | - |
3091 | -Authors |
3092 | -------- |
3093 | - |
3094 | -Marcus Eriksson |
3095 | - |
3096 | -.. _rabbitmq_version: |
3097 | - |
3098 | -Version |
3099 | -------- |
3100 | - |
3101 | -This documentation applies to **rabbitmq 0.1**. |
3102 | - |
3103 | -To see which version of the plugin a Drizzle server is running, execute: |
3104 | - |
3105 | -.. code-block:: mysql |
3106 | - |
3107 | - SELECT MODULE_VERSION FROM DATA_DICTIONARY.MODULES WHERE MODULE_NAME='rabbitmq' |
3108 | - |
3109 | -Changelog |
3110 | ---------- |
3111 | - |
3112 | -v0.1 |
3113 | -^^^^ |
3114 | -* First release. |
3115 | +==================== |
3116 | + |
3117 | +See :ref:`rabbitmq_applier`. |
3118 | |
3119 | === removed file 'plugin/slave/docs/admin.rst' |
3120 | --- plugin/slave/docs/admin.rst 2011-03-11 18:38:09 +0000 |
3121 | +++ plugin/slave/docs/admin.rst 1970-01-01 00:00:00 +0000 |
3122 | @@ -1,136 +0,0 @@ |
3123 | -******************************** |
3124 | -Replication Slave Administration |
3125 | -******************************** |
3126 | - |
3127 | -This page walks you through some common administration tasks when using |
3128 | -the replication slave plugin. |
3129 | - |
3130 | -Monitoring the Master |
3131 | -##################### |
3132 | - |
3133 | -Slave Connections |
3134 | -***************** |
3135 | - |
3136 | -If you want to determine which slave machines are connected to your |
3137 | -master, use the *SHOW PROCESSLIST* command. Slave connections will show |
3138 | -up in the output of this command. |
3139 | - |
3140 | -InnoDB Transaction Log |
3141 | -********************** |
3142 | - |
3143 | -The slave plugin uses the InnoDB transaction log (see |
3144 | -:ref:`innodb_transaction_log`) on the master to retrieve replication |
3145 | -messages. This transaction log, though stored as an internal table within |
3146 | -InnoDB, offers two different views to the table contents. Two tables in |
3147 | -the DATA_DICTIONARY schema provide the different views into the transaction |
3148 | -log: the SYS_REPLICATION_LOG table and the INNODB_REPLICATION_LOG table. |
3149 | - |
3150 | -The SYS_REPLICATION_LOG table is read directly by the slave plugin. |
3151 | -This table is described as below:: |
3152 | - |
3153 | - drizzle> SHOW CREATE TABLE data_dictionary.sys_replication_log\G |
3154 | - *************************** 1. row *************************** |
3155 | - Table: SYS_REPLICATION_LOG |
3156 | - Create Table: CREATE TABLE `SYS_REPLICATION_LOG` ( |
3157 | - `ID` BIGINT, |
3158 | - `SEGID` INT, |
3159 | - `COMMIT_ID` BIGINT, |
3160 | - `END_TIMESTAMP` BIGINT, |
3161 | - `MESSAGE_LEN` INT, |
3162 | - `MESSAGE` BLOB, |
3163 | - PRIMARY KEY (`ID`,`SEGID`) USING BTREE, |
3164 | - KEY `COMMIT_IDX` (`COMMIT_ID`,`ID`) USING BTREE |
3165 | - ) ENGINE=InnoDB COLLATE = binary |
3166 | - |
3167 | -The INNODB_REPLICATION_LOG is similar to the SYS_REPLICATION_LOG, the |
3168 | -main difference being that the Google Protobuffer message representing |
3169 | -the changed rows is converted to plain text before being output:: |
3170 | - |
3171 | - drizzle> SHOW CREATE TABLE data_dictionary.innodb_replication_log\G |
3172 | - *************************** 1. row *************************** |
3173 | - Table: INNODB_REPLICATION_LOG |
3174 | - Create Table: CREATE TABLE `INNODB_REPLICATION_LOG` ( |
3175 | - `TRANSACTION_ID` BIGINT NOT NULL, |
3176 | - `TRANSACTION_SEGMENT_ID` BIGINT NOT NULL, |
3177 | - `COMMIT_ID` BIGINT NOT NULL, |
3178 | - `END_TIMESTAMP` BIGINT NOT NULL, |
3179 | - `TRANSACTION_MESSAGE_STRING` TEXT COLLATE utf8_general_ci NOT NULL, |
3180 | - `TRANSACTION_LENGTH` BIGINT NOT NULL |
3181 | - ) ENGINE=FunctionEngine COLLATE = utf8_general_ci REPLICATE = FALSE |
3182 | - |
3183 | -The INNODB_REPLICATION_LOG table is read-only due to the way it is |
3184 | -implemented. The SYS_REPLICATION_LOG table, on the other hand, allows you |
3185 | -to modify the contents of the transaction log. You would use this table |
3186 | -to trim the transaction log. |
3187 | - |
3188 | -Monitoring the Slave |
3189 | -#################### |
3190 | - |
3191 | -The slave plugin has two types of threads doing all of the work: |
3192 | - |
3193 | -* An IO (or producer) thread |
3194 | -* An applier (or consumer) thread |
3195 | - |
3196 | -The status of each thread is stored in tables in the *sys_replication* |
3197 | -schema. The IO thread status is contained in the *io_state* table, and |
3198 | -the applier thread status is in the *applier_state* table. You may query |
3199 | -these tables just like any other table. For example:: |
3200 | - |
3201 | - drizzle> SELECT * FROM sys_replication.io_state\G |
3202 | - *************************** 1. row *************************** |
3203 | - status: RUNNING |
3204 | - error_msg: |
3205 | - |
3206 | -The above shows that the IO thread is **RUNNING**. If there had been |
3207 | -an error on the IO thread, the status value would be **STOPPED** and |
3208 | -the error_msg column would contain information about the error. |
3209 | - |
3210 | -We can check the state of the applier thread in a similar manner:: |
3211 | - |
3212 | - drizzle> SELECT * FROM sys_replication.applier_state\G |
3213 | - *************************** 1. row *************************** |
3214 | - last_applied_commit_id: 4 |
3215 | - status: RUNNING |
3216 | - error_msg: |
3217 | - |
3218 | -The status and error_msg columns are similar to the ones in the *io_state* |
3219 | -table. Also available is the last_applied_commit_id, which contains the |
3220 | -value of the COMMIT_ID from the master's replication log (see definition |
3221 | -of the data_dictionary.sys_replication_log table above) of the most |
3222 | -recently executed transaction. |
3223 | - |
3224 | -Transaction Log Maintenance |
3225 | -########################### |
3226 | - |
3227 | -Currently, the InnoDB transaction log grows without bounds and is never |
3228 | -trimmed of unneeded entries. This can present a problem for long running |
3229 | -replication setups. You may trim the log manually, but you must make certain |
3230 | -to not remove any entries that are needed by slave servers. |
3231 | - |
3232 | -Follow these steps to trim the InnoDB transaction without affecting slave |
3233 | -function: |
3234 | - |
3235 | -#. Query each slave for the *last_applied_commit_id* value from the *sys_replication.applier_state* table. |
3236 | -#. Choose the **minimum** value obtained from step one. This will be the marker for the slave that is the furthest behind the master. |
3237 | -#. Using this marker value from the previous step, delete all entries from the master's transaction log that has a COMMIT_ID less than the marker value. |
3238 | - |
3239 | -Below is an example of the steps defined above. First, step 1 and 2. Assume |
3240 | -that we have two slave hosts connected to the master (slave-1 and slave-2). |
3241 | -We need to query both to check their relationship with the master transaction |
3242 | -log:: |
3243 | - |
3244 | - slave-1> SELECT last_applied_commit_id FROM sys_replication.applier_state\G |
3245 | - *************************** 1. row *************************** |
3246 | - last_applied_commit_id: 3000 |
3247 | - |
3248 | - slave-2> SELECT last_applied_commit_id FROM sys_replication.applier_state\G |
3249 | - *************************** 1. row *************************** |
3250 | - last_applied_commit_id: 2877 |
3251 | - |
3252 | -We see that slave-2 has the smallest value for *last_applied_commit_id*. We |
3253 | -will use this value in the next step to trim the transaction log on the |
3254 | -master:: |
3255 | - |
3256 | - master> DELETE FROM data_dictionary.sys_replication_log WHERE commit_id < 2877; |
3257 | - |
3258 | -This will remove all old, unneeded entries from the InnoDB transaction log. Note that the SYS_REPLICATION_LOG table is used for this maintenance task. |
3259 | |
3260 | === modified file 'plugin/slave/docs/index.rst' |
3261 | --- plugin/slave/docs/index.rst 2012-03-08 00:54:48 +0000 |
3262 | +++ plugin/slave/docs/index.rst 2012-03-18 00:36:19 +0000 |
3263 | @@ -1,165 +1,4 @@ |
3264 | -.. _slave_plugin: |
3265 | - |
3266 | Replication Slave |
3267 | ================== |
3268 | |
3269 | -This page contains the configuration and implementation details for Drizzle replication. |
3270 | - |
3271 | -See these pages for user-level information: |
3272 | - |
3273 | -.. toctree:: |
3274 | - :maxdepth: 2 |
3275 | - |
3276 | - user_example |
3277 | - admin |
3278 | - |
3279 | -Description |
3280 | ------------ |
3281 | - |
3282 | -Replication enables data from one Drizzle database server (the master) to be replicated to one or more Drizzle database servers (the slaves). It provides a native implementation of replication between two Drizzle processes. Depending on your configuration, you can replicate all databases, selected databases, or selected tables within a database. |
3283 | - |
3284 | -Drizzle’s replication system is entirely new and different from MySQL. Replication events are stored using Google Protocol Buffer messages in an InnoDB table. These events are read by the slave, stored locally, and applied. The advantage of the Google Protocol Buffer messages is a script or program can be put together in pretty much any language in minutes, and read the replication log. In other words, replication plugins are easy to implement, which enable developers to entirely customize their replication system. |
3285 | - |
3286 | -This plugin requires a master that is running with the InnoDB replication log enabled. The slave plugin allows a server to replicate from another server that is using the innodb-trx log. It is a very simple setup: |
3287 | |
3288 | -master options: –innodb.replication-log=true |
3289 | slave options: –plugin-add=slave –slave.config-file=XYZ |
3290 | - |
3291 | -The config file may contain the following options in option=value format: |
3292 | |
3293 | -master-host – hostname/ip of the master host |
3294 | master-port – port used by the master server |
3295 | master-user – username |
3296 | master-pass – password |
3297 | max-reconnects – max # of reconnect attempts if the master disappears |
3298 | seconds-between-reconnects – how long to wait between reconnect attempts |
3299 | - |
3300 | - |
3301 | -Configuration |
3302 | -------------- |
3303 | - |
3304 | -Most of the options that can be used to control the replication slave plugin |
3305 | -can only be given in a configuration file. The only exceptions are the |
3306 | -:option:`drizzled --slave.config-file` and :option:`drizzled --slave.max-commit-id` options. |
3307 | - |
3308 | -.. program:: drizzled |
3309 | - |
3310 | -.. option:: --slave.config-file FILE |
3311 | - |
3312 | - :Default: :file:`etc/slave.cfg` |
3313 | - :Variable: |
3314 | - |
3315 | - Path to the replication slave configuration file. By default, the |
3316 | - plugin will look for a file named :file:`slave.cfg` in the `etc` directory |
3317 | - of the Drizzle installation. If you want to specify a different path or |
3318 | - configuration file name, it is best to specify a full path to the |
3319 | - file. The relative path used by plugins is within the :option:`--datadir` |
3320 | - directory, so a full path is recommended. |
3321 | - |
3322 | -.. option:: --slave.max-commit-id ID |
3323 | - |
3324 | - Manually set the maximum commit ID the slave is assumed to have retrieved |
3325 | - from the master. This value will be used by the slave to determine where |
3326 | - to begin retrieving replication messages from the master transaction log. |
3327 | - This option can be used to provision a new slave machine by setting it to |
3328 | - the value output from the drizzledump client when used with the |
3329 | - --single-transaction option. |
3330 | - |
3331 | - This value is not allowed to be set via the configuration file since |
3332 | - you would normally only set it once on initial slave startup. This |
3333 | - eliminates the possibility of forgetting to delete it from the configuration |
3334 | - file for subsequent slave restarts. |
3335 | - |
3336 | -The options below are read from the configuration file. |
3337 | - |
3338 | -.. confval:: master-host |
3339 | - |
3340 | - Hostname/IP address of the master server. |
3341 | - |
3342 | -.. confval:: master-port |
3343 | - |
3344 | - Drizzle port used by the master server. Default is 3306. |
3345 | - |
3346 | -.. confval:: master-user |
3347 | - |
3348 | - Username to use for connecting to the master server. |
3349 | - |
3350 | -.. confval:: master-pass |
3351 | - |
3352 | - Password associated with the username given by :confval:`master-user`. |
3353 | - |
3354 | -.. confval:: max-reconnects |
3355 | - |
3356 | - The number of reconnection attempts the slave plugin will try if the |
3357 | - master server becomes unreachable. Default is 10. |
3358 | - |
3359 | -.. confval:: seconds-between-reconnects |
3360 | - |
3361 | - The number of seconds to wait between reconnect attempts when the master |
3362 | - server becomes unreachable. Default is 30. |
3363 | - |
3364 | -.. confval:: io-thread-sleep |
3365 | - |
3366 | - The number of seconds the IO (producer) thread sleeps between queries to the |
3367 | - master for more replication events. Default is 5. |
3368 | - |
3369 | -.. confval:: applier-thread-sleep |
3370 | - |
3371 | - The number of seconds the applier (consumer) thread sleeps between applying |
3372 | - replication events from the local queue. Default is 5. |
3373 | - |
3374 | -Implementation Details |
3375 | ----------------------- |
3376 | - |
3377 | -The replication slave plugin creates two worker threads, each accessing a |
3378 | -work queue (implemented as an InnoDB table) that contains the replication |
3379 | -events. This is a producer/consumer paradigm where one thread populates the |
3380 | -queue (the producer), and the other thread (the consumer) reads events from |
3381 | -the queue. |
3382 | - |
3383 | -The producer thread (or I/O thread) is in charge of connecting to the master |
3384 | -server and pulling down replication events from the master's transaction |
3385 | -log and storing them locally in the slave queue. It is required that the |
3386 | -master use the InnoDB replication log (:option:`--innodb.replication-log <drizzled --innodb.replication-log>`). |
3387 | - |
3388 | -The consumer thread (or applier thread) reads the replication events from |
3389 | -the local slave queue, applies them locally, and then deletes successfully |
3390 | -applied events from the queue. |
3391 | - |
3392 | -Schemas and Tables |
3393 | ------------------- |
3394 | - |
3395 | -The slave plugin creates its own schema and set of tables to store its |
3396 | -metadata. It stores everything in the **sys_replication** schema. The |
3397 | -following are the tables that it will create: |
3398 | - |
3399 | -.. dbtable:: sys_replication.io_state |
3400 | - |
3401 | - Stores metadata about the IO/producer thread. |
3402 | - |
3403 | -.. dbtable:: sys_replication.applier_state |
3404 | - |
3405 | - Stores metadata about the applier/consumer thread. |
3406 | - |
3407 | -.. dbtable:: sys_replication.queue |
3408 | - |
3409 | - The replication event queue. |
3410 | - |
3411 | -.. _slave_authors: |
3412 | - |
3413 | -Authors |
3414 | -------- |
3415 | - |
3416 | -David Shrewsbury |
3417 | - |
3418 | -.. _slave_version: |
3419 | - |
3420 | -Version |
3421 | -------- |
3422 | - |
3423 | -This documentation applies to **slave 1.0**. |
3424 | - |
3425 | -To see which version of the plugin a Drizzle server is running, execute: |
3426 | - |
3427 | -.. code-block:: mysql |
3428 | - |
3429 | - SELECT MODULE_VERSION FROM DATA_DICTIONARY.MODULES WHERE MODULE_NAME='slave' |
3430 | - |
3431 | -Changelog |
3432 | ---------- |
3433 | - |
3434 | -v1.0 |
3435 | -^^^^ |
3436 | -* First release. |
3437 | +See :ref:`slave_applier`. |
3438 | |
3439 | === removed file 'plugin/slave/docs/user_example.rst' |
3440 | --- plugin/slave/docs/user_example.rst 2011-07-22 23:56:42 +0000 |
3441 | +++ plugin/slave/docs/user_example.rst 1970-01-01 00:00:00 +0000 |
3442 | @@ -1,134 +0,0 @@ |
3443 | -How to use replication: An example |
3444 | -==================================== |
3445 | - |
3446 | -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. |
3447 | - |
3448 | -Replication setup begins with making certain that both master and slave share the same version of Drizzle to avoid any potential incompatibility issues. |
3449 | - |
3450 | -Master Setup |
3451 | -------------- |
3452 | - |
3453 | -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: |
3454 | - |
3455 | - master> usr/local/sbin/drizzled \ |
3456 | - --innodb.replication-log \ |
3457 | - --pid-file=/var/run/drizzled/drizzled.pid \ |
3458 | - --drizzle-protocol.bind-address=0.0.0.0 \ |
3459 | - --mysql-protocol.bind-address=0.0.0.0 \ |
3460 | - --daemon |
3461 | - |
3462 | - |
3463 | -Several options are required on most setups. They are set on Drizzle Startup with a --optionname. The most important ones are: |
3464 | - |
3465 | - |
3466 | -The InnoDB replication log must be running: |
3467 | - |
3468 | ---innodb.replication-log |
3469 | - |
3470 | - |
3471 | -PID must be set: |
3472 | - |
3473 | ---pid-file=/var/run/drizzled/drizzled.pid |
3474 | - |
3475 | - |
3476 | -the address binding for Drizzle's default port (4427): |
3477 | - |
3478 | ---drizzle-protocol.bind-address=0.0.0.0 |
3479 | - |
3480 | - |
3481 | -The address binding for systems replicating through MySQL's default port (3306): |
3482 | - |
3483 | ---mysql-protocol.bind-address=0.0.0.0 |
3484 | - |
3485 | - |
3486 | -Data Directory can be set other than default: |
3487 | - |
3488 | ---datadir=$PWD/var |
3489 | - |
3490 | - |
3491 | -For more complex setups, the server id option may be appropriate to use: |
3492 | - |
3493 | ---server-id |
3494 | - |
3495 | - |
3496 | -To run Drizzle in the background, thereby keeping the database running if the user logs out: |
3497 | - |
3498 | ---daemon |
3499 | - |
3500 | - |
3501 | - |
3502 | -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. |
3503 | - |
3504 | -Slave Setup |
3505 | -------------- |
3506 | - |
3507 | -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: :: |
3508 | - |
3509 | - slave> /usr/local/sbin/drizzled \ |
3510 | - --plugin-add=slave \ |
3511 | - --slave.config-file=/usr/local/etc//slave.cfg |
3512 | - |
3513 | -A more typical startup will need more options: |
3514 | - |
3515 | - slave> /usr/local/sbin/drizzled \ |
3516 | - --plugin-add=slave \ |
3517 | - --slave.config-file=/usr/local/etc//slave.cfg \ |
3518 | - --pid-file=/var/run/drizzled/drizzled.pid \ |
3519 | - --drizzle-protocol.bind-address=0.0.0.0 \ |
3520 | - --mysql-protocol.bind-address=0.0.0.0 \ |
3521 | - --daemon |
3522 | - |
3523 | -Similar to the Master setup, there are a number of options that can be selected. Please see the Plugin Documentation for the relevent options. |
3524 | - |
3525 | -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: :: |
3526 | - |
3527 | - master-host = master.location.com |
3528 | - master-port = 4427 |
3529 | - |
3530 | -Some options that can be set other than default, but are otherwise not necessary, are: |
3531 | - |
3532 | - master-user = dino_slave |
3533 | - master-pass = my_password |
3534 | - io-thread-sleep = 10 |
3535 | - applier-thread-sleep = 10 |
3536 | - |
3537 | -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. |
3538 | - |
3539 | -Provisioning a New Slave Host |
3540 | -------------------------------- |
3541 | - |
3542 | -The basic formula for creating a new slave host for an existing replication setup is: |
3543 | - |
3544 | - 1. Make a backup of the master databases. |
3545 | - 2. Record the state of the master transaction log at the point the backup was made. |
3546 | - 3. Restore the backup on the new slave machine. |
3547 | - 4. Start the new slave and tell it to begin reading the transaction log from the point recorded in #2. |
3548 | - |
3549 | -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: :: |
3550 | - |
3551 | - master> drizzledump --all-databases --single-transaction > master.backup |
3552 | - master> head -1 master.backup |
3553 | - -- SYS_REPLICATION_LOG: COMMIT_ID = 33426, ID = 35074 |
3554 | - |
3555 | -The SYS_REPLICATION_LOG line provides the replication log metadata needed when starting a new slave. It has two pieces of information: |
3556 | - |
3557 | -* **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. |
3558 | -* **ID**: This is the unique transaction identifier associated with the most recently executed transaction stored in the transaction log. |
3559 | - |
3560 | -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: :: |
3561 | - |
3562 | - slave> sbin/drizzled --datadir=$PWD/var & |
3563 | - slave> drizzle < master.backup |
3564 | - slave> drizzle --shutdown |
3565 | - |
3566 | -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: |
3567 | - |
3568 | - slave> sbin/drizzled --datadir=$PWD/var \ |
3569 | - --plugin-add=slave \ |
3570 | - --slave.config-file=/user/local/etc/slave.cfg \ |
3571 | - --slave.max-commit-id=33426 & |
3572 | - |
3573 | - |
3574 | -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. |
3575 | - |
3576 | -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. |
3577 | |
3578 | === modified file 'plugin/slave/module.cc' |
3579 | --- plugin/slave/module.cc 2012-01-15 20:54:59 +0000 |
3580 | +++ plugin/slave/module.cc 2012-03-18 00:36:19 +0000 |
3581 | @@ -62,7 +62,7 @@ |
3582 | { |
3583 | DRIZZLE_VERSION_ID, |
3584 | "slave", |
3585 | - "1.0", |
3586 | + "1.1", |
3587 | "David Shrewsbury", |
3588 | N_("Drizzle replication slave"), |
3589 | PLUGIN_LICENSE_GPL, |
3590 | |
3591 | === modified file 'plugin/zeromq/docs/index.rst' |
3592 | --- plugin/zeromq/docs/index.rst 2011-10-23 05:45:09 +0000 |
3593 | +++ plugin/zeromq/docs/index.rst 2012-03-18 00:36:19 +0000 |
3594 | @@ -3,51 +3,4 @@ |
3595 | ZeroMQ |
3596 | ====== |
3597 | |
3598 | -ZeroMQ is a messaging library that allows you to easily build complex |
3599 | -communication systems. The ZeroMQ plugin allows drizzle to publish |
3600 | -transactions to a local PUB socket. Many clients can subscribe to |
3601 | -these transactions. The first frame of the message sent out is the |
3602 | -schema name the transaction touched - this enables clients to only |
3603 | -subscribe to the interesting schemas (note that certain "transactions" |
3604 | -are without a schema, like SET xyz for example, for these, the first |
3605 | -frame is empty). |
3606 | - |
3607 | -Getting started |
3608 | ---------------- |
3609 | - |
3610 | -First, install zeromq, get the code from `zeromq.org |
3611 | -<http://zeromq.org>`_, then you can build drizzle, watch the |
3612 | -./configure output to verify that drizzle finds the libraries needed. |
3613 | - |
3614 | -Now you are good to go, simply start drizzle with --plugin-add=zeromq |
3615 | -and drizzle will start publishing transactions. The only configuration |
3616 | -parameter available is: |
3617 | - |
3618 | -.. code-block:: bash |
3619 | - |
3620 | - --zeromq.endpoint arg (=tcp://*:9999) - the endpoint to expose. |
3621 | - |
3622 | -Now you can write a simple python script to verify that it works, |
3623 | -something like this will work: |
3624 | - |
3625 | -.. code-block:: python |
3626 | - |
3627 | - import zmq |
3628 | - |
3629 | - ctx = zmq.Context() |
3630 | - s = ctx.socket(zmq.SUB) |
3631 | - s.setsockopt(zmq.SUBSCRIBE, '') |
3632 | - s.connect('tcp://localhost:9999') |
3633 | - i = 0 |
3634 | - while True: |
3635 | - i = i+1 |
3636 | - s.recv_multipart() |
3637 | - print i |
3638 | - |
3639 | -and then you can generate some load: |
3640 | - |
3641 | -.. code-block:: bash |
3642 | - |
3643 | - bin/drizzleslap -c 10 -a --auto-generate-sql-add-autoincrement --burnin |
3644 | - |
3645 | -which creates 10 threads and generates random queries. |
3646 | +See :ref:`zeromq_applier`. |
Please elaborate the content..
Thanks,
Sekhar