1 ===================================================
2 Open vSwitch Configuration Database Specification
3 ===================================================
8 The descriptions below use the following shorthand notations for JSON
9 values. Additional notation is presented later.
13 A JSON string. Any Unicode string is allowed, as specified by RFC
14 4627. Implementations may disallowed null bytes.
18 A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*.
20 <id>s that begin with _ are reserved to the implementation and may
21 not be used by the user.
25 A JSON true or false value.
33 A JSON number with an integer value, within a certain range
34 (currently -2**63...+2**63-1).
43 An Open vSwitch configuration database consists of a set of tables,
44 each of which has a number of columns and zero or more rows. A schema
45 is represented by <database-schema>, as described below.
49 A JSON object with the following members:
52 "comment": <string> optional
53 "tables": {<id>: <table-schema>, ...} required
55 The "name" identifies the database as a whole. The "comment"
56 optionally provides more information about the database. The
57 value of "tables" is a JSON object whose names are table names and
58 whose values are <table-schema>s.
62 A JSON object with the following members:
64 "comment": <string> optional
65 "columns": {<id>: <column-schema>, ...} required
67 The "comment" optionally provides information about this table for
68 a human reader. The value of "columns" is a JSON object whose
69 names are column names and whose values are <column-schema>s.
71 Every table has the following columns whose definitions are not
72 included in the schema:
74 "_uuid": This column, which contains exactly one UUID value,
75 is initialized to a random value by the database engine when
76 it creates a row. It is read-only, and its value never
77 changes during the lifetime of a row.
79 "_version": Like "_uuid", this column contains exactly one
80 UUID value, initialized to a random value by the database
81 engine when it creates a row, and it is read-only. However,
82 its value changes to a new random value whenever any other
83 field in the row changes. Furthermore, its value is
84 ephemeral: when the database is closed and reopened, or when
85 the database process is stopped and then started again, each
86 "_version" also changes to a new random value.
90 A JSON object with the following members:
92 "comment": <string> optional
93 "type": <type> required
94 "ephemeral": <boolean> optional
96 The "comment" optionally provides information about this column
97 for a human reader. The "type" specifies the type of data stored
98 in this column. If "ephemeral" is specified as true, then this
99 column's values are not guaranteed to be durable; they may be lost
100 when the database restarts.
104 The type of a database column. Either an <atomic-type> or a JSON
105 object that describes the type of a database column, with the
108 "key": <atomic-type> required
109 "value": <atomic-type> optional
110 "min": <integer> optional
111 "max": <integer> or "unlimited" optional
113 If "min" or "max" is not specified, each defaults to 1. If "max"
114 is specified as "unlimited", then there is no specified maximum
115 number of elements, although the implementation will enforce some
116 limit. After considering defaults, "min" must be at least 0,
117 "max" must be at least 1, and "max" must be greater than or equal
120 If "min" and "max" are both 1 and "value" is not specified, the
121 type is the scalar type specified by "key".
123 If "min" is not 1 or "max" is not 1, or both, and "value" is not
124 specified, the type is a set of scalar type "key".
126 If "value" is specified, the type is a map from type "key" to type
131 One of the strings "integer", "real", "boolean", "string", or
132 "uuid", representing the specified scalar type.
137 The database wire protocol is implemented in JSON-RPC 1.0. We
138 encourage use of JSON-RPC over stream connections instead of JSON-RPC
139 over HTTP, for these reasons:
141 * JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server
142 protocol, which is a poor match. Thus, JSON-RPC over HTTP
143 requires the client to periodically poll the server to receive
146 * HTTP is more complicated than stream connections and doesn't
147 provide any corresponding advantage.
149 * The JSON-RPC specification for HTTP transport is incomplete.
151 The database wire protocol consists of the following JSON-RPC methods:
156 Request object members:
158 "method": "get_schema" required
159 "params": [] required
160 "id": any JSON value except null required
162 Response object members:
164 "result": <database-schema>
166 "id": same "id" as request
168 This operation retrieves a <database-schema> that describes the
174 Request object members:
176 "method": "transact" required
177 "params": [<operation>*] required
178 "id": any JSON value except null required
180 Response object members:
182 "result": [<object>*]
184 "id": same "id" as request
186 The "params" array for this method consists of zero or more JSON
187 objects, each of which represents a single database operation. The
188 "Operations" section below describes the valid operations.
190 The value of "id" must be unique among all in-flight transactions
191 within the current JSON-RPC session. Otherwise, the server may return
194 The database server executes each of the specified operations in the
195 specified order, except that if an operation fails, then the remaining
196 operations are not executed.
198 The set of operations is executed as a single atomic, consistent,
199 isolated transaction. The transaction is committed only if every
200 operation succeeds. Durability of the commit is not guaranteed unless
201 the "commit" operation, with "durable" set to true, is included in the
202 operation set (see below).
204 Regardless of whether errors occur, the response is always a JSON-RPC
205 response with null "error" and a "result" member that is an array with
206 the same number of elements as "params". Each element of the "result"
207 array corresponds to the same element of the "params" array. The
208 "result" array elements may be interpreted as follows:
210 - A JSON object that does not contain an "error" member indicates
211 that the operation completed successfully. The specific members
212 of the object are specified below in the descriptions of
213 individual operations. Some operations do not produce any
214 results, in which case the object will have no members.
216 - A JSON object that contains an "error" member indicates that the
217 operation completed with an error. The value of the "error"
218 member is a short string, specified in this document, that
219 broadly indicates the class of the error. Besides the ones
220 listed for a specific operation, any operation may result in one
221 the following "error"s:
223 "error": "resources exhausted"
225 The operation or the transaction requires more resources
226 (memory, disk, CPU, etc.) than are currently available to
229 "error": "syntax error"
231 The operation is not specified correctly: a required request
232 object member is missing, an unknown or unsupported request
233 object member is present, the operation attempts to act on a
234 table that does not exist, the operation modifies a
235 read-only table column, etc.
237 Database implementations may use "error" strings not specified
238 in this document to indicate errors that do not fit into any of
239 the specified categories.
241 Optionally, the object may include a "details" member, whose
242 value is a string that describes the error in more detail for
243 the benefit of a human user or administrator. The object may
244 also have other members that describe the error in more detail.
245 This document does not specify the names or values of these
248 - A JSON null value indicates that the operation was not attempted
249 because a prior operation failed.
251 In general, "result" contains some number of successful results,
252 possibly followed by an error, in turn followed by enough JSON null
253 values to match the number of elements in "params". There is one
254 exception: if all of the operations succeed, but the results cannot be
255 committed (e.g. due to I/O errors), then "result" will have one more
256 element than "params", with the additional element describing the
259 If "params" contains one or more "wait" operations, then the
260 transaction may take an arbitrary amount of time to complete. The
261 database implementation must be capable of accepting, executing, and
262 replying to other transactions and other JSON-RPC requests while a
263 transaction or transactions containing "wait" operations are
264 outstanding on the same or different JSON-RPC sessions.
266 The section "Notation for the Wire Protocol" below describes
267 additional notation for use with the wire protocol. After that, the
268 "Operations" section describes each operation.
273 Request object members:
275 "method": "cancel" required
276 "params": [the "id" for an outstanding request] required
279 Response object members:
283 This JSON-RPC notification instructs the database server to
284 immediately complete or cancel the "transact" request whose "id" is
285 the same as the notification's "params" value.
287 If the "transact" request can be completed immediately, then the
288 server sends a response in the form described for "transact", above.
289 Otherwise, the server sends a JSON-RPC error response of the following
294 "id": the request "id" member
296 The "cancel" notification itself has no reply.
301 Request object members:
303 "method": "monitor" required
304 "params": [<value>, <monitor-requests>] required
305 "id": any JSON value except null required
307 <monitor-requests> is an object that maps from a table name to a
310 Each <monitor-request> is an object with the following members:
312 "columns": [<column>*] optional
313 "select": <monitor-select> optional
315 <monitor-select> is an object with the following members:
317 "initial": <boolean> optional
318 "insert": <boolean> optional
319 "delete": <boolean> optional
320 "modify": <boolean> optional
322 Response object members:
324 "result": <table-updates>
326 "id": same "id" as request
328 This JSON-RPC request enables a client to replicate tables or subsets
329 of tables. Each <monitor-request> specifies a table to be replicated.
330 The JSON-RPC response to the "monitor" includes the initial contents
331 of each table. Afterward, when changes to those tables are committed,
332 the changes are automatically sent to the client using the "update"
333 monitor notification. This monitoring persists until the JSON-RPC
334 session terminates or until the client sends a "monitor_cancel"
337 Each <monitor-request> describes how to monitor a table:
339 The circumstances in which an "update" notification is sent for a
340 row within the table are determined by <monitor-select>:
342 If "initial" is omitted or true, every row in the table is
343 sent as part of the reply to the "monitor" request.
345 If "insert" is omitted or true, "update" notifications are
346 sent for rows newly inserted into the table.
348 If "delete" is omitted or true, "update" notifications are
349 sent for rows deleted from the table.
351 If "modify" is omitted or true, "update" notifications are
352 sent whenever when a row in the table is modified.
354 The "columns" member specifies the columns whose values are
355 monitored. If "columns" is omitted, all columns in the table,
356 except for "_uuid", are monitored.
358 The "result" in the JSON-RPC response to the "monitor" request is a
359 <table-updates> object (see below) that contains the contents of the
360 tables for which "initial" rows are selected. If no tables' initial
361 contents are requested, then "result" is an empty object.
366 Notification object members:
369 "params": [<value>, <table-updates>]
372 The <value> in "params" is the same as the value passed as the <value>
373 in "params" for the "monitor" request.
375 <table-updates> is an object that maps from a table name to a
378 A <table-update> is an object that maps from the row's UUID (as a
379 36-byte string) to a <row-update> object.
381 A <row-update> is an object with the following members:
383 "old": <row> present for "delete" and "modify" updates
384 "new": <row> present for "initial", "insert", and "modify" updates
386 This JSON-RPC notification is sent from the server to the client to
387 tell it about changes to a monitored table (or the initial state of a
388 modified table). Each table in which one or more rows has changed (or
389 whose initial view is being presented) is represented in "updates".
390 Each row that has changed (or whose initial view is being presented)
391 is represented in its <table-update> as a member with its name taken
392 from the row's _uuid member. The corresponding value is a
395 The "old" member is present for "delete" and "modify" updates.
396 For "delete" updates, each monitored column is included. For
397 "modify" updates, the prior value of each monitored column whose
398 value has changed is included (monitored columns that have not
399 changed are represented in "new").
401 The "new" member is present for "initial", "insert", and "modify"
402 updates. For "initial" and "insert" updates, each monitored
403 column is included. For "modify" updates, the new value of each
404 monitored column is included.
409 Request object members:
411 "method": "monitor_cancel" required
412 "params": [<value>] required
413 "id": any JSON value except null required
415 Response object members:
419 "id": the request "id" member
421 Cancels the ongoing table monitor request, identified by the <value>
422 in "params" matching the <value> in "params" for an ongoing "monitor"
423 request. No more "update" messages will be sent for this table
429 Request object members:
431 "method": "echo" required
432 "params": JSON array with any contents required
433 "id": <value> required
435 Response object members:
437 "result": same as "params"
439 "id": the request "id" member
441 Both the JSON-RPC client and the server must implement this request.
443 This JSON-RPC request and response can be used to implement connection
444 keepalives, by allowing the server to check that the client is still
448 Notation for the Wire Protocol
449 ------------------------------
453 An <id> that names a table.
457 An <id> that names a table column.
461 A JSON object that describes a table row or a subset of a table
462 row. Each member is the name of a table column paired with the
463 <value> of that column.
467 A JSON value that represents the value of a column in a table row,
468 one of <atom>, a <set>, or a <map>.
472 A JSON value that represents a scalar value for a column, one of
473 <string>, <number>, <boolean>, <uuid>, <named-uuid>.
477 A 2-element JSON array that represents a database set value. The
478 first element of the array must be the string "set" and the second
479 element must be an array of zero or more <atom>s giving the values
480 in the set. All of the <atom>s must have the same type.
484 A 2-element JSON array that represents a database map value. The
485 first element of the array must be the string "map" and the second
486 element must be an array of zero or more <pair>s giving the values
487 in the map. All of the <pair>s must have the same key and value
490 (JSON objects are not used to represent <map> because JSON only
491 allows string names in an object.)
495 A 2-element JSON array that represents a pair within a database
496 map. The first element is an <atom> that represents the key, the
497 second element is an <atom> that represents the value.
501 A 2-element JSON array that represents a UUID. The first element
502 of the array must be the string "uuid" and the second element must
503 be a 36-character string giving the UUID in the format described
504 by RFC 4122. For example, the following <uuid> represents the
505 UUID 550e8400-e29b-41d4-a716-446655440000:
507 ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
511 A 2-element JSON array that represents the UUID of a row inserted
512 in a previous "insert" operation within the same transaction. The
513 first element of the array must be the string "named-uuid" and the
514 second element must be the string specified on this "insert"
515 operation's "uuid-name" or on a preceding "insert" within the same
516 transaction. For example, if this or a previous "insert"
517 operation specified a "uuid-name" of "myrow", the following
518 <named-uuid> represents the UUID created by that operation:
520 ["named-uuid", "myrow"]
522 A <named-uuid> may be used anywhere a <uuid> is valid.
526 A 3-element JSON array of the form [<column>, <function>,
527 <value>] that represents a test on a column value.
529 Except as otherwise specified below, <value> must have the same
532 The meaning depends on the type of <column>:
537 <function> must be "<", "<=", "==", "!=", ">=", ">",
538 "includes", or "excludes".
540 The test is true if the column's value satisfies the
541 relation <function> <value>, e.g. if the column has value
542 1 and <value> is 2, the test is true if <function> is "<",
543 "<=" or "!=", but not otherwise.
545 "includes" is equivalent to "=="; "excludes" is equivalent
552 <function> must be "!=", "==", "includes", or "excludes".
554 If <function> is "==" or "includes", the test is true if
555 the column's value equals <value>. If <function> is "!="
556 or "excludes", the test is inverted.
561 <function> must be "!=", "==", "includes", or "excludes".
563 If <function> is "==", the test is true if the column's
564 value contains exactly the same values (for sets) or pairs
565 (for maps). If <function> is "!=", the test is inverted.
567 If <function> is "includes", the test is true if the
568 column's value contains all of the values (for sets) or
569 pairs (for maps) in <value>. The column's value may also
570 contain other values or pairs.
572 If <function> is "excludes", the test is true if the
573 column's value does not contain any of the values (for
574 sets) or pairs (for maps) in <value>. The column's value
575 may contain other values or pairs not in <value>.
577 If <function> is "includes" or "excludes", then the
578 required type of <value> is slightly relaxed, in that it
579 may have fewer than the minimum number of elements
580 specified by the column's type. If <function> is
581 "excludes", then the required type is additionally relaxed
582 in that <value> may have more than the maximum number of
583 elements specified by the column's type.
587 One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
591 A 3-element JSON array of the form [<column>, <mutator>, <value>]
592 that represents a change to a column value.
594 Except as otherwise specified below, <value> must have the same
597 The meaning depends on the type of <column>:
602 <mutator> must be "+=", "-=", "*=", "/=" or (integer only)
603 "%=". The value of <column> is changed to the sum,
604 difference, product, quotient, or remainder, respectively,
605 of <column> and <value>.
611 No valid <mutator>s are currently defined for these types.
615 Any <mutator> valid for the set's element type may be
616 applied to the set, in which case the mutation is applied
617 to each member of the set individually. <value> must be a
618 scalar value of the same type as the set's element type.
620 If <mutator> is "insert", then each of the values in the
621 set in <value> is added to <column> if it is not already
622 present. The required type of <value> is slightly
623 relaxed, in that it may have fewer than the minimum number
624 of elements specified by the column's type.
626 If <mutator> is "delete", then each of the values in the
627 set in <value> is removed from <column> if it is present
628 there. The required type is slightly relaxed in that
629 <value> may have more or less than the maximum number of
630 elements specified by the column's type.
634 <mutator> must be "insert" or "delete".
636 If <mutator> is "insert", then each of the key-value pairs
637 in the map in <value> is added to <column> if its key is
638 not already present. The required type of <value> is
639 slightly relaxed, in that it may have fewer than the
640 minimum number of elements specified by the column's type.
642 If <mutator> is "delete", then <value> may have the same
643 type as <column> (a map type) or it may be a set whose
644 element type is the same as <column>'s key type:
646 - If <value> is a map, the mutation deletes each
647 key-value pair in <column> whose key and value equal
648 one of the key-value pairs in <value>.
650 - If <value> is a set, the mutation deletes each
651 key-value pair in <column> whose key equals one of
652 the values in <value>.
654 For "delete", <value> may have any number of elements,
655 regardless of restrictions on the number of elements in
660 One of "+=", "-=", "*=", "/=", "%=", "insert", "delete".
665 Each of the available operations is described below.
670 Request object members:
672 "op": "insert" required
673 "table": <table> required
674 "row": <row> required
675 "uuid-name": <id> optional
677 Result object members:
683 Inserts "row" into "table". If "row" does not specify values
684 for all the columns in "table", those columns receive default
687 If "uuid-name" is not supplied, the new row receives a new,
688 randomly generated UUID.
690 If "uuid-name" is supplied, then it is an error if <id> has
691 previously appeared as the "uuid-name" in an "insert" operation.
693 If "uuid-name" is supplied and its <id> previously appeared as the
694 "uuid-name" in a "declare" operation, then the new row receives
695 the UUID associated with that "uuid-name".
697 If "uuid-name" is supplied and its <id> has not previously
698 appeared as the "uuid-name" in a "declare" operation, then the new
699 row also receives a new, randomly generated UUID. This UUID is
700 also made available under that name to this operation and later
701 operations within the same transaction.
703 The UUID for the new row is returned as the "uuid" member of the
708 "error": "duplicate uuid-name"
710 The same "uuid-name" appeared on an earlier "insert" operation
711 within this transaction.
716 Request object members:
718 "op": "select" required
719 "table": <table> required
720 "where": [<condition>*] required
721 "columns": [<column>*] optional
723 Result object members:
729 Searches "table" for rows that match all the conditions specified
730 in "where". If "where" is an empty array, every row in "table" is
733 The "rows" member of the result is an array of objects. Each
734 object corresponds to a matching row, with each column
735 specified in "columns" as a member, the column's name as the
736 member name and its value as the member value. If "columns"
737 is not specified, all the table's columns are included. If
738 two rows of the result have the same values for all included
739 columns, only one copy of that row is included in "rows".
740 Specifying "_uuid" within "columns" will avoid dropping
741 duplicates, since every row has a unique UUID.
743 The ordering of rows within "rows" is unspecified.
748 Request object members:
750 "op": "update" required
751 "table": <table> required
752 "where": [<condition>*] required
753 "row": <row> required
755 Result object members:
761 Updates rows in a table.
763 Searches "table" for rows that match all the conditions
764 specified in "where". For each matching row, changes the
765 value of each column specified in "row" to the value for that
766 column specified in "row".
768 The "_uuid" and "_version" columns of a table may not be directly
769 updated with this operation. Columns designated read-only in the
770 schema also may not be updated.
772 The "count" member of the result specifies the number of rows
778 Request object members:
780 "op": "mutate" required
781 "table": <table> required
782 "where": [<condition>*] required
783 "mutations": [<mutation>*] required
785 Result object members:
791 Mutates rows in a table.
793 Searches "table" for rows that match all the conditions specified
794 in "where". For each matching row, mutates its columns as
795 specified by each <mutation> in "mutations", in the order
798 The "_uuid" and "_version" columns of a table may not be directly
799 modified with this operation. Columns designated read-only in the
800 schema also may not be updated.
802 The "count" member of the result specifies the number of rows
807 "error": "domain error"
809 The result of the mutation is not mathematically defined,
810 e.g. division by zero.
812 "error": "range error"
814 The result of the mutation is not representable within the
815 database's format, e.g. an integer result outside the range
816 INT64_MIN...INT64_MAX or a real result outside the range
819 "error": "constraint violation"
821 The mutation caused the column's value to violate a
822 constraint, e.g. it caused a column to have more or fewer
823 values than are allowed or an arithmetic operation caused a
824 set or map to have duplicate elements.
829 Request object members:
831 "op": "delete" required
832 "table": <table> required
833 "where": [<condition>*] required
835 Result object members:
841 Deletes all the rows from "table" that match all the conditions
842 specified in "where".
844 The "count" member of the result specifies the number of deleted
850 Request object members:
852 "op": "wait" required
853 "timeout": <integer> optional
854 "table": <table> required
855 "where": [<condition>*] required
856 "columns": [<column>*] required
857 "until": "==" or "!=" required
858 "rows": [<row>*] required
860 Result object members:
866 Waits until a condition becomes true.
868 If "until" is "==", checks whether the query on "table" specified
869 by "where" and "columns", which is evaluated in the same way as
870 specified for "select", returns the result set specified by
871 "rows". If it does, then the operation completes successfully.
872 Otherwise, the entire transaction rolls back. It is automatically
873 restarted later, after a change in the database makes it possible
874 for the operation to succeed. The client will not receive a
875 response until the operation permanently succeeds or fails.
877 If "until" is "!=", the sense of the test is negated. That is, as
878 long as the query on "table" specified by "where" and "columns"
879 returns "rows", the transaction will be rolled back and restarted
882 If "timeout" is specified, then the transaction aborts after the
883 specified number of milliseconds. The transaction is guaranteed
884 to be attempted at least once before it aborts. A "timeout" of 0
885 will abort the transaction on the first mismatch.
889 "error": "not supported"
891 One or more of the columns in this table do not support
892 triggers. This error will not occur if "timeout" is 0.
896 The "timeout" was reached before the transaction was able to
902 Request object members:
904 "op": "commit" required
905 "durable": <boolean> required
907 Result object members:
913 If "durable" is specified as true, then the transaction, if it
914 commits, will be stored durably (to disk) before the reply is sent
919 "error": "not supported"
921 When "durable" is true, this database implementation does not
922 support durable commits.
927 Request object members:
929 "op": "abort" required
931 Result object members:
937 Aborts the transaction with an error. This may be useful for
944 This operation always fails with this error.
949 Request object members:
951 "op": "declare" required
952 "uuid-name": <id> required
954 Result object members:
960 Predeclares a UUID named <id> that may be referenced in later
961 operations as ["named-uuid", <id>] or (at most once) in an
962 "insert" operation as "uuid-name".
964 It is an error if <id> has appeared as the "uuid-name" in a prior
965 "insert" or "declare" operation within this transaction.
967 The generated UUID is returned as the "uuid" member of the result.
971 "error": "duplicate uuid-name"
973 The same "uuid-name" appeared on an earlier "insert" or
974 "declare" operation within this transaction.
980 Request object members:
982 "op": "comment" required
983 "comment": <string> required
985 Result object members:
991 Provides information to a database administrator on the purpose of
992 a transaction. The OVSDB server, for example, adds comments in
993 transactions that modify the database to the database journal.