]>
Commit | Line | Data |
---|---|---|
f85f8ebb BP |
1 | =================================================== |
2 | Open vSwitch Configuration Database Specification | |
3 | =================================================== | |
4 | ||
5 | Basic Notation | |
6 | -------------- | |
7 | ||
65e18fa8 BP |
8 | OVSDB uses JSON, as defined by RFC 4627, for its schema format and its |
9 | wire protocol format. The JSON implementation in Open vSwitch has the | |
10 | following limitations: | |
11 | ||
12 | - Null bytes (\u0000) are not allowed in strings. | |
13 | ||
14 | - Only UTF-8 encoding is supported. (RFC 4627 also mentions | |
15 | UTF-16BE, UTF-16LE, and UTF-32.) | |
16 | ||
17 | - RFC 4627 says that names within a JSON object should be unique. | |
18 | The Open vSwitch JSON parser discards all but the last value | |
19 | for a name that is specified more than once. | |
20 | ||
f85f8ebb BP |
21 | The descriptions below use the following shorthand notations for JSON |
22 | values. Additional notation is presented later. | |
23 | ||
24 | <string> | |
25 | ||
12996ef9 | 26 | A JSON string. Any Unicode string is allowed, as specified by RFC |
bd76d25d | 27 | 4627. Implementations may disallow null bytes. |
f85f8ebb BP |
28 | |
29 | <id> | |
30 | ||
31 | A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*. | |
32 | ||
33 | <id>s that begin with _ are reserved to the implementation and may | |
34 | not be used by the user. | |
35 | ||
8159b984 BP |
36 | <version> |
37 | ||
38 | A JSON string that contains a version number that matches | |
39 | [0-9]+\.[0-9]+\.[0-9]+ | |
40 | ||
f85f8ebb BP |
41 | <boolean> |
42 | ||
43 | A JSON true or false value. | |
44 | ||
45 | <number> | |
46 | ||
47 | A JSON number. | |
48 | ||
49 | <integer> | |
50 | ||
51 | A JSON number with an integer value, within a certain range | |
52 | (currently -2**63...+2**63-1). | |
53 | ||
a817e524 | 54 | <json-value> |
6e79e210 BP |
55 | |
56 | Any JSON value. | |
57 | ||
394ca249 BP |
58 | <nonnull-json-value> |
59 | ||
60 | Any JSON value except null. | |
61 | ||
bd76d25d BP |
62 | <error> |
63 | ||
64 | A JSON object with the following members: | |
65 | ||
66 | "error": <string> required | |
67 | "details": <string> optional | |
68 | ||
69 | The value of the "error" member is a short string, specified in | |
70 | this document, that broadly indicates the class of the error. | |
71 | Most "error" strings are specific to contexts described elsewhere | |
72 | in this document, but the following "error" strings may appear in | |
73 | any context where an <error> is permitted: | |
74 | ||
75 | "error": "resources exhausted" | |
76 | ||
77 | The operation requires more resources (memory, disk, CPU, | |
78 | etc.) than are currently available to the database server. | |
79 | ||
80 | "error": "I/O error" | |
81 | ||
82 | Problems accessing the disk, network, or other required | |
83 | resources prevented the operation from completing. | |
84 | ||
85 | Database implementations may use "error" strings not specified | |
86 | in this document to indicate errors that do not fit into any of | |
87 | the specified categories. | |
88 | ||
89 | Optionally, an <error> may include a "details" member, whose value | |
90 | is a string that describes the error in more detail for the | |
91 | benefit of a human user or administrator. This document does not | |
92 | specify the format or content of the "details" string. | |
93 | ||
94 | An <error> may also have other members that describe the error in | |
95 | more detail. This document does not specify the names or values | |
96 | of these members. | |
97 | ||
f85f8ebb BP |
98 | Schema Format |
99 | ------------- | |
100 | ||
101 | An Open vSwitch configuration database consists of a set of tables, | |
102 | each of which has a number of columns and zero or more rows. A schema | |
103 | is represented by <database-schema>, as described below. | |
104 | ||
105 | <database-schema> | |
106 | ||
107 | A JSON object with the following members: | |
108 | ||
109 | "name": <id> required | |
8159b984 | 110 | "version": <version> required |
6aa09313 | 111 | "cksum": <string> optional |
f85f8ebb BP |
112 | "tables": {<id>: <table-schema>, ...} required |
113 | ||
9cb53f26 BP |
114 | The "name" identifies the database as a whole. It must be |
115 | provided to most JSON-RPC requests to identify the database being | |
2e57b537 BP |
116 | operated on. The value of "tables" is a JSON object whose names |
117 | are table names and whose values are <table-schema>s. | |
f85f8ebb | 118 | |
8159b984 BP |
119 | The "version" reports the version of the database schema. Because |
120 | this is a recent addition to the schema format, OVSDB permits it | |
121 | to be omitted, but future versions of OVSDB will require it to be | |
122 | present. Open vSwitch semantics for "version" are described in | |
123 | ovs-vswitchd.conf.db(5). | |
124 | ||
6aa09313 BP |
125 | The "cksum" optionally reports an implementation-defined checksum |
126 | for the database schema. | |
127 | ||
f85f8ebb BP |
128 | <table-schema> |
129 | ||
130 | A JSON object with the following members: | |
131 | ||
f85f8ebb | 132 | "columns": {<id>: <column-schema>, ...} required |
87ab878c | 133 | "maxRows": <integer> optional |
c5f341ab | 134 | "isRoot": <boolean> optional |
6910a6e6 | 135 | "indexes": [<column-set>*] optional |
f85f8ebb | 136 | |
2e57b537 BP |
137 | The value of "columns" is a JSON object whose names are column |
138 | names and whose values are <column-schema>s. | |
f85f8ebb BP |
139 | |
140 | Every table has the following columns whose definitions are not | |
141 | included in the schema: | |
142 | ||
143 | "_uuid": This column, which contains exactly one UUID value, | |
144 | is initialized to a random value by the database engine when | |
145 | it creates a row. It is read-only, and its value never | |
146 | changes during the lifetime of a row. | |
147 | ||
148 | "_version": Like "_uuid", this column contains exactly one | |
149 | UUID value, initialized to a random value by the database | |
150 | engine when it creates a row, and it is read-only. However, | |
151 | its value changes to a new random value whenever any other | |
152 | field in the row changes. Furthermore, its value is | |
153 | ephemeral: when the database is closed and reopened, or when | |
154 | the database process is stopped and then started again, each | |
155 | "_version" also changes to a new random value. | |
156 | ||
c5f341ab BP |
157 | If "isRoot" is omitted or specified as false, then any given row |
158 | in the table may exist only when there is at least one reference | |
159 | to it, with refType "strong", from a different row (in the same | |
160 | table or a different table). This is a "deferred" action: | |
161 | unreferenced rows in the table are deleted just before transaction | |
162 | commit. If "isRoot" is specified as true, then rows in the table | |
163 | exist independent of any references (they can be thought of as | |
164 | part of the "root set" in a garbage collector). | |
165 | ||
166 | For compatibility with schemas created before "isRoot" was | |
167 | introduced, if "isRoot" is omitted or false in every | |
168 | <table-schema> in a given <database-schema>, then every table is | |
169 | part of the root set. | |
170 | ||
87ab878c BP |
171 | If "maxRows" is specified, as a positive integer, it limits the |
172 | maximum number of rows that may be present in the table. This is | |
173 | a "deferred" constraint, enforced only at transaction commit time | |
174 | (see the "transact" request below). If "maxRows" is not | |
175 | specified, the size of the table is limited only by the resources | |
c5f341ab BP |
176 | available to the database server. "maxRows" constraints are |
177 | enforced after unreferenced rows are deleted from tables with a | |
178 | false "isRoot". | |
87ab878c | 179 | |
6910a6e6 BP |
180 | If "indexes" is specified, it must be an array of zero or more |
181 | <column-set>s. A <column-set> is an array of one or more strings, | |
182 | each of which names a column. Each <column-set> is a set of | |
183 | columns whose values, taken together within any given row, must be | |
184 | unique within the table. This is a "deferred" constraint, | |
185 | enforced only at transaction commit time, after unreferenced rows | |
186 | are deleted and dangling weak references are removed. Ephemeral | |
187 | columns may not be part of indexes. | |
188 | ||
f85f8ebb BP |
189 | <column-schema> |
190 | ||
191 | A JSON object with the following members: | |
192 | ||
f85f8ebb BP |
193 | "type": <type> required |
194 | "ephemeral": <boolean> optional | |
c424adb3 | 195 | "mutable": <boolean> optional |
f85f8ebb | 196 | |
42a49b96 BP |
197 | The "type" specifies the type of data stored in this column. |
198 | ||
199 | If "ephemeral" is specified as true, then this column's values are | |
2e57b537 | 200 | not guaranteed to be durable; they may be lost when the database |
42a49b96 BP |
201 | restarts. A column whose type (either key or value) is a strong |
202 | reference to a table that is not part of the root set is always | |
203 | durable, regardless of this value. (Otherwise, restarting the | |
204 | database could lose entire rows.) | |
205 | ||
206 | If "mutable" is specified as false, then this column's values may | |
207 | not be modified after they are initially set with the "insert" | |
208 | operation. | |
f85f8ebb BP |
209 | |
210 | <type> | |
211 | ||
212 | The type of a database column. Either an <atomic-type> or a JSON | |
213 | object that describes the type of a database column, with the | |
214 | following members: | |
215 | ||
bd76d25d BP |
216 | "key": <base-type> required |
217 | "value": <base-type> optional | |
f85f8ebb BP |
218 | "min": <integer> optional |
219 | "max": <integer> or "unlimited" optional | |
220 | ||
221 | If "min" or "max" is not specified, each defaults to 1. If "max" | |
222 | is specified as "unlimited", then there is no specified maximum | |
223 | number of elements, although the implementation will enforce some | |
31a763d7 BP |
224 | limit. After considering defaults, "min" must be exactly 0 or |
225 | exactly 1, "max" must be at least 1, and "max" must be greater | |
226 | than or equal to "min". | |
f85f8ebb BP |
227 | |
228 | If "min" and "max" are both 1 and "value" is not specified, the | |
229 | type is the scalar type specified by "key". | |
230 | ||
231 | If "min" is not 1 or "max" is not 1, or both, and "value" is not | |
232 | specified, the type is a set of scalar type "key". | |
233 | ||
234 | If "value" is specified, the type is a map from type "key" to type | |
235 | "value". | |
236 | ||
bd76d25d BP |
237 | <base-type> |
238 | ||
239 | The type of a key or value in a database column. Either an | |
240 | <atomic-type> or a JSON object with the following members: | |
241 | ||
242 | "type": <atomic-type> required | |
bfc96d9b | 243 | "enum": <value> optional |
bd76d25d BP |
244 | "minInteger": <integer> optional, integers only |
245 | "maxInteger": <integer> optional, integers only | |
246 | "minReal": <real> optional, reals only | |
c5c7c7c5 | 247 | "maxReal": <real> optional, reals only |
bd76d25d BP |
248 | "minLength": <integer> optional, strings only |
249 | "maxLength": <integer> optional, strings only | |
250 | "refTable": <id> optional, uuids only | |
7360012b | 251 | "refType": "strong" or "weak" optional, only with "refTable" |
bd76d25d BP |
252 | |
253 | An <atomic-type> by itself is equivalent to a JSON object with a | |
254 | single member "type" whose value is the <atomic-type>. | |
255 | ||
bfc96d9b BP |
256 | "enum" may be specified as a <value> whose type is a set of one |
257 | or more values specified for the member "type". If "enum" is | |
258 | specified, then the valid values of the <base-type> are limited to | |
259 | those in the <value>. | |
260 | ||
261 | "enum" is mutually exclusive with the following constraints. | |
262 | ||
bd76d25d BP |
263 | If "type" is "integer", then "minInteger" or "maxInteger" or both |
264 | may also be specified, restricting the valid integer range. If | |
265 | both are specified, then the maxInteger must be greater than or | |
266 | equal to minInteger. | |
267 | ||
268 | If "type" is "real", then "minReal" or "maxReal" or both may also | |
269 | be specified, restricting the valid real range. If both are | |
270 | specified, then the maxReal must be greater than or equal to | |
271 | minReal. | |
272 | ||
89521e3f BP |
273 | If "type" is "string", then "minLength" and "maxLength" or both |
274 | may be specified, restricting the valid length of value strings. | |
275 | If both are specified, then maxLength must be greater than or | |
276 | equal to minLength. String length is measured in characters (not | |
277 | bytes or UTF-16 code units). | |
bd76d25d | 278 | |
0d0f05b9 | 279 | If "type" is "uuid", then "refTable", if present, must be the name |
7360012b BP |
280 | of a table within this database. If "refTable" is specified, then |
281 | "refType" may also be specified. If "refTable" is set, the effect | |
282 | depends on "refType": | |
283 | ||
284 | - If "refType" is "strong" or if "refType" is omitted, the | |
285 | allowed UUIDs are limited to UUIDs for rows in the named | |
286 | table. | |
287 | ||
288 | - If "refType" is "weak", then any UUIDs are allowed, but | |
289 | UUIDs that do not correspond to rows in the named table will | |
290 | be automatically deleted. | |
0d0f05b9 BP |
291 | |
292 | "refTable" constraints are "deferred" constraints: they are | |
293 | enforced only at transaction commit time (see the "transact" | |
294 | request below). The other contraints on <base-type> are | |
295 | "immediate", enforced immediately by each operation. | |
bd76d25d | 296 | |
f85f8ebb BP |
297 | <atomic-type> |
298 | ||
299 | One of the strings "integer", "real", "boolean", "string", or | |
300 | "uuid", representing the specified scalar type. | |
301 | ||
302 | Wire Protocol | |
303 | ------------- | |
304 | ||
12996ef9 BP |
305 | The database wire protocol is implemented in JSON-RPC 1.0. We |
306 | encourage use of JSON-RPC over stream connections instead of JSON-RPC | |
307 | over HTTP, for these reasons: | |
308 | ||
309 | * JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server | |
310 | protocol, which is a poor match. Thus, JSON-RPC over HTTP | |
311 | requires the client to periodically poll the server to receive | |
312 | server requests. | |
313 | ||
314 | * HTTP is more complicated than stream connections and doesn't | |
315 | provide any corresponding advantage. | |
316 | ||
317 | * The JSON-RPC specification for HTTP transport is incomplete. | |
318 | ||
0d11f523 BP |
319 | We are using TCP port 6632 for the database JSON-RPC connection. |
320 | ||
12996ef9 | 321 | The database wire protocol consists of the following JSON-RPC methods: |
f85f8ebb | 322 | |
9cb53f26 BP |
323 | list_dbs |
324 | ........ | |
325 | ||
326 | Request object members: | |
327 | ||
328 | "method": "list_dbs" required | |
329 | "params": [] required | |
394ca249 | 330 | "id": <nonnull-json-value> required |
9cb53f26 BP |
331 | |
332 | Response object members: | |
333 | ||
334 | "result": [<db-name>, ...] | |
335 | "error": null | |
336 | "id": same "id" as request | |
337 | ||
338 | This operation retrieves an array whose elements are <db-name>s | |
339 | that name the databases that can be accessed over this JSON-RPC | |
340 | connection. | |
341 | ||
f85f8ebb BP |
342 | get_schema |
343 | .......... | |
344 | ||
345 | Request object members: | |
346 | ||
347 | "method": "get_schema" required | |
9cb53f26 | 348 | "params": [<db-name>] required |
394ca249 | 349 | "id": <nonnull-json-value> required |
f85f8ebb BP |
350 | |
351 | Response object members: | |
352 | ||
353 | "result": <database-schema> | |
354 | "error": null | |
355 | "id": same "id" as request | |
356 | ||
9cb53f26 BP |
357 | This operation retrieves a <database-schema> that describes hosted |
358 | database <db-name>. | |
f85f8ebb BP |
359 | |
360 | transact | |
361 | ........ | |
362 | ||
363 | Request object members: | |
364 | ||
9cb53f26 BP |
365 | "method": "transact" required |
366 | "params": [<db-name>, <operation>*] required | |
394ca249 | 367 | "id": <nonnull-json-value> required |
f85f8ebb BP |
368 | |
369 | Response object members: | |
370 | ||
371 | "result": [<object>*] | |
372 | "error": null | |
373 | "id": same "id" as request | |
374 | ||
9cb53f26 BP |
375 | The "params" array for this method consists of a <db-name> that |
376 | identifies the database to which the transaction applies, followed by | |
377 | zero or more JSON objects, each of which represents a single database | |
378 | operation. The "Operations" section below describes the valid | |
379 | operations. | |
f85f8ebb BP |
380 | |
381 | The value of "id" must be unique among all in-flight transactions | |
382 | within the current JSON-RPC session. Otherwise, the server may return | |
383 | a JSON-RPC error. | |
384 | ||
385 | The database server executes each of the specified operations in the | |
386 | specified order, except that if an operation fails, then the remaining | |
387 | operations are not executed. | |
388 | ||
389 | The set of operations is executed as a single atomic, consistent, | |
390 | isolated transaction. The transaction is committed only if every | |
391 | operation succeeds. Durability of the commit is not guaranteed unless | |
392 | the "commit" operation, with "durable" set to true, is included in the | |
393 | operation set (see below). | |
394 | ||
395 | Regardless of whether errors occur, the response is always a JSON-RPC | |
396 | response with null "error" and a "result" member that is an array with | |
397 | the same number of elements as "params". Each element of the "result" | |
398 | array corresponds to the same element of the "params" array. The | |
399 | "result" array elements may be interpreted as follows: | |
400 | ||
401 | - A JSON object that does not contain an "error" member indicates | |
402 | that the operation completed successfully. The specific members | |
403 | of the object are specified below in the descriptions of | |
404 | individual operations. Some operations do not produce any | |
405 | results, in which case the object will have no members. | |
406 | ||
bd76d25d BP |
407 | - An <error>, which indicates that the operation completed with an |
408 | error. | |
f85f8ebb BP |
409 | |
410 | - A JSON null value indicates that the operation was not attempted | |
411 | because a prior operation failed. | |
412 | ||
413 | In general, "result" contains some number of successful results, | |
414 | possibly followed by an error, in turn followed by enough JSON null | |
415 | values to match the number of elements in "params". There is one | |
416 | exception: if all of the operations succeed, but the results cannot be | |
0d0f05b9 BP |
417 | committed, then "result" will have one more element than "params", |
418 | with the additional element an <error>. The possible "error" strings | |
419 | include at least the following: | |
420 | ||
421 | "error": "referential integrity violation" | |
422 | ||
423 | When the commit was attempted, a column's value referenced the | |
424 | UUID for a row that did not exist in the table named by the | |
7360012b BP |
425 | column's <base-type> key or value "refTable" that has a |
426 | "refType" of "strong". (This can be caused by inserting a row | |
427 | that references a nonexistent row, by deleting a row that is | |
428 | still referenced by another row, by specifying the UUID for a | |
429 | row in the wrong table, and other ways.) | |
430 | ||
431 | "error": "constraint violation" | |
432 | ||
433 | A column with a <base-type> key or value "refTable" whose | |
434 | "refType" is "weak" became empty due to deletion(s) caused | |
435 | because the rows that it referenced were deleted (or never | |
436 | existed, if the column's row was inserted within the | |
437 | transaction), and this column is not allowed to be empty | |
438 | because its <type> has a "min" of 1. | |
f85f8ebb | 439 | |
87ab878c BP |
440 | "error": "constraint violation" |
441 | ||
442 | The number of rows in a table exceeds the maximum number | |
443 | permitted by the table's "maxRows" value (see <table-schema>). | |
444 | ||
d901ddf4 BP |
445 | "error": "constraint violation" |
446 | ||
447 | Two or more rows in a table had the same values in the columns | |
448 | that comprise an index. | |
449 | ||
450 | "error": "resources exhausted" | |
451 | "error": "I/O error" | |
452 | ||
453 | As described in the definition of <error> above. | |
454 | ||
f85f8ebb BP |
455 | If "params" contains one or more "wait" operations, then the |
456 | transaction may take an arbitrary amount of time to complete. The | |
457 | database implementation must be capable of accepting, executing, and | |
458 | replying to other transactions and other JSON-RPC requests while a | |
459 | transaction or transactions containing "wait" operations are | |
460 | outstanding on the same or different JSON-RPC sessions. | |
461 | ||
462 | The section "Notation for the Wire Protocol" below describes | |
463 | additional notation for use with the wire protocol. After that, the | |
464 | "Operations" section describes each operation. | |
465 | ||
466 | cancel | |
467 | ...... | |
468 | ||
469 | Request object members: | |
470 | ||
471 | "method": "cancel" required | |
6e79e210 | 472 | "params": [the "id" for an outstanding request] required |
f85f8ebb BP |
473 | "id": null required |
474 | ||
475 | Response object members: | |
476 | ||
477 | <no response> | |
478 | ||
479 | This JSON-RPC notification instructs the database server to | |
480 | immediately complete or cancel the "transact" request whose "id" is | |
c5c7c7c5 | 481 | the same as the notification's "params" value. |
f85f8ebb BP |
482 | |
483 | If the "transact" request can be completed immediately, then the | |
484 | server sends a response in the form described for "transact", above. | |
485 | Otherwise, the server sends a JSON-RPC error response of the following | |
486 | form: | |
487 | ||
488 | "result": null | |
489 | "error": "canceled" | |
490 | "id": the request "id" member | |
491 | ||
492 | The "cancel" notification itself has no reply. | |
493 | ||
a8425c53 BP |
494 | monitor |
495 | ....... | |
496 | ||
497 | Request object members: | |
498 | ||
a817e524 BP |
499 | "method": "monitor" required |
500 | "params": [<db-name>, <json-value>, <monitor-requests>] required | |
394ca249 | 501 | "id": <nonnull-json-value> required |
a8425c53 | 502 | |
20aa445d BP |
503 | <monitor-requests> is an object that maps from a table name to an |
504 | array of <monitor-request> objects. For backward compatibility, a | |
505 | single <monitor-request> may be used instead of an array; it is | |
506 | treated as a single-element array. | |
a8425c53 BP |
507 | |
508 | Each <monitor-request> is an object with the following members: | |
509 | ||
510 | "columns": [<column>*] optional | |
511 | "select": <monitor-select> optional | |
512 | ||
513 | <monitor-select> is an object with the following members: | |
514 | ||
515 | "initial": <boolean> optional | |
516 | "insert": <boolean> optional | |
517 | "delete": <boolean> optional | |
518 | "modify": <boolean> optional | |
519 | ||
520 | Response object members: | |
521 | ||
522 | "result": <table-updates> | |
523 | "error": null | |
524 | "id": same "id" as request | |
525 | ||
526 | This JSON-RPC request enables a client to replicate tables or subsets | |
20aa445d BP |
527 | of tables within database <db-name>. Each element of |
528 | <monitor-requests> specifies a table to be replicated. The JSON-RPC | |
529 | response to the "monitor" includes the initial contents of each table, | |
530 | unless disabled (see below). Afterward, when changes to those tables | |
531 | are committed, the changes are automatically sent to the client using | |
532 | the "update" monitor notification. This monitoring persists until the | |
533 | JSON-RPC session terminates or until the client sends a | |
534 | "monitor_cancel" JSON-RPC request. | |
a8425c53 | 535 | |
20aa445d | 536 | Each <monitor-request> describes how to monitor columns in a table: |
a8425c53 BP |
537 | |
538 | The circumstances in which an "update" notification is sent for a | |
539 | row within the table are determined by <monitor-select>: | |
540 | ||
541 | If "initial" is omitted or true, every row in the table is | |
542 | sent as part of the reply to the "monitor" request. | |
543 | ||
544 | If "insert" is omitted or true, "update" notifications are | |
545 | sent for rows newly inserted into the table. | |
546 | ||
547 | If "delete" is omitted or true, "update" notifications are | |
548 | sent for rows deleted from the table. | |
549 | ||
550 | If "modify" is omitted or true, "update" notifications are | |
551 | sent whenever when a row in the table is modified. | |
552 | ||
553 | The "columns" member specifies the columns whose values are | |
20aa445d BP |
554 | monitored. It must not contain duplicates. If "columns" is |
555 | omitted, all columns in the table, except for "_uuid", are | |
556 | monitored. | |
557 | ||
558 | If there is more than one <monitor-request> in an array of them, then | |
559 | each <monitor-request> in the array should specify both "columns" and | |
560 | "select", and the "columns" must be non-overlapping sets. | |
a8425c53 BP |
561 | |
562 | The "result" in the JSON-RPC response to the "monitor" request is a | |
563 | <table-updates> object (see below) that contains the contents of the | |
564 | tables for which "initial" rows are selected. If no tables' initial | |
565 | contents are requested, then "result" is an empty object. | |
566 | ||
567 | update | |
568 | ...... | |
569 | ||
570 | Notification object members: | |
571 | ||
572 | "method": "update" | |
a817e524 | 573 | "params": [<json-value>, <table-updates>] |
a8425c53 BP |
574 | "id": null |
575 | ||
a817e524 BP |
576 | The <json-value> in "params" is the same as the value passed as the |
577 | <json-value> in "params" for the "monitor" request. | |
a8425c53 BP |
578 | |
579 | <table-updates> is an object that maps from a table name to a | |
580 | <table-update>. | |
581 | ||
582 | A <table-update> is an object that maps from the row's UUID (as a | |
583 | 36-byte string) to a <row-update> object. | |
584 | ||
585 | A <row-update> is an object with the following members: | |
586 | ||
587 | "old": <row> present for "delete" and "modify" updates | |
588 | "new": <row> present for "initial", "insert", and "modify" updates | |
589 | ||
590 | This JSON-RPC notification is sent from the server to the client to | |
591 | tell it about changes to a monitored table (or the initial state of a | |
592 | modified table). Each table in which one or more rows has changed (or | |
593 | whose initial view is being presented) is represented in "updates". | |
594 | Each row that has changed (or whose initial view is being presented) | |
595 | is represented in its <table-update> as a member with its name taken | |
596 | from the row's _uuid member. The corresponding value is a | |
597 | <row-update>: | |
598 | ||
599 | The "old" member is present for "delete" and "modify" updates. | |
600 | For "delete" updates, each monitored column is included. For | |
601 | "modify" updates, the prior value of each monitored column whose | |
602 | value has changed is included (monitored columns that have not | |
603 | changed are represented in "new"). | |
604 | ||
605 | The "new" member is present for "initial", "insert", and "modify" | |
606 | updates. For "initial" and "insert" updates, each monitored | |
607 | column is included. For "modify" updates, the new value of each | |
608 | monitored column is included. | |
609 | ||
610 | monitor_cancel | |
611 | .............. | |
612 | ||
613 | Request object members: | |
614 | ||
615 | "method": "monitor_cancel" required | |
a817e524 | 616 | "params": [<json-value>] required |
394ca249 | 617 | "id": <nonnull-json-value> required |
a8425c53 BP |
618 | |
619 | Response object members: | |
620 | ||
621 | "result": {} | |
622 | "error": null | |
623 | "id": the request "id" member | |
624 | ||
a817e524 BP |
625 | Cancels the ongoing table monitor request, identified by the |
626 | <json-value> in "params" matching the <json-value> in "params" for an | |
627 | ongoing "monitor" request. No more "update" messages will be sent for | |
628 | this table monitor. | |
a8425c53 | 629 | |
da897f41 BP |
630 | lock operations |
631 | ............... | |
632 | ||
633 | Request object members: | |
634 | ||
635 | "method": "lock", "steal", or "unlock" required | |
636 | "params": [<id>] required | |
637 | "id": <nonnull-json-value> required | |
638 | ||
639 | Response object members: | |
640 | ||
641 | "result": {"locked": <boolean>} for "lock" | |
642 | "result": {"locked": true} for "steal" | |
643 | "result": {} for "unlock" | |
644 | "error": null | |
645 | "id": same "id" as request | |
646 | ||
647 | Performs an operation on a "lock" object. The database server | |
648 | supports an arbitrary number of locks, each of which is identified by | |
649 | a client-defined id (given in "params"). At any given time, each lock | |
650 | may have at most one owner. | |
651 | ||
652 | The locking operation depends on "method": | |
653 | ||
654 | - "lock": The database will assign this client ownership of the | |
655 | lock as soon as it becomes available. When multiple clients | |
656 | request the same lock, they will receive it in first-come, first | |
657 | served order. | |
658 | ||
659 | - "steal": The database immediately assigns this client ownership | |
660 | of the lock. If there is an existing owner, it loses ownership. | |
661 | ||
662 | - "unlock": If the client owns the lock, releases it. If the | |
663 | client is waiting to obtain the lock, cancels the request and | |
664 | stops waiting. | |
665 | ||
666 | (Closing or otherwise disconnecting a database client connection | |
667 | unlocks all of its locks.) | |
668 | ||
669 | For any given lock, the client must alternate "lock" or "steal" | |
670 | operations with "unlock" operations. That is, if the previous | |
671 | operation on a lock was "lock" or "steal", it must be followed by an | |
672 | "unlock" operation, and vice versa. | |
673 | ||
674 | For a "lock" operation, the "locked" member in the response object is | |
675 | true if the lock has already been acquired, false if another client | |
676 | holds the lock and the client's request for it was queued. In the | |
677 | latter case, the client will be notified later with a "locked" message | |
678 | when acquisition succeeds. | |
679 | ||
680 | These requests complete and send a response quickly, without waiting. | |
681 | The "locked" and "stolen" notifications (see below) report | |
682 | asynchronous changes to ownership. | |
683 | ||
684 | The scope of a lock is a database server, not a database hosted by | |
454ec971 | 685 | that server. A naming convention, such as "<db-name>__<lock-name>", |
da897f41 BP |
686 | can effectively limit the scope of a lock to a particular database. |
687 | ||
688 | locked | |
689 | ...... | |
690 | ||
691 | Notification object members: | |
692 | ||
693 | "method": "locked" | |
694 | "params": [<id>] | |
695 | "id": null | |
696 | ||
697 | Notifies the client that a "lock" operation that it previously | |
698 | requested has succeeded. The client now owns the lock named in | |
699 | "params". | |
700 | ||
701 | The database server sends this notification after the reply to the | |
702 | corresponding "lock" request (but only if the "locked" member of the | |
703 | response was false), and before the reply to the client's subsequent | |
704 | "unlock" request. | |
705 | ||
706 | stolen | |
707 | ...... | |
708 | ||
709 | Notification object members: | |
710 | ||
6b2ccff3 | 711 | "method": "stolen" |
da897f41 BP |
712 | "params": [<id>] |
713 | "id": null | |
714 | ||
715 | Notifies the client that owns a lock that another database client has | |
716 | stolen ownership of the lock. The client no longer owns the lock | |
717 | named in "params". The client must still issue an "unlock" request | |
718 | before performing any subsequent "lock" or "steal" operation on the | |
719 | lock. | |
720 | ||
721 | If the client originally obtained the lock through a "lock" request, | |
722 | then it will automatically regain the lock later after the client that | |
723 | stole it releases it. (The database server will send the client a | |
724 | "locked" notification at that point to let it know.) | |
725 | ||
726 | If the client originally obtained the lock through a "steal" request, | |
727 | the database server won't automatically reassign it ownership of the | |
728 | lock when it later becomes available. To regain ownership, the client | |
729 | must "unlock" and then "lock" or "steal" the lock again. | |
730 | ||
6c2882f9 BP |
731 | echo |
732 | .... | |
733 | ||
734 | Request object members: | |
735 | ||
736 | "method": "echo" required | |
6e79e210 | 737 | "params": JSON array with any contents required |
a817e524 | 738 | "id": <json-value> required |
6c2882f9 BP |
739 | |
740 | Response object members: | |
741 | ||
742 | "result": same as "params" | |
743 | "error": null | |
744 | "id": the request "id" member | |
745 | ||
746 | Both the JSON-RPC client and the server must implement this request. | |
747 | ||
748 | This JSON-RPC request and response can be used to implement connection | |
749 | keepalives, by allowing the server to check that the client is still | |
750 | there or vice versa. | |
751 | ||
752 | ||
f85f8ebb BP |
753 | Notation for the Wire Protocol |
754 | ------------------------------ | |
755 | ||
9cb53f26 BP |
756 | <db-name> |
757 | ||
758 | An <id> that names a database. The valid <db-name>s can be | |
759 | obtained using a "list-db" request. The <db-name> is taken from | |
760 | the "name" member of <database-schema>. | |
761 | ||
f85f8ebb BP |
762 | <table> |
763 | ||
764 | An <id> that names a table. | |
765 | ||
766 | <column> | |
767 | ||
768 | An <id> that names a table column. | |
769 | ||
770 | <row> | |
771 | ||
772 | A JSON object that describes a table row or a subset of a table | |
773 | row. Each member is the name of a table column paired with the | |
774 | <value> of that column. | |
775 | ||
776 | <value> | |
777 | ||
778 | A JSON value that represents the value of a column in a table row, | |
779 | one of <atom>, a <set>, or a <map>. | |
780 | ||
781 | <atom> | |
782 | ||
783 | A JSON value that represents a scalar value for a column, one of | |
784 | <string>, <number>, <boolean>, <uuid>, <named-uuid>. | |
785 | ||
786 | <set> | |
787 | ||
ae8f13e2 BP |
788 | Either an <atom>, representing a set with exactly one element, or |
789 | a 2-element JSON array that represents a database set value. The | |
f85f8ebb BP |
790 | first element of the array must be the string "set" and the second |
791 | element must be an array of zero or more <atom>s giving the values | |
792 | in the set. All of the <atom>s must have the same type. | |
793 | ||
794 | <map> | |
795 | ||
796 | A 2-element JSON array that represents a database map value. The | |
797 | first element of the array must be the string "map" and the second | |
798 | element must be an array of zero or more <pair>s giving the values | |
799 | in the map. All of the <pair>s must have the same key and value | |
800 | types. | |
801 | ||
802 | (JSON objects are not used to represent <map> because JSON only | |
803 | allows string names in an object.) | |
804 | ||
805 | <pair> | |
806 | ||
807 | A 2-element JSON array that represents a pair within a database | |
808 | map. The first element is an <atom> that represents the key, the | |
809 | second element is an <atom> that represents the value. | |
810 | ||
811 | <uuid> | |
812 | ||
813 | A 2-element JSON array that represents a UUID. The first element | |
814 | of the array must be the string "uuid" and the second element must | |
815 | be a 36-character string giving the UUID in the format described | |
816 | by RFC 4122. For example, the following <uuid> represents the | |
817 | UUID 550e8400-e29b-41d4-a716-446655440000: | |
818 | ||
819 | ["uuid", "550e8400-e29b-41d4-a716-446655440000"] | |
820 | ||
821 | <named-uuid> | |
822 | ||
823 | A 2-element JSON array that represents the UUID of a row inserted | |
fbf925e4 BP |
824 | in an "insert" operation within the same transaction. The first |
825 | element of the array must be the string "named-uuid" and the | |
d198c4be | 826 | second element should be the <id> specified as the "uuid-name" |
fbf925e4 BP |
827 | for an "insert" operation within the same transaction. For |
828 | example, if an "insert" operation within this transaction | |
829 | specifies a "uuid-name" of "myrow", the following <named-uuid> | |
830 | represents the UUID created by that operation: | |
f85f8ebb BP |
831 | |
832 | ["named-uuid", "myrow"] | |
833 | ||
6e30ca63 BP |
834 | A <named-uuid> may be used anywhere a <uuid> is valid. |
835 | ||
f85f8ebb BP |
836 | <condition> |
837 | ||
838 | A 3-element JSON array of the form [<column>, <function>, | |
839 | <value>] that represents a test on a column value. | |
840 | ||
841 | Except as otherwise specified below, <value> must have the same | |
842 | type as <column>. | |
843 | ||
844 | The meaning depends on the type of <column>: | |
845 | ||
846 | integer | |
847 | real | |
848 | ||
849 | <function> must be "<", "<=", "==", "!=", ">=", ">", | |
850 | "includes", or "excludes". | |
851 | ||
852 | The test is true if the column's value satisfies the | |
853 | relation <function> <value>, e.g. if the column has value | |
854 | 1 and <value> is 2, the test is true if <function> is "<", | |
855 | "<=" or "!=", but not otherwise. | |
856 | ||
857 | "includes" is equivalent to "=="; "excludes" is equivalent | |
858 | to "!=". | |
859 | ||
860 | boolean | |
861 | string | |
862 | uuid | |
863 | ||
864 | <function> must be "!=", "==", "includes", or "excludes". | |
865 | ||
866 | If <function> is "==" or "includes", the test is true if | |
867 | the column's value equals <value>. If <function> is "!=" | |
868 | or "excludes", the test is inverted. | |
869 | ||
870 | set | |
871 | map | |
872 | ||
873 | <function> must be "!=", "==", "includes", or "excludes". | |
874 | ||
875 | If <function> is "==", the test is true if the column's | |
876 | value contains exactly the same values (for sets) or pairs | |
877 | (for maps). If <function> is "!=", the test is inverted. | |
878 | ||
879 | If <function> is "includes", the test is true if the | |
880 | column's value contains all of the values (for sets) or | |
881 | pairs (for maps) in <value>. The column's value may also | |
882 | contain other values or pairs. | |
883 | ||
884 | If <function> is "excludes", the test is true if the | |
885 | column's value does not contain any of the values (for | |
886 | sets) or pairs (for maps) in <value>. The column's value | |
887 | may contain other values or pairs not in <value>. | |
888 | ||
889 | If <function> is "includes" or "excludes", then the | |
890 | required type of <value> is slightly relaxed, in that it | |
891 | may have fewer than the minimum number of elements | |
892 | specified by the column's type. If <function> is | |
893 | "excludes", then the required type is additionally relaxed | |
894 | in that <value> may have more than the maximum number of | |
895 | elements specified by the column's type. | |
896 | ||
897 | <function> | |
898 | ||
899 | One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes". | |
900 | ||
e9f8f936 BP |
901 | <mutation> |
902 | ||
903 | A 3-element JSON array of the form [<column>, <mutator>, <value>] | |
904 | that represents a change to a column value. | |
905 | ||
906 | Except as otherwise specified below, <value> must have the same | |
907 | type as <column>. | |
908 | ||
909 | The meaning depends on the type of <column>: | |
910 | ||
911 | integer | |
912 | real | |
913 | ||
914 | <mutator> must be "+=", "-=", "*=", "/=" or (integer only) | |
915 | "%=". The value of <column> is changed to the sum, | |
916 | difference, product, quotient, or remainder, respectively, | |
917 | of <column> and <value>. | |
918 | ||
bd76d25d BP |
919 | Constraints on <column> are ignored when parsing <value>. |
920 | ||
e9f8f936 BP |
921 | boolean |
922 | string | |
923 | uuid | |
924 | ||
925 | No valid <mutator>s are currently defined for these types. | |
926 | ||
927 | set | |
928 | ||
929 | Any <mutator> valid for the set's element type may be | |
930 | applied to the set, in which case the mutation is applied | |
931 | to each member of the set individually. <value> must be a | |
bd76d25d BP |
932 | scalar value of the same type as the set's element type, |
933 | except that contraints are ignored. | |
e9f8f936 BP |
934 | |
935 | If <mutator> is "insert", then each of the values in the | |
936 | set in <value> is added to <column> if it is not already | |
937 | present. The required type of <value> is slightly | |
938 | relaxed, in that it may have fewer than the minimum number | |
939 | of elements specified by the column's type. | |
940 | ||
941 | If <mutator> is "delete", then each of the values in the | |
942 | set in <value> is removed from <column> if it is present | |
943 | there. The required type is slightly relaxed in that | |
944 | <value> may have more or less than the maximum number of | |
945 | elements specified by the column's type. | |
946 | ||
947 | map | |
948 | ||
949 | <mutator> must be "insert" or "delete". | |
950 | ||
951 | If <mutator> is "insert", then each of the key-value pairs | |
03b1f24e BP |
952 | in the map in <value> is added to <column> only if its key |
953 | is not already present. The required type of <value> is | |
e9f8f936 BP |
954 | slightly relaxed, in that it may have fewer than the |
955 | minimum number of elements specified by the column's type. | |
956 | ||
957 | If <mutator> is "delete", then <value> may have the same | |
958 | type as <column> (a map type) or it may be a set whose | |
959 | element type is the same as <column>'s key type: | |
960 | ||
961 | - If <value> is a map, the mutation deletes each | |
962 | key-value pair in <column> whose key and value equal | |
963 | one of the key-value pairs in <value>. | |
964 | ||
965 | - If <value> is a set, the mutation deletes each | |
966 | key-value pair in <column> whose key equals one of | |
967 | the values in <value>. | |
968 | ||
969 | For "delete", <value> may have any number of elements, | |
970 | regardless of restrictions on the number of elements in | |
971 | <column>. | |
972 | ||
973 | <mutator> | |
974 | ||
975 | One of "+=", "-=", "*=", "/=", "%=", "insert", "delete". | |
976 | ||
f85f8ebb BP |
977 | Operations |
978 | ---------- | |
979 | ||
980 | Each of the available operations is described below. | |
981 | ||
982 | insert | |
983 | ...... | |
984 | ||
985 | Request object members: | |
986 | ||
987 | "op": "insert" required | |
988 | "table": <table> required | |
989 | "row": <row> required | |
2d2d6d4a | 990 | "uuid-name": <id> optional |
f85f8ebb BP |
991 | |
992 | Result object members: | |
993 | ||
994 | "uuid": <uuid> | |
995 | ||
996 | Semantics: | |
997 | ||
bd76d25d BP |
998 | Inserts "row" into "table". |
999 | ||
1000 | If "row" does not specify values for all the columns in "table", | |
1001 | those columns receive default values. The default value for a | |
1002 | column depends on its type. The default for a column whose <type> | |
1003 | specifies a "min" of 0 is an empty set or empty map. Otherwise, | |
1004 | the default is a single value or a single key-value pair, whose | |
1005 | value(s) depend on its <atomic-type>: | |
1006 | ||
1007 | - "integer" or "real": 0 | |
1008 | ||
1009 | - "boolean": false | |
1010 | ||
1011 | - "string": "" (the empty string) | |
1012 | ||
1013 | - "uuid": 00000000-0000-0000-0000-000000000000 | |
f85f8ebb | 1014 | |
fbf925e4 | 1015 | The new row receives a new, randomly generated UUID. |
2d2d6d4a | 1016 | |
fbf925e4 BP |
1017 | If "uuid-name" is supplied, then it is an error if <id> is not |
1018 | unique among the "uuid-name"s supplied on all the "insert" | |
1019 | operations within this transaction. | |
2d2d6d4a BP |
1020 | |
1021 | The UUID for the new row is returned as the "uuid" member of the | |
1022 | result. | |
1023 | ||
1024 | Errors: | |
1025 | ||
1026 | "error": "duplicate uuid-name" | |
1027 | ||
fbf925e4 | 1028 | The same "uuid-name" appears on another "insert" operation |
2d2d6d4a | 1029 | within this transaction. |
f85f8ebb | 1030 | |
bd76d25d BP |
1031 | "error": "constraint violation" |
1032 | ||
1033 | One of the values in "row" does not satisfy the immediate | |
1034 | constraints for its column's <base-type>. This error will | |
1035 | occur for columns that are not explicitly set by "row" if the | |
1036 | default value does not satisfy the column's constraints. | |
1037 | ||
f85f8ebb BP |
1038 | select |
1039 | ...... | |
1040 | ||
1041 | Request object members: | |
1042 | ||
1043 | "op": "select" required | |
1044 | "table": <table> required | |
1045 | "where": [<condition>*] required | |
1046 | "columns": [<column>*] optional | |
1047 | ||
1048 | Result object members: | |
1049 | ||
1050 | "rows": [<row>*] | |
1051 | ||
1052 | Semantics: | |
1053 | ||
1054 | Searches "table" for rows that match all the conditions specified | |
1055 | in "where". If "where" is an empty array, every row in "table" is | |
1056 | selected. | |
1057 | ||
1058 | The "rows" member of the result is an array of objects. Each | |
1059 | object corresponds to a matching row, with each column | |
1060 | specified in "columns" as a member, the column's name as the | |
1061 | member name and its value as the member value. If "columns" | |
1062 | is not specified, all the table's columns are included. If | |
1063 | two rows of the result have the same values for all included | |
1064 | columns, only one copy of that row is included in "rows". | |
1065 | Specifying "_uuid" within "columns" will avoid dropping | |
1066 | duplicates, since every row has a unique UUID. | |
1067 | ||
1068 | The ordering of rows within "rows" is unspecified. | |
1069 | ||
1070 | update | |
1071 | ...... | |
1072 | ||
1073 | Request object members: | |
1074 | ||
1075 | "op": "update" required | |
1076 | "table": <table> required | |
1077 | "where": [<condition>*] required | |
1078 | "row": <row> required | |
1079 | ||
1080 | Result object members: | |
1081 | ||
1082 | "count": <integer> | |
1083 | ||
1084 | Semantics: | |
1085 | ||
1086 | Updates rows in a table. | |
1087 | ||
1088 | Searches "table" for rows that match all the conditions | |
1089 | specified in "where". For each matching row, changes the | |
1090 | value of each column specified in "row" to the value for that | |
1091 | column specified in "row". | |
1092 | ||
e68c3e48 | 1093 | The "_uuid" and "_version" columns of a table may not be directly |
c5c7c7c5 | 1094 | updated with this operation. Columns designated read-only in the |
e68c3e48 | 1095 | schema also may not be updated. |
f85f8ebb BP |
1096 | |
1097 | The "count" member of the result specifies the number of rows | |
1098 | that matched. | |
1099 | ||
bd76d25d BP |
1100 | Errors: |
1101 | ||
1102 | "error": "constraint violation" | |
1103 | ||
1104 | One of the values in "row" does not satisfy the immediate | |
1105 | constraints for its column's <base-type>. | |
e9f8f936 BP |
1106 | mutate |
1107 | ...... | |
1108 | ||
1109 | Request object members: | |
1110 | ||
1111 | "op": "mutate" required | |
1112 | "table": <table> required | |
1113 | "where": [<condition>*] required | |
1114 | "mutations": [<mutation>*] required | |
1115 | ||
1116 | Result object members: | |
1117 | ||
1118 | "count": <integer> | |
1119 | ||
1120 | Semantics: | |
1121 | ||
1122 | Mutates rows in a table. | |
1123 | ||
1124 | Searches "table" for rows that match all the conditions specified | |
1125 | in "where". For each matching row, mutates its columns as | |
1126 | specified by each <mutation> in "mutations", in the order | |
1127 | specified. | |
1128 | ||
1129 | The "_uuid" and "_version" columns of a table may not be directly | |
1130 | modified with this operation. Columns designated read-only in the | |
1131 | schema also may not be updated. | |
1132 | ||
1133 | The "count" member of the result specifies the number of rows | |
1134 | that matched. | |
1135 | ||
1136 | Errors: | |
1137 | ||
1138 | "error": "domain error" | |
1139 | ||
1140 | The result of the mutation is not mathematically defined, | |
1141 | e.g. division by zero. | |
1142 | ||
1143 | "error": "range error" | |
1144 | ||
1145 | The result of the mutation is not representable within the | |
1146 | database's format, e.g. an integer result outside the range | |
1147 | INT64_MIN...INT64_MAX or a real result outside the range | |
1148 | -DBL_MAX...DBL_MAX. | |
1149 | ||
1150 | "error": "constraint violation" | |
1151 | ||
1152 | The mutation caused the column's value to violate a | |
1153 | constraint, e.g. it caused a column to have more or fewer | |
bd76d25d BP |
1154 | values than are allowed, an arithmetic operation caused a set |
1155 | or map to have duplicate elements, or it violated a constraint | |
1156 | specified by a column's <base-type>. | |
e9f8f936 | 1157 | |
f85f8ebb BP |
1158 | delete |
1159 | ...... | |
1160 | ||
1161 | Request object members: | |
1162 | ||
1163 | "op": "delete" required | |
1164 | "table": <table> required | |
1165 | "where": [<condition>*] required | |
1166 | ||
1167 | Result object members: | |
1168 | ||
1169 | "count": <integer> | |
1170 | ||
1171 | Semantics: | |
1172 | ||
1173 | Deletes all the rows from "table" that match all the conditions | |
1174 | specified in "where". | |
1175 | ||
1176 | The "count" member of the result specifies the number of deleted | |
1177 | rows. | |
1178 | ||
1179 | wait | |
1180 | .... | |
1181 | ||
1182 | Request object members: | |
1183 | ||
1184 | "op": "wait" required | |
1185 | "timeout": <integer> optional | |
1186 | "table": <table> required | |
1187 | "where": [<condition>*] required | |
1188 | "columns": [<column>*] required | |
1189 | "until": "==" or "!=" required | |
1190 | "rows": [<row>*] required | |
1191 | ||
1192 | Result object members: | |
1193 | ||
1194 | none | |
1195 | ||
1196 | Semantics: | |
1197 | ||
1198 | Waits until a condition becomes true. | |
1199 | ||
1200 | If "until" is "==", checks whether the query on "table" specified | |
1201 | by "where" and "columns", which is evaluated in the same way as | |
1202 | specified for "select", returns the result set specified by | |
1203 | "rows". If it does, then the operation completes successfully. | |
1204 | Otherwise, the entire transaction rolls back. It is automatically | |
1205 | restarted later, after a change in the database makes it possible | |
1206 | for the operation to succeed. The client will not receive a | |
1207 | response until the operation permanently succeeds or fails. | |
c5c7c7c5 | 1208 | |
f85f8ebb BP |
1209 | If "until" is "!=", the sense of the test is negated. That is, as |
1210 | long as the query on "table" specified by "where" and "columns" | |
1211 | returns "rows", the transaction will be rolled back and restarted | |
1212 | later. | |
1213 | ||
1214 | If "timeout" is specified, then the transaction aborts after the | |
1215 | specified number of milliseconds. The transaction is guaranteed | |
1216 | to be attempted at least once before it aborts. A "timeout" of 0 | |
1217 | will abort the transaction on the first mismatch. | |
1218 | ||
1219 | Errors: | |
1220 | ||
1221 | "error": "not supported" | |
1222 | ||
1223 | One or more of the columns in this table do not support | |
1224 | triggers. This error will not occur if "timeout" is 0. | |
1225 | ||
1226 | "error": "timed out" | |
1227 | ||
1228 | The "timeout" was reached before the transaction was able to | |
1229 | complete. | |
1230 | ||
1231 | commit | |
1232 | ...... | |
1233 | ||
1234 | Request object members: | |
1235 | ||
1236 | "op": "commit" required | |
1237 | "durable": <boolean> required | |
1238 | ||
1239 | Result object members: | |
1240 | ||
1241 | none | |
1242 | ||
1243 | Semantics: | |
1244 | ||
1245 | If "durable" is specified as true, then the transaction, if it | |
1246 | commits, will be stored durably (to disk) before the reply is sent | |
1247 | to the client. | |
1248 | ||
1249 | Errors: | |
1250 | ||
1251 | "error": "not supported" | |
1252 | ||
1253 | When "durable" is true, this database implementation does not | |
1254 | support durable commits. | |
1255 | ||
1256 | abort | |
1257 | ..... | |
1258 | ||
1259 | Request object members: | |
1260 | ||
1261 | "op": "abort" required | |
1262 | ||
1263 | Result object members: | |
1264 | ||
1265 | (never succeeds) | |
1266 | ||
1267 | Semantics: | |
1268 | ||
1269 | Aborts the transaction with an error. This may be useful for | |
1270 | testing. | |
1271 | ||
1272 | Errors: | |
1273 | ||
1274 | "error": "aborted" | |
1275 | ||
1276 | This operation always fails with this error. | |
2d2d6d4a | 1277 | |
d171b584 BP |
1278 | comment |
1279 | ....... | |
1280 | ||
1281 | ||
1282 | Request object members: | |
1283 | ||
1284 | "op": "comment" required | |
1285 | "comment": <string> required | |
1286 | ||
1287 | Result object members: | |
1288 | ||
1289 | none | |
1290 | ||
1291 | Semantics: | |
1292 | ||
1293 | Provides information to a database administrator on the purpose of | |
1294 | a transaction. The OVSDB server, for example, adds comments in | |
1295 | transactions that modify the database to the database journal. | |
da897f41 BP |
1296 | |
1297 | assert | |
1298 | ...... | |
1299 | ||
1300 | Request object members: | |
1301 | ||
1302 | "op": "assert" required | |
454ec971 | 1303 | "lock": <id> required |
da897f41 BP |
1304 | |
1305 | Result object members: | |
1306 | ||
1307 | none | |
1308 | ||
1309 | Semantics: | |
1310 | ||
1311 | If the client does not own the lock named <string>, aborts the | |
1312 | transaction. | |
1313 | ||
1314 | Errors: | |
1315 | ||
1316 | "error": "not owner" | |
1317 | ||
1318 | The client does not own the named lock. |