← Back to branch summary

~drizzle-trunk/drizzle/development

« back to all changes in this revision

Viewing changes to docs/replication.rst

  • Committer: Lee Bieber
  • Date: 2011-02-28 19:31:51 UTC
  • mfrom: (2207.1.2 build)
  • Revision ID: kalebral@gmail.com-20110228193151-hrp1jymg33pvp3dr
Merge Shrews - update replication documentation
Merge Monty - Fix the plugin doc distcheck issue

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/replication.rst
 
1
*******************
1
2
Drizzle Replication
2
 
===================
 
3
*******************
3
4
 
4
5
Replication events are recorded using messages in the `Google Protocol Buffer
5
6
<http://code.google.com/p/protobuf/>`_ (GPB) format. GPB messages can contain
7
8
is passed to plugins that subscribe to the replication stream.
8
9
 
9
10
Configuration Options
10
 
---------------------
 
11
#####################
11
12
 
12
13
**transaction_message_threshold**
13
14
 
32
33
    on a slave to perform replication as this will lead to incorrect results.
33
34
 
34
35
Message Definitions
35
 
-------------------
 
36
###################
36
37
 
37
38
The GPB messages are defined in .proto files in the drizzled/message
38
39
directory of the Drizzle source code. The primary definition file is
97
98
  ------------------------------------------------------------------
98
99
 
99
100
The Transaction Message
100
 
^^^^^^^^^^^^^^^^^^^^^^^
 
101
#######################
101
102
 
102
103
The main "envelope" message which represents an atomic transaction
103
104
which changed the state of a server is the Transaction message class.
106
107
 
107
108
#. A TransactionContext message containing information about the
108
109
   transaction as a whole, such as the ID of the executing server,
109
 
   the start and end timestamp of the transaction, and a globally-
110
 
   unique identifier for the transaction.
 
110
   the start and end timestamp of the transaction, segmenting
 
111
   metadata and a unique identifier for the transaction.
111
112
#. A vector of Statement messages representing the distinct SQL
112
113
   statements which modified the state of the server.  The Statement
113
114
   message is, itself, a generic envelope message containing a
114
115
   sub-message which describes the specific data modification which
115
 
   occurred on the server (such as, for instance, an INSERT statement.
 
116
   occurred on the server (such as, for instance, an INSERT statement).
116
117
 
117
118
The Statement Message
118
 
^^^^^^^^^^^^^^^^^^^^^
 
119
#####################
119
120
 
120
121
The generic "envelope" message containing information common to each
121
122
SQL statement executed against a server (such as a start and end timestamp
126
127
of the Statement should construct the inner Statement subclass representing
127
128
a data change.
128
129
 
129
 
Statements are recorded seperatley as sometimes individual statements
 
130
Statements are recorded separately as sometimes individual statements
130
131
have to be rolled back.
131
132
 
132
133
 
133
134
.. _bulk-operations:
134
135
 
135
136
How Bulk Operations Work
136
 
------------------------
 
137
########################
137
138
 
138
139
Certain operations which change large volumes of data on a server
139
140
present a specific set of problems for a transaction coordinator or
153
154
replication system uses a mechanism which provides bulk change
154
155
operations.
155
156
 
 
157
A single transaction in the database can possibly be represented with
 
158
multiple protobuf Transaction messages if the message grows too large.
 
159
This can happen if you have a bulk transaction, or a single statement
 
160
affecting a very large number of rows, or just a large transaction with
 
161
many statements/changes.
 
162
 
 
163
For the first two examples, it is likely that the Statement sub-message
 
164
itself will get segmented, causing another Transaction message to be
 
165
created to hold the rest of the Statement's row changes. In these cases,
 
166
it is enough to look at the segment information stored in the Statement
 
167
message (see example below).
 
168
 
 
169
For the last example, the Statement sub-messages may or may not be
 
170
segmented, but we could still need to split the individual Statements up into
 
171
multiple Transaction messages to keep the Transaction message size from
 
172
growing too large. In this case, the segment information in the Statement
 
173
submessages is not helpful if the Statement isn't segmented. We need this
 
174
information in the Transaction message itself.
 
175
 
 
176
Segmenting a Single SQL Statement
 
177
*********************************
 
178
 
156
179
When a regular SQL statement modifies or inserts more rows than a
157
180
certain threshold, Drizzle's replication services component will begin
158
181
sending Transaction messages to replicas which contain a chunk
200
223
#. Construct an UpdateHeader message with information about the tables
201
224
   and fields involved in the UPDATE statement.  Push this UpdateHeader
202
225
   message onto the Transaction message's statement vector.
203
 
#. Construct an UpdateData message.  Set the segment_id member to 1.
204
 
   Set the end_segment member to true.
 
226
#. Construct an UpdateData message.  Set the *segment_id* member to 1.
 
227
   Set the *end_segment* member to true.
205
228
#. For every record updated in a storage engine, the ReplicationServices
206
229
   component builds a new UpdateRecord message and appends this message
207
230
   to the aforementioned UpdateData message's record vector.
208
231
#. After a certain threshold of records is reached, the
209
232
   ReplicationServices component sets the current UpdateData message's
210
 
   end_segment member to false, and proceeds to send the Transaction
 
233
   *end_segment* member to false, and proceeds to send the Transaction
211
234
   message to replicators.
212
235
#. The ReplicationServices component then constructs a new Transaction
213
236
   message and constructs a transaction context with the same
214
237
   transaction ID and server information.
215
 
#. A new UpdateData message is created.  The message's segment_id is
 
238
#. A new UpdateData message is created.  The message's *segment_id* is
216
239
   set to N+1 and as new records are updated, new UpdateRecord messages
217
240
   are appended to the UpdateData message's record vector.
218
241
#. While records are being updated, we repeat steps 5 through 7, with
219
 
   only the final UpdateData message having its end_segment member set
 
242
   only the final UpdateData message having its *end_segment* member set
220
243
   to true.
221
244
 
 
245
Segmenting a Transaction
 
246
************************
 
247
 
 
248
The Transaction protobuf message also contains *segment_id* member and a
 
249
*end_segment* member. These values are also set appropriately when a
 
250
Statement sub-message is segmented, as described above.
 
251
 
 
252
These values are also set when a Transaction must be segmented along
 
253
individual Statement boundaries (i.e., the Statement message itself
 
254
is **not** segmented). In either case, it is enough to check the
 
255
*end_segment* and *segment_id* values of the Transaction message
 
256
to determine if this is a multi-message transaction.
 
257
 
222
258
Handling ROLLBACKs
223
 
------------------
 
259
##################
224
260
 
225
261
Both transactions and individual statements may be rolled back.
226
262
 
235
271
* For a transaction which is made up of multiple messages, and at least
236
272
  one message has already been sent through the replication stream, then
237
273
  the Transaction message will contain a Statement message with type =
238
 
  ROLLBACK.
 
274
  ROLLBACK. This signifies to rollback the entire transaction.
 
275
 
 
276
A special Statement message type, ROLLBACK_STATEMENT, is used when
 
277
we have a segmented Statement message (see above) and we need to tell the
 
278
receiver to undo any changes made for this single statement, but not
 
279
for the entire transaction. If the receiver cannot handle rolling back
 
280
a single statement, then a message buffering strategy should be employed 
 
281
to guarantee that a statement was indeed applied successfully before
 
282
executing on the receiver.