"comment": <string> optional
"tables": {<id>: <table-schema>, ...} required
- The "name" identifies the database as a whole. The "comment"
- optionally provides more information about the database. The
- value of "tables" is a JSON object whose names are table names and
- whose values are <table-schema>s.
+ 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 "comment" optionally provides more information
+ about the database. The value of "tables" is a JSON object whose
+ names are table names and whose values are <table-schema>s.
<table-schema>
minLength. String length is measured in characters (not bytes
or UTF-16 code units).
- The contraints on <base-type> are "immediate", enforced
- immediately by each operation.
+ If "type" is "uuid", then "refTable", if present, must be the name
+ of a table within this database. If "refTable" is set, the
+ allowed UUIDs are limited to UUIDs for rows in the named table.
+
+ "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>
The database wire protocol consists of the following JSON-RPC methods:
+list_dbs
+........
+
+Request object members:
+
+ "method": "list_dbs" required
+ "params": [] required
+ "id": any JSON value except null 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": [] required
+ "params": [<db-name>] required
"id": any JSON value except null required
Response object members:
"error": null
"id": same "id" as request
-This operation retrieves a <database-schema> that describes the
-hosted database.
+This operation retrieves a <database-schema> that describes hosted
+database <db-name>.
transact
........
Request object members:
- "method": "transact" required
- "params": [<operation>*] required
- "id": any JSON value except null required
+ "method": "transact" required
+ "params": [<db-name>, <operation>*] required
+ "id": any JSON value except null required
Response object members:
"error": null
"id": same "id" as request
-The "params" array for this method consists of zero or more JSON
-objects, each of which represents a single database operation. The
-"Operations" section below describes the valid operations.
+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
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 (e.g. due to I/O errors), then "result" will have one more
-element than "params", with the additional element describing the
-error.
+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". (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.)
If "params" contains one or more "wait" operations, then the
transaction may take an arbitrary amount of time to complete. The
Request object members:
- "method": "monitor" required
- "params": [<value>, <monitor-requests>] required
- "id": any JSON value except null required
+ "method": "monitor" required
+ "params": [<db-name>, <value>, <monitor-requests>] required
+ "id": any JSON value except null required
<monitor-requests> is an object that maps from a table name to a
<monitor-request>.
"id": same "id" as request
This JSON-RPC request enables a client to replicate tables or subsets
-of tables. 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 <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.
Each <monitor-request> describes how to monitor a table:
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.
<set>
- A 2-element JSON array that represents a database set value. The
+ 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.
<named-uuid>
A 2-element JSON array that represents the UUID of a row inserted
- in a previous "insert" operation within the same transaction. The
- first element of the array must be the string "named-uuid" and the
- second element must be the string specified on this "insert"
- operation's "uuid-name" or on a preceding "insert" within the same
- transaction. For example, if this or a previous "insert"
- operation specified a "uuid-name" of "myrow", the following
- <named-uuid> represents the UUID created by that operation:
+ 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"
+ 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"]
- "uuid": 00000000-0000-0000-0000-000000000000
- If "uuid-name" is not supplied, the new row receives a new,
- randomly generated UUID.
-
- If "uuid-name" is supplied, then it is an error if <id> has
- previously appeared as the "uuid-name" in an "insert" operation.
+ The new row receives a new, randomly generated UUID.
- If "uuid-name" is supplied and its <id> previously appeared as the
- "uuid-name" in a "declare" operation, then the new row receives
- the UUID associated with that "uuid-name".
-
- If "uuid-name" is supplied and its <id> has not previously
- appeared as the "uuid-name" in a "declare" operation, then the new
- row also receives a new, randomly generated UUID. This UUID is
- also made available under that name to this operation and later
- operations within the same transaction.
+ 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.
"error": "duplicate uuid-name"
- The same "uuid-name" appeared on an earlier "insert" operation
+ The same "uuid-name" appears on another "insert" operation
within this transaction.
"error": "constraint violation"
This operation always fails with this error.
-declare
-.......
-
-Request object members:
-
- "op": "declare" required
- "uuid-name": <id> required
-
-Result object members:
-
- "uuid": <uuid>
-
-Semantics:
-
- Predeclares a UUID named <id> that may be referenced in later
- operations as ["named-uuid", <id>] or (at most once) in an
- "insert" operation as "uuid-name".
-
- It is an error if <id> has appeared as the "uuid-name" in a prior
- "insert" or "declare" operation within this transaction.
-
- The generated UUID is returned as the "uuid" member of the result.
-
-Errors:
-
- "error": "duplicate uuid-name"
-
- The same "uuid-name" appeared on an earlier "insert" or
- "declare" operation within this transaction.
-
comment
.......
projects / openvswitch / blobdiff