+++ /dev/null
- ===================================================
- Open vSwitch Configuration Database Specification
- ===================================================
-
-Basic Notation
---------------
-
-OVSDB uses JSON, as defined by RFC 4627, for its schema format and its
-wire protocol format. The JSON implementation in Open vSwitch has the
-following limitations:
-
- - Null bytes (\u0000) are not allowed in strings.
-
- - Only UTF-8 encoding is supported. (RFC 4627 also mentions
- UTF-16BE, UTF-16LE, and UTF-32.)
-
- - RFC 4627 says that names within a JSON object should be unique.
- The Open vSwitch JSON parser discards all but the last value
- for a name that is specified more than once.
-
-The descriptions below use the following shorthand notations for JSON
-values. Additional notation is presented later.
-
-<string>
-
- A JSON string. Any Unicode string is allowed, as specified by RFC
- 4627. Implementations may disallow null bytes.
-
-<id>
-
- A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*.
-
- <id>s that begin with _ are reserved to the implementation and may
- not be used by the user.
-
-<version>
-
- A JSON string that contains a version number that matches
- [0-9]+\.[0-9]+\.[0-9]+
-
-<boolean>
-
- A JSON true or false value.
-
-<number>
-
- A JSON number.
-
-<integer>
-
- A JSON number with an integer value, within a certain range
- (currently -2**63...+2**63-1).
-
-<json-value>
-
- Any JSON value.
-
-<nonnull-json-value>
-
- Any JSON value except null.
-
-<error>
-
- A JSON object with the following members:
-
- "error": <string> required
- "details": <string> optional
-
- The value of the "error" member is a short string, specified in
- this document, that broadly indicates the class of the error.
- Most "error" strings are specific to contexts described elsewhere
- in this document, but the following "error" strings may appear in
- any context where an <error> is permitted:
-
- "error": "resources exhausted"
-
- The operation requires more resources (memory, disk, CPU,
- etc.) than are currently available to the database server.
-
- "error": "I/O error"
-
- Problems accessing the disk, network, or other required
- resources prevented the operation from completing.
-
- Database implementations may use "error" strings not specified
- in this document to indicate errors that do not fit into any of
- the specified categories.
-
- Optionally, an <error> may include a "details" member, whose value
- is a string that describes the error in more detail for the
- benefit of a human user or administrator. This document does not
- specify the format or content of the "details" string.
-
- An <error> may also have other members that describe the error in
- more detail. This document does not specify the names or values
- of these members.
-
-Schema Format
--------------
-
-An Open vSwitch configuration database consists of a set of tables,
-each of which has a number of columns and zero or more rows. A schema
-is represented by <database-schema>, as described below.
-
-<database-schema>
-
- A JSON object with the following members:
-
- "name": <id> required
- "version": <version> required
- "cksum": <string> optional
- "tables": {<id>: <table-schema>, ...} required
-
- The "name" identifies the database as a whole. It must be
- provided to most JSON-RPC requests to identify the database being
- operated on. The value of "tables" is a JSON object whose names
- are table names and whose values are <table-schema>s.
-
- The "version" reports the version of the database schema. Because
- this is a recent addition to the schema format, OVSDB permits it
- to be omitted, but future versions of OVSDB will require it to be
- present. Open vSwitch semantics for "version" are described in
- ovs-vswitchd.conf.db(5).
-
- The "cksum" optionally reports an implementation-defined checksum
- for the database schema.
-
-<table-schema>
-
- A JSON object with the following members:
-
- "columns": {<id>: <column-schema>, ...} required
- "maxRows": <integer> optional
- "isRoot": <boolean> optional
- "indexes": [<column-set>*] optional
-
- The value of "columns" is a JSON object whose names are column
- names and whose values are <column-schema>s.
-
- Every table has the following columns whose definitions are not
- included in the schema:
-
- "_uuid": This column, which contains exactly one UUID value,
- is initialized to a random value by the database engine when
- it creates a row. It is read-only, and its value never
- changes during the lifetime of a row.
-
- "_version": Like "_uuid", this column contains exactly one
- UUID value, initialized to a random value by the database
- engine when it creates a row, and it is read-only. However,
- its value changes to a new random value whenever any other
- field in the row changes. Furthermore, its value is
- ephemeral: when the database is closed and reopened, or when
- the database process is stopped and then started again, each
- "_version" also changes to a new random value.
-
- If "isRoot" is omitted or specified as false, then any given row
- in the table may exist only when there is at least one reference
- to it, with refType "strong", from a different row (in the same
- table or a different table). This is a "deferred" action:
- unreferenced rows in the table are deleted just before transaction
- commit. If "isRoot" is specified as true, then rows in the table
- exist independent of any references (they can be thought of as
- part of the "root set" in a garbage collector).
-
- For compatibility with schemas created before "isRoot" was
- introduced, if "isRoot" is omitted or false in every
- <table-schema> in a given <database-schema>, then every table is
- part of the root set.
-
- If "maxRows" is specified, as a positive integer, it limits the
- maximum number of rows that may be present in the table. This is
- a "deferred" constraint, enforced only at transaction commit time
- (see the "transact" request below). If "maxRows" is not
- specified, the size of the table is limited only by the resources
- available to the database server. "maxRows" constraints are
- enforced after unreferenced rows are deleted from tables with a
- false "isRoot".
-
- If "indexes" is specified, it must be an array of zero or more
- <column-set>s. A <column-set> is an array of one or more strings,
- each of which names a column. Each <column-set> is a set of
- columns whose values, taken together within any given row, must be
- unique within the table. This is a "deferred" constraint,
- enforced only at transaction commit time, after unreferenced rows
- are deleted and dangling weak references are removed. Ephemeral
- columns may not be part of indexes.
-
-<column-schema>
-
- A JSON object with the following members:
-
- "type": <type> required
- "ephemeral": <boolean> optional
- "mutable": <boolean> optional
-
- The "type" specifies the type of data stored in this column.
-
- If "ephemeral" is specified as true, then this column's values are
- not guaranteed to be durable; they may be lost when the database
- restarts. A column whose type (either key or value) is a strong
- reference to a table that is not part of the root set is always
- durable, regardless of this value. (Otherwise, restarting the
- database could lose entire rows.)
-
- If "mutable" is specified as false, then this column's values may
- not be modified after they are initially set with the "insert"
- operation.
-
-<type>
-
- The type of a database column. Either an <atomic-type> or a JSON
- object that describes the type of a database column, with the
- following members:
-
- "key": <base-type> required
- "value": <base-type> optional
- "min": <integer> optional
- "max": <integer> or "unlimited" optional
-
- If "min" or "max" is not specified, each defaults to 1. If "max"
- is specified as "unlimited", then there is no specified maximum
- number of elements, although the implementation will enforce some
- limit. After considering defaults, "min" must be exactly 0 or
- exactly 1, "max" must be at least 1, and "max" must be greater
- than or equal to "min".
-
- If "min" and "max" are both 1 and "value" is not specified, the
- type is the scalar type specified by "key".
-
- If "min" is not 1 or "max" is not 1, or both, and "value" is not
- specified, the type is a set of scalar type "key".
-
- If "value" is specified, the type is a map from type "key" to type
- "value".
-
-<base-type>
-
- The type of a key or value in a database column. Either an
- <atomic-type> or a JSON object with the following members:
-
- "type": <atomic-type> required
- "enum": <value> optional
- "minInteger": <integer> optional, integers only
- "maxInteger": <integer> optional, integers only
- "minReal": <real> optional, reals only
- "maxReal": <real> optional, reals only
- "minLength": <integer> optional, strings only
- "maxLength": <integer> optional, strings only
- "refTable": <id> optional, uuids only
- "refType": "strong" or "weak" optional, only with "refTable"
-
- An <atomic-type> by itself is equivalent to a JSON object with a
- single member "type" whose value is the <atomic-type>.
-
- "enum" may be specified as a <value> whose type is a set of one
- or more values specified for the member "type". If "enum" is
- specified, then the valid values of the <base-type> are limited to
- those in the <value>.
-
- "enum" is mutually exclusive with the following constraints.
-
- If "type" is "integer", then "minInteger" or "maxInteger" or both
- may also be specified, restricting the valid integer range. If
- both are specified, then the maxInteger must be greater than or
- equal to minInteger.
-
- If "type" is "real", then "minReal" or "maxReal" or both may also
- be specified, restricting the valid real range. If both are
- specified, then the maxReal must be greater than or equal to
- minReal.
-
- If "type" is "string", then "minLength" and "maxLength" or both
- may be specified, restricting the valid length of value strings.
- If both are specified, then maxLength must be greater than or
- equal to minLength. String length is measured in characters (not
- bytes or UTF-16 code units).
-
- If "type" is "uuid", then "refTable", if present, must be the name
- of a table within this database. If "refTable" is specified, then
- "refType" may also be specified. If "refTable" is set, the effect
- depends on "refType":
-
- - If "refType" is "strong" or if "refType" is omitted, the
- allowed UUIDs are limited to UUIDs for rows in the named
- table.
-
- - If "refType" is "weak", then any UUIDs are allowed, but
- UUIDs that do not correspond to rows in the named table will
- be automatically deleted.
-
- "refTable" constraints are "deferred" constraints: they are
- enforced only at transaction commit time (see the "transact"
- request below). The other contraints on <base-type> are
- "immediate", enforced immediately by each operation.
-
-<atomic-type>
-
- One of the strings "integer", "real", "boolean", "string", or
- "uuid", representing the specified scalar type.
-
-Wire Protocol
--------------
-
-The database wire protocol is implemented in JSON-RPC 1.0. We
-encourage use of JSON-RPC over stream connections instead of JSON-RPC
-over HTTP, for these reasons:
-
- * JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server
- protocol, which is a poor match. Thus, JSON-RPC over HTTP
- requires the client to periodically poll the server to receive
- server requests.
-
- * HTTP is more complicated than stream connections and doesn't
- provide any corresponding advantage.
-
- * The JSON-RPC specification for HTTP transport is incomplete.
-
-We are currently using TCP port 6632 for the database JSON-RPC
-connection, but future versions will switch to using IANA-assigned TCP
-port 6640.
-
-The database wire protocol consists of the following JSON-RPC methods:
-
-list_dbs
-........
-
-Request object members:
-
- "method": "list_dbs" required
- "params": [] required
- "id": <nonnull-json-value> required
-
-Response object members:
-
- "result": [<db-name>, ...]
- "error": null
- "id": same "id" as request
-
-This operation retrieves an array whose elements are <db-name>s
-that name the databases that can be accessed over this JSON-RPC
-connection.
-
-get_schema
-..........
-
-Request object members:
-
- "method": "get_schema" required
- "params": [<db-name>] required
- "id": <nonnull-json-value> required
-
-Response object members:
-
- "result": <database-schema>
- "error": null
- "id": same "id" as request
-
-This operation retrieves a <database-schema> that describes hosted
-database <db-name>.
-
-transact
-........
-
-Request object members:
-
- "method": "transact" required
- "params": [<db-name>, <operation>*] required
- "id": <nonnull-json-value> required
-
-Response object members:
-
- "result": [<object>*]
- "error": null
- "id": same "id" as request
-
-The "params" array for this method consists of a <db-name> that
-identifies the database to which the transaction applies, followed by
-zero or more JSON objects, each of which represents a single database
-operation. The "Operations" section below describes the valid
-operations.
-
-The value of "id" must be unique among all in-flight transactions
-within the current JSON-RPC session. Otherwise, the server may return
-a JSON-RPC error.
-
-The database server executes each of the specified operations in the
-specified order, except that if an operation fails, then the remaining
-operations are not executed.
-
-The set of operations is executed as a single atomic, consistent,
-isolated transaction. The transaction is committed only if every
-operation succeeds. Durability of the commit is not guaranteed unless
-the "commit" operation, with "durable" set to true, is included in the
-operation set (see below).
-
-Regardless of whether errors occur, the response is always a JSON-RPC
-response with null "error" and a "result" member that is an array with
-the same number of elements as "params". Each element of the "result"
-array corresponds to the same element of the "params" array. The
-"result" array elements may be interpreted as follows:
-
- - A JSON object that does not contain an "error" member indicates
- that the operation completed successfully. The specific members
- of the object are specified below in the descriptions of
- individual operations. Some operations do not produce any
- results, in which case the object will have no members.
-
- - An <error>, which indicates that the operation completed with an
- error.
-
- - A JSON null value indicates that the operation was not attempted
- because a prior operation failed.
-
-In general, "result" contains some number of successful results,
-possibly followed by an error, in turn followed by enough JSON null
-values to match the number of elements in "params". There is one
-exception: if all of the operations succeed, but the results cannot be
-committed, then "result" will have one more element than "params",
-with the additional element an <error>. The possible "error" strings
-include at least the following:
-
- "error": "referential integrity violation"
-
- When the commit was attempted, a column's value referenced the
- UUID for a row that did not exist in the table named by the
- column's <base-type> key or value "refTable" that has a
- "refType" of "strong". (This can be caused by inserting a row
- that references a nonexistent row, by deleting a row that is
- still referenced by another row, by specifying the UUID for a
- row in the wrong table, and other ways.)
-
- "error": "constraint violation"
-
- A column with a <base-type> key or value "refTable" whose
- "refType" is "weak" became empty due to deletion(s) caused
- because the rows that it referenced were deleted (or never
- existed, if the column's row was inserted within the
- transaction), and this column is not allowed to be empty
- because its <type> has a "min" of 1.
-
- "error": "constraint violation"
-
- The number of rows in a table exceeds the maximum number
- permitted by the table's "maxRows" value (see <table-schema>).
-
- "error": "constraint violation"
-
- Two or more rows in a table had the same values in the columns
- that comprise an index.
-
- "error": "resources exhausted"
- "error": "I/O error"
-
- As described in the definition of <error> above.
-
-If "params" contains one or more "wait" operations, then the
-transaction may take an arbitrary amount of time to complete. The
-database implementation must be capable of accepting, executing, and
-replying to other transactions and other JSON-RPC requests while a
-transaction or transactions containing "wait" operations are
-outstanding on the same or different JSON-RPC sessions.
-
-The section "Notation for the Wire Protocol" below describes
-additional notation for use with the wire protocol. After that, the
-"Operations" section describes each operation.
-
-cancel
-......
-
-Request object members:
-
- "method": "cancel" required
- "params": [the "id" for an outstanding request] required
- "id": null required
-
-Response object members:
-
- <no response>
-
-This JSON-RPC notification instructs the database server to
-immediately complete or cancel the "transact" request whose "id" is
-the same as the notification's "params" value.
-
-If the "transact" request can be completed immediately, then the
-server sends a response in the form described for "transact", above.
-Otherwise, the server sends a JSON-RPC error response of the following
-form:
-
- "result": null
- "error": "canceled"
- "id": the request "id" member
-
-The "cancel" notification itself has no reply.
-
-monitor
-.......
-
-Request object members:
-
- "method": "monitor" required
- "params": [<db-name>, <json-value>, <monitor-requests>] required
- "id": <nonnull-json-value> required
-
-<monitor-requests> is an object that maps from a table name to an
-array of <monitor-request> objects. For backward compatibility, a
-single <monitor-request> may be used instead of an array; it is
-treated as a single-element array.
-
-Each <monitor-request> is an object with the following members:
-
- "columns": [<column>*] optional
- "select": <monitor-select> optional
-
-<monitor-select> is an object with the following members:
-
- "initial": <boolean> optional
- "insert": <boolean> optional
- "delete": <boolean> optional
- "modify": <boolean> optional
-
-Response object members:
-
- "result": <table-updates>
- "error": null
- "id": same "id" as request
-
-This JSON-RPC request enables a client to replicate tables or subsets
-of tables within database <db-name>. Each element of
-<monitor-requests> specifies a table to be replicated. The JSON-RPC
-response to the "monitor" includes the initial contents of each table,
-unless disabled (see below). Afterward, when changes to those tables
-are committed, the changes are automatically sent to the client using
-the "update" monitor notification. This monitoring persists until the
-JSON-RPC session terminates or until the client sends a
-"monitor_cancel" JSON-RPC request.
-
-Each <monitor-request> describes how to monitor columns in a table:
-
- The circumstances in which an "update" notification is sent for a
- row within the table are determined by <monitor-select>:
-
- If "initial" is omitted or true, every row in the table is
- sent as part of the reply to the "monitor" request.
-
- If "insert" is omitted or true, "update" notifications are
- sent for rows newly inserted into the table.
-
- If "delete" is omitted or true, "update" notifications are
- sent for rows deleted from the table.
-
- If "modify" is omitted or true, "update" notifications are
- sent whenever when a row in the table is modified.
-
- The "columns" member specifies the columns whose values are
- monitored. It must not contain duplicates. If "columns" is
- omitted, all columns in the table, except for "_uuid", are
- monitored.
-
-If there is more than one <monitor-request> in an array of them, then
-each <monitor-request> in the array should specify both "columns" and
-"select", and the "columns" must be non-overlapping sets.
-
-The "result" in the JSON-RPC response to the "monitor" request is a
-<table-updates> object (see below) that contains the contents of the
-tables for which "initial" rows are selected. If no tables' initial
-contents are requested, then "result" is an empty object.
-
-update
-......
-
-Notification object members:
-
- "method": "update"
- "params": [<json-value>, <table-updates>]
- "id": null
-
-The <json-value> in "params" is the same as the value passed as the
-<json-value> in "params" for the "monitor" request.
-
-<table-updates> is an object that maps from a table name to a
-<table-update>.
-
-A <table-update> is an object that maps from the row's UUID (as a
-36-byte string) to a <row-update> object.
-
-A <row-update> is an object with the following members:
-
- "old": <row> present for "delete" and "modify" updates
- "new": <row> present for "initial", "insert", and "modify" updates
-
-This JSON-RPC notification is sent from the server to the client to
-tell it about changes to a monitored table (or the initial state of a
-modified table). Each table in which one or more rows has changed (or
-whose initial view is being presented) is represented in "updates".
-Each row that has changed (or whose initial view is being presented)
-is represented in its <table-update> as a member with its name taken
-from the row's _uuid member. The corresponding value is a
-<row-update>:
-
- The "old" member is present for "delete" and "modify" updates.
- For "delete" updates, each monitored column is included. For
- "modify" updates, the prior value of each monitored column whose
- value has changed is included (monitored columns that have not
- changed are represented in "new").
-
- The "new" member is present for "initial", "insert", and "modify"
- updates. For "initial" and "insert" updates, each monitored
- column is included. For "modify" updates, the new value of each
- monitored column is included.
-
-monitor_cancel
-..............
-
-Request object members:
-
- "method": "monitor_cancel" required
- "params": [<json-value>] required
- "id": <nonnull-json-value> required
-
-Response object members:
-
- "result": {}
- "error": null
- "id": the request "id" member
-
-Cancels the ongoing table monitor request, identified by the
-<json-value> in "params" matching the <json-value> in "params" for an
-ongoing "monitor" request. No more "update" messages will be sent for
-this table monitor.
-
-lock operations
-...............
-
-Request object members:
-
- "method": "lock", "steal", or "unlock" required
- "params": [<id>] required
- "id": <nonnull-json-value> required
-
-Response object members:
-
- "result": {"locked": <boolean>} for "lock"
- "result": {"locked": true} for "steal"
- "result": {} for "unlock"
- "error": null
- "id": same "id" as request
-
-Performs an operation on a "lock" object. The database server
-supports an arbitrary number of locks, each of which is identified by
-a client-defined id (given in "params"). At any given time, each lock
-may have at most one owner.
-
-The locking operation depends on "method":
-
- - "lock": The database will assign this client ownership of the
- lock as soon as it becomes available. When multiple clients
- request the same lock, they will receive it in first-come, first
- served order.
-
- - "steal": The database immediately assigns this client ownership
- of the lock. If there is an existing owner, it loses ownership.
-
- - "unlock": If the client owns the lock, releases it. If the
- client is waiting to obtain the lock, cancels the request and
- stops waiting.
-
- (Closing or otherwise disconnecting a database client connection
- unlocks all of its locks.)
-
-For any given lock, the client must alternate "lock" or "steal"
-operations with "unlock" operations. That is, if the previous
-operation on a lock was "lock" or "steal", it must be followed by an
-"unlock" operation, and vice versa.
-
-For a "lock" operation, the "locked" member in the response object is
-true if the lock has already been acquired, false if another client
-holds the lock and the client's request for it was queued. In the
-latter case, the client will be notified later with a "locked" message
-when acquisition succeeds.
-
-These requests complete and send a response quickly, without waiting.
-The "locked" and "stolen" notifications (see below) report
-asynchronous changes to ownership.
-
-The scope of a lock is a database server, not a database hosted by
-that server. A naming convention, such as "<db-name>__<lock-name>",
-can effectively limit the scope of a lock to a particular database.
-
-locked
-......
-
-Notification object members:
-
- "method": "locked"
- "params": [<id>]
- "id": null
-
-Notifies the client that a "lock" operation that it previously
-requested has succeeded. The client now owns the lock named in
-"params".
-
-The database server sends this notification after the reply to the
-corresponding "lock" request (but only if the "locked" member of the
-response was false), and before the reply to the client's subsequent
-"unlock" request.
-
-stolen
-......
-
-Notification object members:
-
- "method": "stolen"
- "params": [<id>]
- "id": null
-
-Notifies the client that owns a lock that another database client has
-stolen ownership of the lock. The client no longer owns the lock
-named in "params". The client must still issue an "unlock" request
-before performing any subsequent "lock" or "steal" operation on the
-lock.
-
-If the client originally obtained the lock through a "lock" request,
-then it will automatically regain the lock later after the client that
-stole it releases it. (The database server will send the client a
-"locked" notification at that point to let it know.)
-
-If the client originally obtained the lock through a "steal" request,
-the database server won't automatically reassign it ownership of the
-lock when it later becomes available. To regain ownership, the client
-must "unlock" and then "lock" or "steal" the lock again.
-
-echo
-....
-
-Request object members:
-
- "method": "echo" required
- "params": JSON array with any contents required
- "id": <json-value> required
-
-Response object members:
-
- "result": same as "params"
- "error": null
- "id": the request "id" member
-
-Both the JSON-RPC client and the server must implement this request.
-
-This JSON-RPC request and response can be used to implement connection
-keepalives, by allowing the server to check that the client is still
-there or vice versa.
-
-
-Notation for the Wire Protocol
-------------------------------
-
-<db-name>
-
- An <id> that names a database. The valid <db-name>s can be
- obtained using a "list-db" request. The <db-name> is taken from
- the "name" member of <database-schema>.
-
-<table>
-
- An <id> that names a table.
-
-<column>
-
- An <id> that names a table column.
-
-<row>
-
- A JSON object that describes a table row or a subset of a table
- row. Each member is the name of a table column paired with the
- <value> of that column.
-
-<value>
-
- A JSON value that represents the value of a column in a table row,
- one of <atom>, a <set>, or a <map>.
-
-<atom>
-
- A JSON value that represents a scalar value for a column, one of
- <string>, <number>, <boolean>, <uuid>, <named-uuid>.
-
-<set>
-
- Either an <atom>, representing a set with exactly one element, or
- a 2-element JSON array that represents a database set value. The
- first element of the array must be the string "set" and the second
- element must be an array of zero or more <atom>s giving the values
- in the set. All of the <atom>s must have the same type.
-
-<map>
-
- A 2-element JSON array that represents a database map value. The
- first element of the array must be the string "map" and the second
- element must be an array of zero or more <pair>s giving the values
- in the map. All of the <pair>s must have the same key and value
- types.
-
- (JSON objects are not used to represent <map> because JSON only
- allows string names in an object.)
-
-<pair>
-
- A 2-element JSON array that represents a pair within a database
- map. The first element is an <atom> that represents the key, the
- second element is an <atom> that represents the value.
-
-<uuid>
-
- A 2-element JSON array that represents a UUID. The first element
- of the array must be the string "uuid" and the second element must
- be a 36-character string giving the UUID in the format described
- by RFC 4122. For example, the following <uuid> represents the
- UUID 550e8400-e29b-41d4-a716-446655440000:
-
- ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
-
-<named-uuid>
-
- A 2-element JSON array that represents the UUID of a row inserted
- in an "insert" operation within the same transaction. The first
- element of the array must be the string "named-uuid" and the
- second element should be the <id> specified as the "uuid-name"
- for an "insert" operation within the same transaction. For
- example, if an "insert" operation within this transaction
- specifies a "uuid-name" of "myrow", the following <named-uuid>
- represents the UUID created by that operation:
-
- ["named-uuid", "myrow"]
-
- A <named-uuid> may be used anywhere a <uuid> is valid.
-
-<condition>
-
- A 3-element JSON array of the form [<column>, <function>,
- <value>] that represents a test on a column value.
-
- Except as otherwise specified below, <value> must have the same
- type as <column>.
-
- The meaning depends on the type of <column>:
-
- integer
- real
-
- <function> must be "<", "<=", "==", "!=", ">=", ">",
- "includes", or "excludes".
-
- The test is true if the column's value satisfies the
- relation <function> <value>, e.g. if the column has value
- 1 and <value> is 2, the test is true if <function> is "<",
- "<=" or "!=", but not otherwise.
-
- "includes" is equivalent to "=="; "excludes" is equivalent
- to "!=".
-
- boolean
- string
- uuid
-
- <function> must be "!=", "==", "includes", or "excludes".
-
- If <function> is "==" or "includes", the test is true if
- the column's value equals <value>. If <function> is "!="
- or "excludes", the test is inverted.
-
- set
- map
-
- <function> must be "!=", "==", "includes", or "excludes".
-
- If <function> is "==", the test is true if the column's
- value contains exactly the same values (for sets) or pairs
- (for maps). If <function> is "!=", the test is inverted.
-
- If <function> is "includes", the test is true if the
- column's value contains all of the values (for sets) or
- pairs (for maps) in <value>. The column's value may also
- contain other values or pairs.
-
- If <function> is "excludes", the test is true if the
- column's value does not contain any of the values (for
- sets) or pairs (for maps) in <value>. The column's value
- may contain other values or pairs not in <value>.
-
- If <function> is "includes" or "excludes", then the
- required type of <value> is slightly relaxed, in that it
- may have fewer than the minimum number of elements
- specified by the column's type. If <function> is
- "excludes", then the required type is additionally relaxed
- in that <value> may have more than the maximum number of
- elements specified by the column's type.
-
-<function>
-
- One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
-
-<mutation>
-
- A 3-element JSON array of the form [<column>, <mutator>, <value>]
- that represents a change to a column value.
-
- Except as otherwise specified below, <value> must have the same
- type as <column>.
-
- The meaning depends on the type of <column>:
-
- integer
- real
-
- <mutator> must be "+=", "-=", "*=", "/=" or (integer only)
- "%=". The value of <column> is changed to the sum,
- difference, product, quotient, or remainder, respectively,
- of <column> and <value>.
-
- Constraints on <column> are ignored when parsing <value>.
-
- boolean
- string
- uuid
-
- No valid <mutator>s are currently defined for these types.
-
- set
-
- Any <mutator> valid for the set's element type may be
- applied to the set, in which case the mutation is applied
- to each member of the set individually. <value> must be a
- scalar value of the same type as the set's element type,
- except that contraints are ignored.
-
- If <mutator> is "insert", then each of the values in the
- set in <value> is added to <column> if it is not already
- present. The required type of <value> is slightly
- relaxed, in that it may have fewer than the minimum number
- of elements specified by the column's type.
-
- If <mutator> is "delete", then each of the values in the
- set in <value> is removed from <column> if it is present
- there. The required type is slightly relaxed in that
- <value> may have more or less than the maximum number of
- elements specified by the column's type.
-
- map
-
- <mutator> must be "insert" or "delete".
-
- If <mutator> is "insert", then each of the key-value pairs
- in the map in <value> is added to <column> only if its key
- is not already present. The required type of <value> is
- slightly relaxed, in that it may have fewer than the
- minimum number of elements specified by the column's type.
-
- If <mutator> is "delete", then <value> may have the same
- type as <column> (a map type) or it may be a set whose
- element type is the same as <column>'s key type:
-
- - If <value> is a map, the mutation deletes each
- key-value pair in <column> whose key and value equal
- one of the key-value pairs in <value>.
-
- - If <value> is a set, the mutation deletes each
- key-value pair in <column> whose key equals one of
- the values in <value>.
-
- For "delete", <value> may have any number of elements,
- regardless of restrictions on the number of elements in
- <column>.
-
-<mutator>
-
- One of "+=", "-=", "*=", "/=", "%=", "insert", "delete".
-
-Operations
-----------
-
-Each of the available operations is described below.
-
-insert
-......
-
-Request object members:
-
- "op": "insert" required
- "table": <table> required
- "row": <row> required
- "uuid-name": <id> optional
-
-Result object members:
-
- "uuid": <uuid>
-
-Semantics:
-
- Inserts "row" into "table".
-
- If "row" does not specify values for all the columns in "table",
- those columns receive default values. The default value for a
- column depends on its type. The default for a column whose <type>
- specifies a "min" of 0 is an empty set or empty map. Otherwise,
- the default is a single value or a single key-value pair, whose
- value(s) depend on its <atomic-type>:
-
- - "integer" or "real": 0
-
- - "boolean": false
-
- - "string": "" (the empty string)
-
- - "uuid": 00000000-0000-0000-0000-000000000000
-
- The new row receives a new, randomly generated UUID.
-
- If "uuid-name" is supplied, then it is an error if <id> is not
- unique among the "uuid-name"s supplied on all the "insert"
- operations within this transaction.
-
- The UUID for the new row is returned as the "uuid" member of the
- result.
-
-Errors:
-
- "error": "duplicate uuid-name"
-
- The same "uuid-name" appears on another "insert" operation
- within this transaction.
-
- "error": "constraint violation"
-
- One of the values in "row" does not satisfy the immediate
- constraints for its column's <base-type>. This error will
- occur for columns that are not explicitly set by "row" if the
- default value does not satisfy the column's constraints.
-
-select
-......
-
-Request object members:
-
- "op": "select" required
- "table": <table> required
- "where": [<condition>*] required
- "columns": [<column>*] optional
-
-Result object members:
-
- "rows": [<row>*]
-
-Semantics:
-
- Searches "table" for rows that match all the conditions specified
- in "where". If "where" is an empty array, every row in "table" is
- selected.
-
- The "rows" member of the result is an array of objects. Each
- object corresponds to a matching row, with each column
- specified in "columns" as a member, the column's name as the
- member name and its value as the member value. If "columns"
- is not specified, all the table's columns are included. If
- two rows of the result have the same values for all included
- columns, only one copy of that row is included in "rows".
- Specifying "_uuid" within "columns" will avoid dropping
- duplicates, since every row has a unique UUID.
-
- The ordering of rows within "rows" is unspecified.
-
-update
-......
-
-Request object members:
-
- "op": "update" required
- "table": <table> required
- "where": [<condition>*] required
- "row": <row> required
-
-Result object members:
-
- "count": <integer>
-
-Semantics:
-
- Updates rows in a table.
-
- Searches "table" for rows that match all the conditions
- specified in "where". For each matching row, changes the
- value of each column specified in "row" to the value for that
- column specified in "row".
-
- The "_uuid" and "_version" columns of a table may not be directly
- updated with this operation. Columns designated read-only in the
- schema also may not be updated.
-
- The "count" member of the result specifies the number of rows
- that matched.
-
-Errors:
-
- "error": "constraint violation"
-
- One of the values in "row" does not satisfy the immediate
- constraints for its column's <base-type>.
-mutate
-......
-
-Request object members:
-
- "op": "mutate" required
- "table": <table> required
- "where": [<condition>*] required
- "mutations": [<mutation>*] required
-
-Result object members:
-
- "count": <integer>
-
-Semantics:
-
- Mutates rows in a table.
-
- Searches "table" for rows that match all the conditions specified
- in "where". For each matching row, mutates its columns as
- specified by each <mutation> in "mutations", in the order
- specified.
-
- The "_uuid" and "_version" columns of a table may not be directly
- modified with this operation. Columns designated read-only in the
- schema also may not be updated.
-
- The "count" member of the result specifies the number of rows
- that matched.
-
-Errors:
-
- "error": "domain error"
-
- The result of the mutation is not mathematically defined,
- e.g. division by zero.
-
- "error": "range error"
-
- The result of the mutation is not representable within the
- database's format, e.g. an integer result outside the range
- INT64_MIN...INT64_MAX or a real result outside the range
- -DBL_MAX...DBL_MAX.
-
- "error": "constraint violation"
-
- The mutation caused the column's value to violate a
- constraint, e.g. it caused a column to have more or fewer
- values than are allowed, an arithmetic operation caused a set
- or map to have duplicate elements, or it violated a constraint
- specified by a column's <base-type>.
-
-delete
-......
-
-Request object members:
-
- "op": "delete" required
- "table": <table> required
- "where": [<condition>*] required
-
-Result object members:
-
- "count": <integer>
-
-Semantics:
-
- Deletes all the rows from "table" that match all the conditions
- specified in "where".
-
- The "count" member of the result specifies the number of deleted
- rows.
-
-wait
-....
-
-Request object members:
-
- "op": "wait" required
- "timeout": <integer> optional
- "table": <table> required
- "where": [<condition>*] required
- "columns": [<column>*] required
- "until": "==" or "!=" required
- "rows": [<row>*] required
-
-Result object members:
-
- none
-
-Semantics:
-
- Waits until a condition becomes true.
-
- If "until" is "==", checks whether the query on "table" specified
- by "where" and "columns", which is evaluated in the same way as
- specified for "select", returns the result set specified by
- "rows". If it does, then the operation completes successfully.
- Otherwise, the entire transaction rolls back. It is automatically
- restarted later, after a change in the database makes it possible
- for the operation to succeed. The client will not receive a
- response until the operation permanently succeeds or fails.
-
- If "until" is "!=", the sense of the test is negated. That is, as
- long as the query on "table" specified by "where" and "columns"
- returns "rows", the transaction will be rolled back and restarted
- later.
-
- If "timeout" is specified, then the transaction aborts after the
- specified number of milliseconds. The transaction is guaranteed
- to be attempted at least once before it aborts. A "timeout" of 0
- will abort the transaction on the first mismatch.
-
-Errors:
-
- "error": "not supported"
-
- One or more of the columns in this table do not support
- triggers. This error will not occur if "timeout" is 0.
-
- "error": "timed out"
-
- The "timeout" was reached before the transaction was able to
- complete.
-
-commit
-......
-
-Request object members:
-
- "op": "commit" required
- "durable": <boolean> required
-
-Result object members:
-
- none
-
-Semantics:
-
- If "durable" is specified as true, then the transaction, if it
- commits, will be stored durably (to disk) before the reply is sent
- to the client.
-
-Errors:
-
- "error": "not supported"
-
- When "durable" is true, this database implementation does not
- support durable commits.
-
-abort
-.....
-
-Request object members:
-
- "op": "abort" required
-
-Result object members:
-
- (never succeeds)
-
-Semantics:
-
- Aborts the transaction with an error. This may be useful for
- testing.
-
-Errors:
-
- "error": "aborted"
-
- This operation always fails with this error.
-
-comment
-.......
-
-
-Request object members:
-
- "op": "comment" required
- "comment": <string> required
-
-Result object members:
-
- none
-
-Semantics:
-
- Provides information to a database administrator on the purpose of
- a transaction. The OVSDB server, for example, adds comments in
- transactions that modify the database to the database journal.
-
-assert
-......
-
-Request object members:
-
- "op": "assert" required
- "lock": <id> required
-
-Result object members:
-
- none
-
-Semantics:
-
- If the client does not own the lock named <string>, aborts the
- transaction.
-
-Errors:
-
- "error": "not owner"
-
- The client does not own the named lock.
git://git.onelab.eu / sliver-openvswitch.git / commitdiff