<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.
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
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.
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.
+ 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>
"type": <type> required
"ephemeral": <boolean> optional
+ "mutable": <boolean> optional
+
+ The "type" specifies the type of data stored in this column.
- The "type" specifies the type of data stored in this column. If
- "ephemeral" is specified as true, then this column's values are
+ 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.
+ 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>
"minInteger": <integer> optional, integers only
"maxInteger": <integer> optional, integers only
"minReal": <real> optional, reals only
- "maxReal": <real> optional, reals only
+ "maxReal": <real> optional, reals only
"minLength": <integer> optional, strings only
"maxLength": <integer> optional, strings only
"refTable": <id> optional, uuids only
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
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.
+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.
"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 a
-<monitor-request>.
+<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:
"id": same "id" as request
This JSON-RPC request enables a client to replicate tables or subsets
-of tables within database <db-name>. Each <monitor-request> specifies
-a table to be replicated. The JSON-RPC response to the "monitor"
-includes the initial contents of each table. 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.
+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 a table:
+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>:
sent whenever when a row in the table is modified.
The "columns" member specifies the columns whose values are
- monitored. If "columns" is omitted, all columns in the table,
- except for "_uuid", are monitored.
+ 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
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
....
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 string specified as the "uuid-name"
+ 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>
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
+ 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
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
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 / blobdiff