netdev-vport: Don't create port when ovs-monitor-ipsec not running.
[openvswitch] / 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
136     The value of "columns" is a JSON object whose names are column
137     names and whose values are <column-schema>s.
138
139     Every table has the following columns whose definitions are not
140     included in the schema:
141
142         "_uuid": This column, which contains exactly one UUID value,
143         is initialized to a random value by the database engine when
144         it creates a row.  It is read-only, and its value never
145         changes during the lifetime of a row.
146
147         "_version": Like "_uuid", this column contains exactly one
148         UUID value, initialized to a random value by the database
149         engine when it creates a row, and it is read-only.  However,
150         its value changes to a new random value whenever any other
151         field in the row changes.  Furthermore, its value is
152         ephemeral: when the database is closed and reopened, or when
153         the database process is stopped and then started again, each
154         "_version" also changes to a new random value.
155
156     If "isRoot" is omitted or specified as false, then any given row
157     in the table may exist only when there is at least one reference
158     to it, with refType "strong", from a different row (in the same
159     table or a different table).  This is a "deferred" action:
160     unreferenced rows in the table are deleted just before transaction
161     commit.  If "isRoot" is specified as true, then rows in the table
162     exist independent of any references (they can be thought of as
163     part of the "root set" in a garbage collector).
164
165     For compatibility with schemas created before "isRoot" was
166     introduced, if "isRoot" is omitted or false in every
167     <table-schema> in a given <database-schema>, then every table is
168     part of the root set.
169
170     If "maxRows" is specified, as a positive integer, it limits the
171     maximum number of rows that may be present in the table.  This is
172     a "deferred" constraint, enforced only at transaction commit time
173     (see the "transact" request below).  If "maxRows" is not
174     specified, the size of the table is limited only by the resources
175     available to the database server.  "maxRows" constraints are
176     enforced after unreferenced rows are deleted from tables with a
177     false "isRoot".
178
179 <column-schema>
180
181     A JSON object with the following members:
182
183         "type": <type>                            required
184         "ephemeral": <boolean>                    optional
185         "mutable": <boolean>                      optional
186
187     The "type" specifies the type of data stored in this column.  If
188     "ephemeral" is specified as true, then this column's values are
189     not guaranteed to be durable; they may be lost when the database
190     restarts.  If "mutable" is specified as false, then this column's
191     values may not be modified after they are initially set with the
192     "insert" operation.
193
194 <type>
195
196     The type of a database column.  Either an <atomic-type> or a JSON
197     object that describes the type of a database column, with the
198     following members:
199
200         "key": <base-type>                 required
201         "value": <base-type>               optional
202         "min": <integer>                   optional
203         "max": <integer> or "unlimited"    optional
204
205     If "min" or "max" is not specified, each defaults to 1.  If "max"
206     is specified as "unlimited", then there is no specified maximum
207     number of elements, although the implementation will enforce some
208     limit.  After considering defaults, "min" must be exactly 0 or
209     exactly 1, "max" must be at least 1, and "max" must be greater
210     than or equal to "min".
211
212     If "min" and "max" are both 1 and "value" is not specified, the
213     type is the scalar type specified by "key".
214
215     If "min" is not 1 or "max" is not 1, or both, and "value" is not
216     specified, the type is a set of scalar type "key".
217
218     If "value" is specified, the type is a map from type "key" to type
219     "value".
220
221 <base-type>
222
223     The type of a key or value in a database column.  Either an
224     <atomic-type> or a JSON object with the following members:
225
226         "type": <atomic-type>              required
227         "enum": <value>                    optional
228         "minInteger": <integer>            optional, integers only
229         "maxInteger": <integer>            optional, integers only
230         "minReal": <real>                  optional, reals only
231         "maxReal": <real>                  optional, reals only
232         "minLength": <integer>             optional, strings only
233         "maxLength": <integer>             optional, strings only
234         "refTable": <id>                   optional, uuids only
235         "refType": "strong" or "weak"      optional, only with "refTable"
236
237     An <atomic-type> by itself is equivalent to a JSON object with a
238     single member "type" whose value is the <atomic-type>.
239
240     "enum" may be specified as a <value> whose type is a set of one
241     or more values specified for the member "type".  If "enum" is
242     specified, then the valid values of the <base-type> are limited to
243     those in the <value>.
244
245     "enum" is mutually exclusive with the following constraints.
246
247     If "type" is "integer", then "minInteger" or "maxInteger" or both
248     may also be specified, restricting the valid integer range.  If
249     both are specified, then the maxInteger must be greater than or
250     equal to minInteger.
251
252     If "type" is "real", then "minReal" or "maxReal" or both may also
253     be specified, restricting the valid real range.  If both are
254     specified, then the maxReal must be greater than or equal to
255     minReal.
256
257     If "type" is "string", then "minLength" and "maxLength" or both
258     may be specified, restricting the valid length of value strings.
259     If both are specified, then maxLength must be greater than or
260     equal to minLength.  String length is measured in characters (not
261     bytes or UTF-16 code units).
262
263     If "type" is "uuid", then "refTable", if present, must be the name
264     of a table within this database.  If "refTable" is specified, then
265     "refType" may also be specified.  If "refTable" is set, the effect
266     depends on "refType":
267
268         - If "refType" is "strong" or if "refType" is omitted, the
269           allowed UUIDs are limited to UUIDs for rows in the named
270           table.
271
272         - If "refType" is "weak", then any UUIDs are allowed, but
273           UUIDs that do not correspond to rows in the named table will
274           be automatically deleted.
275
276     "refTable" constraints are "deferred" constraints: they are
277     enforced only at transaction commit time (see the "transact"
278     request below).  The other contraints on <base-type> are
279     "immediate", enforced immediately by each operation.
280
281 <atomic-type>
282
283     One of the strings "integer", "real", "boolean", "string", or
284     "uuid", representing the specified scalar type.
285
286 Wire Protocol
287 -------------
288
289 The database wire protocol is implemented in JSON-RPC 1.0.  We
290 encourage use of JSON-RPC over stream connections instead of JSON-RPC
291 over HTTP, for these reasons:
292
293     * JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server
294       protocol, which is a poor match.  Thus, JSON-RPC over HTTP
295       requires the client to periodically poll the server to receive
296       server requests.
297
298     * HTTP is more complicated than stream connections and doesn't
299       provide any corresponding advantage.
300
301     * The JSON-RPC specification for HTTP transport is incomplete.
302
303 We are using TCP port 6632 for the database JSON-RPC connection.
304
305 The database wire protocol consists of the following JSON-RPC methods:
306
307 list_dbs
308 ........
309
310 Request object members:
311
312     "method": "list_dbs"              required
313     "params": []                      required
314     "id": <nonnull-json-value>        required
315
316 Response object members:
317
318     "result": [<db-name>, ...]
319     "error": null
320     "id": same "id" as request
321
322 This operation retrieves an array whose elements are <db-name>s
323 that name the databases that can be accessed over this JSON-RPC
324 connection.
325
326 get_schema
327 ..........
328
329 Request object members:
330
331     "method": "get_schema"            required
332     "params": [<db-name>]             required
333     "id": <nonnull-json-value>        required
334
335 Response object members:
336
337     "result": <database-schema>
338     "error": null
339     "id": same "id" as request
340
341 This operation retrieves a <database-schema> that describes hosted
342 database <db-name>.
343
344 transact
345 ........
346
347 Request object members:
348
349     "method": "transact"                  required
350     "params": [<db-name>, <operation>*]   required
351     "id": <nonnull-json-value>            required
352
353 Response object members:
354
355     "result": [<object>*]
356     "error": null
357     "id": same "id" as request
358
359 The "params" array for this method consists of a <db-name> that
360 identifies the database to which the transaction applies, followed by
361 zero or more JSON objects, each of which represents a single database
362 operation.  The "Operations" section below describes the valid
363 operations.
364
365 The value of "id" must be unique among all in-flight transactions
366 within the current JSON-RPC session.  Otherwise, the server may return
367 a JSON-RPC error.
368
369 The database server executes each of the specified operations in the
370 specified order, except that if an operation fails, then the remaining
371 operations are not executed.
372
373 The set of operations is executed as a single atomic, consistent,
374 isolated transaction.  The transaction is committed only if every
375 operation succeeds.  Durability of the commit is not guaranteed unless
376 the "commit" operation, with "durable" set to true, is included in the
377 operation set (see below).
378
379 Regardless of whether errors occur, the response is always a JSON-RPC
380 response with null "error" and a "result" member that is an array with
381 the same number of elements as "params".  Each element of the "result"
382 array corresponds to the same element of the "params" array.  The
383 "result" array elements may be interpreted as follows:
384
385     - A JSON object that does not contain an "error" member indicates
386       that the operation completed successfully.  The specific members
387       of the object are specified below in the descriptions of
388       individual operations.  Some operations do not produce any
389       results, in which case the object will have no members.
390
391     - An <error>, which indicates that the operation completed with an
392       error.
393
394     - A JSON null value indicates that the operation was not attempted
395       because a prior operation failed.
396
397 In general, "result" contains some number of successful results,
398 possibly followed by an error, in turn followed by enough JSON null
399 values to match the number of elements in "params".  There is one
400 exception: if all of the operations succeed, but the results cannot be
401 committed, then "result" will have one more element than "params",
402 with the additional element an <error>.  The possible "error" strings
403 include at least the following:
404
405     "error": "referential integrity violation"
406
407         When the commit was attempted, a column's value referenced the
408         UUID for a row that did not exist in the table named by the
409         column's <base-type> key or value "refTable" that has a
410         "refType" of "strong".  (This can be caused by inserting a row
411         that references a nonexistent row, by deleting a row that is
412         still referenced by another row, by specifying the UUID for a
413         row in the wrong table, and other ways.)
414
415     "error": "constraint violation"
416
417         A column with a <base-type> key or value "refTable" whose
418         "refType" is "weak" became empty due to deletion(s) caused
419         because the rows that it referenced were deleted (or never
420         existed, if the column's row was inserted within the
421         transaction), and this column is not allowed to be empty
422         because its <type> has a "min" of 1.
423
424     "error": "constraint violation"
425
426         The number of rows in a table exceeds the maximum number
427         permitted by the table's "maxRows" value (see <table-schema>).
428
429 If "params" contains one or more "wait" operations, then the
430 transaction may take an arbitrary amount of time to complete.  The
431 database implementation must be capable of accepting, executing, and
432 replying to other transactions and other JSON-RPC requests while a
433 transaction or transactions containing "wait" operations are
434 outstanding on the same or different JSON-RPC sessions.
435
436 The section "Notation for the Wire Protocol" below describes
437 additional notation for use with the wire protocol.  After that, the
438 "Operations" section describes each operation.
439
440 cancel
441 ......
442
443 Request object members:
444
445     "method": "cancel"                              required
446     "params": [the "id" for an outstanding request] required
447     "id": null                                      required
448
449 Response object members:
450
451     <no response>
452
453 This JSON-RPC notification instructs the database server to
454 immediately complete or cancel the "transact" request whose "id" is
455 the same as the notification's "params" value.
456
457 If the "transact" request can be completed immediately, then the
458 server sends a response in the form described for "transact", above.
459 Otherwise, the server sends a JSON-RPC error response of the following
460 form:
461
462     "result": null
463     "error": "canceled"
464     "id": the request "id" member
465
466 The "cancel" notification itself has no reply.
467
468 monitor
469 .......
470
471 Request object members:
472
473     "method": "monitor"                                       required
474     "params": [<db-name>, <json-value>, <monitor-requests>]   required
475     "id": <nonnull-json-value>                                required
476
477 <monitor-requests> is an object that maps from a table name to an
478 array of <monitor-request> objects.  For backward compatibility, a
479 single <monitor-request> may be used instead of an array; it is
480 treated as a single-element array.
481
482 Each <monitor-request> is an object with the following members:
483
484     "columns": [<column>*]            optional
485     "select": <monitor-select>        optional
486
487 <monitor-select> is an object with the following members:
488
489     "initial": <boolean>              optional
490     "insert": <boolean>               optional
491     "delete": <boolean>               optional
492     "modify": <boolean>               optional
493
494 Response object members:
495
496     "result": <table-updates>
497     "error": null
498     "id": same "id" as request
499
500 This JSON-RPC request enables a client to replicate tables or subsets
501 of tables within database <db-name>.  Each element of
502 <monitor-requests> specifies a table to be replicated.  The JSON-RPC
503 response to the "monitor" includes the initial contents of each table,
504 unless disabled (see below).  Afterward, when changes to those tables
505 are committed, the changes are automatically sent to the client using
506 the "update" monitor notification.  This monitoring persists until the
507 JSON-RPC session terminates or until the client sends a
508 "monitor_cancel" JSON-RPC request.
509
510 Each <monitor-request> describes how to monitor columns in a table:
511
512     The circumstances in which an "update" notification is sent for a
513     row within the table are determined by <monitor-select>:
514
515         If "initial" is omitted or true, every row in the table is
516         sent as part of the reply to the "monitor" request.
517
518         If "insert" is omitted or true, "update" notifications are
519         sent for rows newly inserted into the table.
520
521         If "delete" is omitted or true, "update" notifications are
522         sent for rows deleted from the table.
523
524         If "modify" is omitted or true, "update" notifications are
525         sent whenever when a row in the table is modified.
526
527     The "columns" member specifies the columns whose values are
528     monitored.  It must not contain duplicates.  If "columns" is
529     omitted, all columns in the table, except for "_uuid", are
530     monitored.
531
532 If there is more than one <monitor-request> in an array of them, then
533 each <monitor-request> in the array should specify both "columns" and
534 "select", and the "columns" must be non-overlapping sets.
535
536 The "result" in the JSON-RPC response to the "monitor" request is a
537 <table-updates> object (see below) that contains the contents of the
538 tables for which "initial" rows are selected.  If no tables' initial
539 contents are requested, then "result" is an empty object.
540
541 update
542 ......
543
544 Notification object members:
545
546     "method": "update"
547     "params": [<json-value>, <table-updates>]
548     "id": null
549
550 The <json-value> in "params" is the same as the value passed as the
551 <json-value> in "params" for the "monitor" request.
552
553 <table-updates> is an object that maps from a table name to a
554 <table-update>.
555
556 A <table-update> is an object that maps from the row's UUID (as a
557 36-byte string) to a <row-update> object.
558
559 A <row-update> is an object with the following members:
560
561     "old": <row>         present for "delete" and "modify" updates
562     "new": <row>         present for "initial", "insert", and "modify" updates
563
564 This JSON-RPC notification is sent from the server to the client to
565 tell it about changes to a monitored table (or the initial state of a
566 modified table).  Each table in which one or more rows has changed (or
567 whose initial view is being presented) is represented in "updates".
568 Each row that has changed (or whose initial view is being presented)
569 is represented in its <table-update> as a member with its name taken
570 from the row's _uuid member.  The corresponding value is a
571 <row-update>:
572
573     The "old" member is present for "delete" and "modify" updates.
574     For "delete" updates, each monitored column is included.  For
575     "modify" updates, the prior value of each monitored column whose
576     value has changed is included (monitored columns that have not
577     changed are represented in "new").
578
579     The "new" member is present for "initial", "insert", and "modify"
580     updates.  For "initial" and "insert" updates, each monitored
581     column is included.  For "modify" updates, the new value of each
582     monitored column is included.
583
584 monitor_cancel
585 ..............
586
587 Request object members:
588
589     "method": "monitor_cancel"                              required
590     "params": [<json-value>]                                required
591     "id": <nonnull-json-value>                              required
592
593 Response object members:
594
595     "result": {}
596     "error": null
597     "id": the request "id" member
598
599 Cancels the ongoing table monitor request, identified by the
600 <json-value> in "params" matching the <json-value> in "params" for an
601 ongoing "monitor" request.  No more "update" messages will be sent for
602 this table monitor.
603
604 echo
605 ....
606
607 Request object members:
608
609     "method": "echo"                                required
610     "params": JSON array with any contents          required
611     "id": <json-value>                              required
612
613 Response object members:
614
615     "result": same as "params"
616     "error": null
617     "id": the request "id" member
618
619 Both the JSON-RPC client and the server must implement this request.
620
621 This JSON-RPC request and response can be used to implement connection
622 keepalives, by allowing the server to check that the client is still
623 there or vice versa.
624
625
626 Notation for the Wire Protocol
627 ------------------------------
628
629 <db-name>
630
631     An <id> that names a database.  The valid <db-name>s can be
632     obtained using a "list-db" request.  The <db-name> is taken from
633     the "name" member of <database-schema>.
634
635 <table>
636
637     An <id> that names a table.
638
639 <column>
640
641     An <id> that names a table column.
642
643 <row>
644
645     A JSON object that describes a table row or a subset of a table
646     row.  Each member is the name of a table column paired with the
647     <value> of that column.
648
649 <value>
650
651     A JSON value that represents the value of a column in a table row,
652     one of <atom>, a <set>, or a <map>.
653
654 <atom>
655
656     A JSON value that represents a scalar value for a column, one of
657     <string>, <number>, <boolean>, <uuid>, <named-uuid>.
658
659 <set>
660
661     Either an <atom>, representing a set with exactly one element, or
662     a 2-element JSON array that represents a database set value.  The
663     first element of the array must be the string "set" and the second
664     element must be an array of zero or more <atom>s giving the values
665     in the set.  All of the <atom>s must have the same type.
666
667 <map>
668
669     A 2-element JSON array that represents a database map value.  The
670     first element of the array must be the string "map" and the second
671     element must be an array of zero or more <pair>s giving the values
672     in the map.  All of the <pair>s must have the same key and value
673     types.
674
675     (JSON objects are not used to represent <map> because JSON only
676     allows string names in an object.)
677
678 <pair>
679
680     A 2-element JSON array that represents a pair within a database
681     map.  The first element is an <atom> that represents the key, the
682     second element is an <atom> that represents the value.
683
684 <uuid>
685
686     A 2-element JSON array that represents a UUID.  The first element
687     of the array must be the string "uuid" and the second element must
688     be a 36-character string giving the UUID in the format described
689     by RFC 4122.  For example, the following <uuid> represents the
690     UUID 550e8400-e29b-41d4-a716-446655440000:
691
692         ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
693
694 <named-uuid>
695
696     A 2-element JSON array that represents the UUID of a row inserted
697     in an "insert" operation within the same transaction.  The first
698     element of the array must be the string "named-uuid" and the
699     second element should be the <id> specified as the "uuid-name"
700     for an "insert" operation within the same transaction.  For
701     example, if an "insert" operation within this transaction
702     specifies a "uuid-name" of "myrow", the following <named-uuid>
703     represents the UUID created by that operation:
704
705         ["named-uuid", "myrow"]
706
707     A <named-uuid> may be used anywhere a <uuid> is valid.
708
709 <condition>
710
711     A 3-element JSON array of the form [<column>, <function>,
712     <value>] that represents a test on a column value.
713
714     Except as otherwise specified below, <value> must have the same
715     type as <column>.
716
717     The meaning depends on the type of <column>:
718
719         integer
720         real
721
722             <function> must be "<", "<=", "==", "!=", ">=", ">",
723             "includes", or "excludes".
724
725             The test is true if the column's value satisfies the
726             relation <function> <value>, e.g. if the column has value
727             1 and <value> is 2, the test is true if <function> is "<",
728             "<=" or "!=", but not otherwise.
729
730             "includes" is equivalent to "=="; "excludes" is equivalent
731             to "!=".
732
733         boolean
734         string
735         uuid
736
737             <function> must be "!=", "==", "includes", or "excludes".
738
739             If <function> is "==" or "includes", the test is true if
740             the column's value equals <value>.  If <function> is "!="
741             or "excludes", the test is inverted.
742
743         set
744         map
745
746             <function> must be "!=", "==", "includes", or "excludes".
747
748             If <function> is "==", the test is true if the column's
749             value contains exactly the same values (for sets) or pairs
750             (for maps).  If <function> is "!=", the test is inverted.
751
752             If <function> is "includes", the test is true if the
753             column's value contains all of the values (for sets) or
754             pairs (for maps) in <value>.  The column's value may also
755             contain other values or pairs.
756
757             If <function> is "excludes", the test is true if the
758             column's value does not contain any of the values (for
759             sets) or pairs (for maps) in <value>.  The column's value
760             may contain other values or pairs not in <value>.
761
762             If <function> is "includes" or "excludes", then the
763             required type of <value> is slightly relaxed, in that it
764             may have fewer than the minimum number of elements
765             specified by the column's type.  If <function> is
766             "excludes", then the required type is additionally relaxed
767             in that <value> may have more than the maximum number of
768             elements specified by the column's type.
769
770 <function>
771
772     One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
773
774 <mutation>
775
776     A 3-element JSON array of the form [<column>, <mutator>, <value>]
777     that represents a change to a column value.
778
779     Except as otherwise specified below, <value> must have the same
780     type as <column>.
781
782     The meaning depends on the type of <column>:
783
784         integer
785         real
786
787             <mutator> must be "+=", "-=", "*=", "/=" or (integer only)
788             "%=".  The value of <column> is changed to the sum,
789             difference, product, quotient, or remainder, respectively,
790             of <column> and <value>.
791
792             Constraints on <column> are ignored when parsing <value>.
793
794         boolean
795         string
796         uuid
797
798             No valid <mutator>s are currently defined for these types.
799
800         set
801
802             Any <mutator> valid for the set's element type may be
803             applied to the set, in which case the mutation is applied
804             to each member of the set individually.  <value> must be a
805             scalar value of the same type as the set's element type,
806             except that contraints are ignored.
807
808             If <mutator> is "insert", then each of the values in the
809             set in <value> is added to <column> if it is not already
810             present.  The required type of <value> is slightly
811             relaxed, in that it may have fewer than the minimum number
812             of elements specified by the column's type.
813
814             If <mutator> is "delete", then each of the values in the
815             set in <value> is removed from <column> if it is present
816             there.  The required type is slightly relaxed in that
817             <value> may have more or less than the maximum number of
818             elements specified by the column's type.
819
820         map
821
822             <mutator> must be "insert" or "delete".
823
824             If <mutator> is "insert", then each of the key-value pairs
825             in the map in <value> is added to <column> only if its key
826             is not already present.  The required type of <value> is
827             slightly relaxed, in that it may have fewer than the
828             minimum number of elements specified by the column's type.
829
830             If <mutator> is "delete", then <value> may have the same
831             type as <column> (a map type) or it may be a set whose
832             element type is the same as <column>'s key type:
833
834                 - If <value> is a map, the mutation deletes each
835                   key-value pair in <column> whose key and value equal
836                   one of the key-value pairs in <value>.
837
838                 - If <value> is a set, the mutation deletes each
839                   key-value pair in <column> whose key equals one of
840                   the values in <value>.
841
842             For "delete", <value> may have any number of elements,
843             regardless of restrictions on the number of elements in
844             <column>.
845
846 <mutator>
847
848     One of "+=", "-=", "*=", "/=", "%=", "insert", "delete".
849
850 Operations
851 ----------
852
853 Each of the available operations is described below.
854
855 insert
856 ......
857
858 Request object members:
859
860     "op": "insert"          required
861     "table": <table>        required
862     "row": <row>            required
863     "uuid-name": <id>       optional
864
865 Result object members:
866
867     "uuid": <uuid>
868
869 Semantics:
870
871     Inserts "row" into "table".
872
873     If "row" does not specify values for all the columns in "table",
874     those columns receive default values.  The default value for a
875     column depends on its type.  The default for a column whose <type>
876     specifies a "min" of 0 is an empty set or empty map.  Otherwise,
877     the default is a single value or a single key-value pair, whose
878     value(s) depend on its <atomic-type>:
879
880         - "integer" or "real": 0
881
882         - "boolean": false
883
884         - "string": "" (the empty string)
885
886         - "uuid": 00000000-0000-0000-0000-000000000000
887
888     The new row receives a new, randomly generated UUID.
889
890     If "uuid-name" is supplied, then it is an error if <id> is not
891     unique among the "uuid-name"s supplied on all the "insert"
892     operations within this transaction.
893
894     The UUID for the new row is returned as the "uuid" member of the
895     result.
896
897 Errors:
898
899     "error": "duplicate uuid-name"
900
901         The same "uuid-name" appears on another "insert" operation
902         within this transaction.
903
904     "error": "constraint violation"
905
906         One of the values in "row" does not satisfy the immediate
907         constraints for its column's <base-type>.  This error will
908         occur for columns that are not explicitly set by "row" if the
909         default value does not satisfy the column's constraints.
910
911 select
912 ......
913
914 Request object members:
915
916     "op": "select"                required
917     "table": <table>              required
918     "where": [<condition>*]       required
919     "columns": [<column>*]        optional
920
921 Result object members:
922
923     "rows": [<row>*]
924
925 Semantics:
926
927     Searches "table" for rows that match all the conditions specified
928     in "where".  If "where" is an empty array, every row in "table" is
929     selected.
930
931     The "rows" member of the result is an array of objects.  Each
932     object corresponds to a matching row, with each column
933     specified in "columns" as a member, the column's name as the
934     member name and its value as the member value.  If "columns"
935     is not specified, all the table's columns are included.  If
936     two rows of the result have the same values for all included
937     columns, only one copy of that row is included in "rows".
938     Specifying "_uuid" within "columns" will avoid dropping
939     duplicates, since every row has a unique UUID.
940
941     The ordering of rows within "rows" is unspecified.
942
943 update
944 ......
945
946 Request object members:
947
948     "op": "update"                required
949     "table": <table>              required
950     "where": [<condition>*]       required
951     "row": <row>                  required
952
953 Result object members:
954
955     "count": <integer>
956
957 Semantics:
958
959     Updates rows in a table.
960
961     Searches "table" for rows that match all the conditions
962     specified in "where".  For each matching row, changes the
963     value of each column specified in "row" to the value for that
964     column specified in "row".
965
966     The "_uuid" and "_version" columns of a table may not be directly
967     updated with this operation.  Columns designated read-only in the
968     schema also may not be updated.
969
970     The "count" member of the result specifies the number of rows
971     that matched.
972
973 Errors:
974
975     "error": "constraint violation"
976
977         One of the values in "row" does not satisfy the immediate
978         constraints for its column's <base-type>.
979 mutate
980 ......
981
982 Request object members:
983
984     "op": "mutate"                required
985     "table": <table>              required
986     "where": [<condition>*]       required
987     "mutations": [<mutation>*]    required
988
989 Result object members:
990
991     "count": <integer>
992
993 Semantics:
994
995     Mutates rows in a table.
996
997     Searches "table" for rows that match all the conditions specified
998     in "where".  For each matching row, mutates its columns as
999     specified by each <mutation> in "mutations", in the order
1000     specified.
1001
1002     The "_uuid" and "_version" columns of a table may not be directly
1003     modified with this operation.  Columns designated read-only in the
1004     schema also may not be updated.
1005
1006     The "count" member of the result specifies the number of rows
1007     that matched.
1008
1009 Errors:
1010
1011     "error": "domain error"
1012
1013         The result of the mutation is not mathematically defined,
1014         e.g. division by zero.
1015
1016     "error": "range error"
1017
1018         The result of the mutation is not representable within the
1019         database's format, e.g. an integer result outside the range
1020         INT64_MIN...INT64_MAX or a real result outside the range
1021         -DBL_MAX...DBL_MAX.
1022
1023     "error": "constraint violation"
1024
1025         The mutation caused the column's value to violate a
1026         constraint, e.g. it caused a column to have more or fewer
1027         values than are allowed, an arithmetic operation caused a set
1028         or map to have duplicate elements, or it violated a constraint
1029         specified by a column's <base-type>.
1030
1031 delete
1032 ......
1033
1034 Request object members:
1035
1036     "op": "delete"                required
1037     "table": <table>              required
1038     "where": [<condition>*]       required
1039
1040 Result object members:
1041
1042     "count": <integer>
1043
1044 Semantics:
1045
1046     Deletes all the rows from "table" that match all the conditions
1047     specified in "where".
1048
1049     The "count" member of the result specifies the number of deleted
1050     rows.
1051
1052 wait
1053 ....
1054
1055 Request object members:
1056
1057     "op": "wait"                        required
1058     "timeout": <integer>                optional
1059     "table": <table>                    required
1060     "where": [<condition>*]             required
1061     "columns": [<column>*]              required
1062     "until": "==" or "!="               required
1063     "rows": [<row>*]                    required
1064
1065 Result object members:
1066
1067     none
1068
1069 Semantics:
1070
1071     Waits until a condition becomes true.
1072
1073     If "until" is "==", checks whether the query on "table" specified
1074     by "where" and "columns", which is evaluated in the same way as
1075     specified for "select", returns the result set specified by
1076     "rows".  If it does, then the operation completes successfully.
1077     Otherwise, the entire transaction rolls back.  It is automatically
1078     restarted later, after a change in the database makes it possible
1079     for the operation to succeed.  The client will not receive a
1080     response until the operation permanently succeeds or fails.
1081
1082     If "until" is "!=", the sense of the test is negated.  That is, as
1083     long as the query on "table" specified by "where" and "columns"
1084     returns "rows", the transaction will be rolled back and restarted
1085     later.
1086
1087     If "timeout" is specified, then the transaction aborts after the
1088     specified number of milliseconds.  The transaction is guaranteed
1089     to be attempted at least once before it aborts.  A "timeout" of 0
1090     will abort the transaction on the first mismatch.
1091
1092 Errors:
1093
1094     "error": "not supported"
1095
1096         One or more of the columns in this table do not support
1097         triggers.  This error will not occur if "timeout" is 0.
1098
1099     "error": "timed out"
1100
1101         The "timeout" was reached before the transaction was able to
1102         complete.
1103
1104 commit
1105 ......
1106
1107 Request object members:
1108
1109     "op": "commit"                      required
1110     "durable": <boolean>                required
1111
1112 Result object members:
1113
1114     none
1115
1116 Semantics:
1117
1118     If "durable" is specified as true, then the transaction, if it
1119     commits, will be stored durably (to disk) before the reply is sent
1120     to the client.
1121
1122 Errors:
1123
1124     "error": "not supported"
1125
1126         When "durable" is true, this database implementation does not
1127         support durable commits.
1128
1129 abort
1130 .....
1131
1132 Request object members:
1133
1134     "op": "abort"                      required
1135
1136 Result object members:
1137
1138     (never succeeds)
1139
1140 Semantics:
1141
1142     Aborts the transaction with an error.  This may be useful for
1143     testing.
1144
1145 Errors:
1146
1147     "error": "aborted"
1148
1149         This operation always fails with this error.
1150
1151 comment
1152 .......
1153
1154
1155 Request object members:
1156
1157     "op": "comment"                    required
1158     "comment": <string>                required
1159
1160 Result object members:
1161
1162     none
1163
1164 Semantics:
1165
1166     Provides information to a database administrator on the purpose of
1167     a transaction.  The OVSDB server, for example, adds comments in
1168     transactions that modify the database to the database journal.