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