← Back to branch summary

~ubuntu-branches/ubuntu/trusty/drizzle/trusty

« back to all changes in this revision

Viewing changes to docs/protocol.rst

  • Committer: Bazaar Package Importer
  • Author(s): Monty Taylor
  • Date: 2010-10-02 14:17:48 UTC
  • mfrom: (1.1.1 upstream)
  • mto: (2.1.17 sid)
  • mto: This revision was merged to the branch mainline in revision 3.
  • Revision ID: james.westby@ubuntu.com-20101002141748-m6vbfbfjhrw1153e
Tags: 2010.09.1802-1
* New upstream release.
* Removed pid-file argument hack.
* Updated GPL-2 address to be new address.
* Directly copy in drizzledump.1 since debian doesn't have sphinx 1.0 yet.
* Link to jquery from libjs-jquery. Add it as a depend.
* Add drizzled.8 symlink to the install files.

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs/protocol.rst
 
1
#
 
2
# Drizzle Client & Protocol Library
 
3
# 
 
4
# Copyright (C) 2008 Eric Day (eday@oddments.org)
 
5
# All rights reserved.
 
6
# 
 
7
# Use and distribution licensed under the BSD license.  See
 
8
# the COPYING file in this directory for full text.
 
9
#
 
10
 
 
11
Drizzle Protocol
 
12
================
 
13
 
 
14
`This is currently a proposed draft as of November 29, 2008`
 
15
 
 
16
The Drizzle protocol works over TCP, UDP, and Unix Domain Sockets
 
17
(UDS, also known as IPC sockets), although there are limitations when
 
18
using UDP (this is discussed below). In the case of TCP and UDS,
 
19
a connection is made, a command is sent, and a response loop is
 
20
started. Socket communication ends when either side closes the
 
21
connection or a QUIT command is issued.
 
22
 
 
23
TCP and UDS communications will be full duplex. This means that as
 
24
the client is sending a command, it is possible for the server to
 
25
report an error before the sending of data completes. This allows
 
26
the server to do preliminary checks (table exists, authentication,
 
27
...) before a request is completely sent so the client may abort. This
 
28
will primarily be used for large requests (INSERTing large BLOBs).
 
29
 
 
30
TCP and UDS communications will also allow for pipe-lining of requests
 
31
and concurrent command execution. This means a client does not need
 
32
to wait for a command to finish before a new command is sent. It is
 
33
even possible a later command issued will complete and have a result
 
34
before an earlier command. Result packets may be interleaved so a
 
35
client issuing concurrent commands must be able to parse results
 
36
concurrently.
 
37
 
 
38
UDP sockets are supported to allow small, fast updates for
 
39
applications such as statistical gathering. Since UDP does not
 
40
guarantee delivery, this method should not be used for applications
 
41
that require reliable transport. When using UDP, the authentication
 
42
packet (if needed) and command packet are bundled into a single UDP
 
43
packet and sent. This puts a limitation on the size of the request
 
44
being made, and this limit can be different between network hosts. The
 
45
absolute limit is 65,507 bytes (28 bytes used for IPv4 and UDP
 
46
headers), but again, this can depend on the network hosts. Responses
 
47
are optional when issuing UDP commands, and this preference is
 
48
specified in the handshake packet.
 
49
 
 
50
All sizes given throughout this document are in bytes. Byte order
 
51
for all multi-byte binary objects such as lengths and mutli-byte
 
52
bit-fields are packed little-endian.
 
53
 
 
54
 
 
55
Packet Sequence Overview
 
56
------------------------
 
57
 
 
58
The sequence of packets for a simple connection and command that
 
59
responds with an OK packet:
 
60
 
 
61
C: Command
 
62
S: OK
 
63
 
 
64
The sequence of packets for a simple connection and query command
 
65
with results:
 
66
 
 
67
C: Command
 
68
S: OK
 
69
S: Fields (optional, multiple packets)
 
70
S: Rows (multiple packets)
 
71
S: EOF
 
72
 
 
73
When authentication is required for a command, the server will ask
 
74
for it. For example:
 
75
 
 
76
C: Command
 
77
S: Authentication Required
 
78
C: Authentication Credentials
 
79
S: OK    
 
80
S: Fields
 
81
S: Rows
 
82
S: EOF
 
83
 
 
84
The server will use the most recent credential information when
 
85
processing subsequent commands.
 
86
 
 
87
If a client wishes to multiplex commands on a single connection,
 
88
it can do so using the command identifiers. Here is an example of
 
89
how the packets could be ordered, but this will largely depend on
 
90
the servers ability to process the commands concurrently and the
 
91
processing time for each command.
 
92
 
 
93
C: Command (Command ID=1)
 
94
C: Command (Command ID=2)
 
95
S: OK (Command ID=2)
 
96
S: Field (Command ID=2)
 
97
S: OK (Command ID=1)
 
98
S: Fields (Command ID=2)
 
99
S: Rows (Command ID=2)
 
100
S: EOF
 
101
 
 
102
As you can see, the commands may be executed with results generated
 
103
in any order, and the packet containing the results may be interleaved.
 
104
 
 
105
 
 
106
Length Encoding
 
107
---------------
 
108
 
 
109
Some lengths used within the protocol packets are length encoded. This
 
110
means the size of the length field will vary between 1 and 9 bytes,
 
111
and is determined by the value of the first byte.
 
112
 
 
113
0-252 - Actual length
 
114
253   - NULL value (only applicable in row results)
 
115
254   - Following 8 bytes contain actual length
 
116
255   - Depends on context, usually signifies end
 
117
 
 
118
 
 
119
Packets
 
120
-------
 
121
 
 
122
Packets consist of two layers. The first is meant to be small,
 
123
simple, and have just enough information for fast router and proxy
 
124
processing. It consists of a fixed-size part, along with a variable
 
125
sized client id (explained later), a series of chunked data, followed
 
126
by a checksum at the end. The chunked transfer encoding allows for
 
127
not having to pre-compute the packet data length before sending,
 
128
and support packets of any size. It also allows for a large packet
 
129
to be aborted gracefully (without having to close the connection)
 
130
in the event of an error.
 
131
 
 
132
   +-------------------------------------------------------------------------+
 
133
   +                                  32 Bits                                +
 
134
   +-------------------------------------------------------------------------+
 
135
    
 
136
   +-----+----------------+----------------+---------------------------------+
 
137
   |   0 | Magic          | Protocol       | Command ID                      |
 
138
   +-----+----------------+----------------+---------------------------------+
 
139
 
 
140
   +-----+---------------------------------+---------------------------------+
 
141
   |  32 | Command / Result Code           | Client ID Length                |
 
142
   +-----+---------------------------------+---------------------------------+
 
143
 
 
144
   +-----+---------------------------------+---------------------------------+
 
145
   |  64 | Client ID (optional, variable length)                             |
 
146
   +-----+---------------------------------+---------------------------------+
 
147
 
 
148
   +-----+---------------------------------+---------------------------------+
 
149
   | 64+ | Chunk Length and Value Pairs (optional, variable length)          |
 
150
   +-----+---------------------------------+---------------------------------+
 
151
 
 
152
   +-----+---------------------------------+---------------------------------+
 
153
   + 64+ | Chunk Length = 0                |                                 |
 
154
   +-----+---------------------------------+---------------------------------+
 
155
 
 
156
   +-----+---------------------------------+---------------------------------+
 
157
   | 80+ | Checksum                                                          |
 
158
   +-----+---------------------------------+---------------------------------+
 
159
 
 
160
The first part of a packet is:
 
161
 
 
162
1-byte Magic number, the value should be 0x44.
 
163
 
 
164
1-byte Protocol version, currently 1.
 
165
 
 
166
2-byte Command ID. This is a unique number among all other queries
 
167
       currently being executed on the connection. The client is
 
168
       responsible for choosing a unique number while generating a
 
169
       command packet, and all response packets associated with that
 
170
       command must have the same command ID. Once a command has been
 
171
       completed, the client may reuse the ID.
 
172
 
 
173
2-byte Command/result code. For commands, this may be:
 
174
 
 
175
       1  ECHO
 
176
         The entire packet is simply echoed back to the caller.
 
177
       2  SET
 
178
         Set protocol options.
 
179
       3  QUERY
 
180
         Execute query.
 
181
       4  QUERY_RO
 
182
         Same as QUERY, but hints that this is a read-only
 
183
         query. This is only useful for routers/proxies who may want
 
184
         to redirect the request to a read slave.
 
185
 
 
186
       Result codes may be:
 
187
 
 
188
       1  OK
 
189
         Single packet success response. No data associated
 
190
         with the result besides parameters.
 
191
       2  ERROR
 
192
         Single packet error response.
 
193
       3  DATA
 
194
         Start of a multi-packet result set.
 
195
       3  DATA_END
 
196
         Mark the end of a series of data packets. This is
 
197
         useful so a low level router or proxy can know when a
 
198
         response is complete without inspecting the contents of
 
199
         the packets.
 
200
 
 
201
2-byte Client ID length.
 
202
X-byte Client ID (length is value of client ID length).
 
203
The client ID is there for the client and routers/proxies to use. The server
 
204
treats this as opaque data, and will only preserve it to send
 
205
in responses. This can be used as a sharding key, to keep
 
206
state information in a proxy, or any other use.
 
207
 
 
208
Next, zero or more chunks are given, terminated by a chunk length of
 
209
0. Each chunk consist of a length and then that amount of data.
 
210
 
 
211
2-byte Chunk length
 
212
X-byte Chunk (length is value of chunk length)
 
213
 
 
214
After the the chunk length of 0 is given, a checksum value is given
 
215
that was computed for the entire packet.
 
216
 
 
217
4-byte Checksum
 
218
 
 
219
The second layer of the protocol is encapsulated inside of the
 
220
chunked encoding. This consists of zero or more packet parameters,
 
221
an end of parameter marker, followed by an optional data set that is
 
222
given until the end of a packet (or the end of all chunks).
 
223
 
 
224
 
 
225
Packet Parameters
 
226
-----------------
 
227
 
 
228
Packet parameter names are defined in a global namespace, although
 
229
not all parameters are relevant for all packet types. Parameters are
 
230
enumerated, and the name is specified with a 1-byte value representing
 
231
the enumerated name. Each packet parameter may have a value associated
 
232
with it, and each parameter defines the size and how that value is
 
233
given. The list of possible packet parameters are:
 
234
 
 
235
0   END_OF_PARAMETERS - Marks the end of a parameter list.
 
236
 
 
237
Parameters used for setting options:
 
238
 
 
239
1   AUTH              - 1-byte value with authentication mechanism
 
240
                        to use. Possible values are:
 
241
                        0 - None.
 
242
                        1 - MD5 on user and password.
 
243
                        2 - 3-way handshake.
 
244
2   CHECKSUM          - 1-byte value with preferred checksum
 
245
                        type. Possible values are:
 
246
                        0 - None.
 
247
                        1 - CRC32
 
248
3   COMPRESSION       - 1-byte value with preferred compression
 
249
                        type. Possible values are:
 
250
                        0 - None.
 
251
                        1 - zlib.
 
252
                        2 - bzip2.
 
253
4   FIELD_ENCODING    - 1-byte value with preferred field encoding
 
254
                        type. Possible values are:
 
255
                        0 - String.
 
256
                        1 - Native.
 
257
5   FIELD_INFO        - 1-byte value to determine if field information
 
258
                        should be sent. Possible values are:
 
259
                        0 - None.
 
260
                        1 - Send field info.
 
261
 
 
262
(6-63 Reserved for future options that can be set)
 
263
 
 
264
Parameters used in responses:
 
265
 
 
266
64  STATUS            - 4-byte bit field.
 
267
65  NUM_ROWS_AFFECTED - Length-encoded count of rows affected.
 
268
66  NUM_ROWS_SCANNED  - Length-encoded count of rows scanned.
 
269
67  NUM_WARNINGS      - Length-encoded count of warnings encountered.
 
270
68  INSERT_ID         - Last insert ID.
 
271
69  ERROR_CODE        - 4-byte error code.
 
272
70  ERROR_STRING      - Length-encoded string.
 
273
71  SQL_STATE         - Length-encoded string.
 
274
72  NUM_FIELDS        - 4-byte integer.
 
275
73  FIELD_START       - No value, starts a new set of field parameters.
 
276
74  FIELD_TYPE        - 2-byte enumerated type.
 
277
75  FIELD_LENGTH      - Length-encoded value.
 
278
76  FIELD_FLAGS       - 4-byte bit-field.
 
279
77  DB_NAME           - Length-encoded string.
 
280
78  TABLE_NAME        - Length-encoded string.
 
281
79  ORIG_TABLE_NAME   - Length-encoded string.
 
282
80  FIELD_NAME        - Length-encoded string.
 
283
81  ORIG_FIELD_NAME   - Length-encoded string.
 
284
82  DEFAULT_VALUE     - Length-encoded string.
 
285
 
 
286
(83-255 Reserved for future responses parameters)
 
287
 
 
288
"Length-encoded string" means a length-encoded value, followed by a
 
289
string of that length.
 
290
 
 
291
 
 
292
Command
 
293
-------
 
294
 
 
295
Inside of the chunked data, command packets consist of zero or more
 
296
parameters depending on which options are being set, followed by
 
297
a end of parameter marker, and then all data until the end of the
 
298
chunks are considered arguments for the command. For a QUERY, this
 
299
will be the actual query to run.
 
300
 
 
301
 
 
302
OK/ERROR
 
303
--------
 
304
 
 
305
The server responds with an OK or ERROR if no row data is given. A
 
306
list of parameters may follow, and the marked with an end of parameter
 
307
value.
 
308
 
 
309
 
 
310
DATA
 
311
----
 
312
 
 
313
A data packet consists of a series of parameters, followed by the end
 
314
of parameter, and then a series of length-encoded values holding field
 
315
values. The NUM_FIELDS parameter must be given before any values, as
 
316
this indicates when a start of a new row happens. The field values may
 
317
either be in string format or native data type, depending on the value
 
318
of FIELD_ENCODING.
 
319
 
 
320
There may be multiple rows inside of a single DATA result packet. In
 
321
the case of large result sets, the result should be split into multiple
 
322
DATA packets since other concurrent commands on the connection will
 
323
block if a single large packet is sent. By breaking resulting rows
 
324
into multiple DATA packets, other commands are then allowed to send
 
325
interleaved response packets.