<string>
- A JSON string.
+ A JSON string. Any Unicode string is allowed, as specified by RFC
+ 4627. Implementations may disallowed null bytes.
<id>
A JSON number with an integer value, within a certain range
(currently -2**63...+2**63-1).
+<value>
+
+ Any JSON value.
+
Schema Format
-------------
"columns": {<id>: <column-schema>, ...} required
The "comment" optionally provides information about this table for
- a human reader. The value of "tables" is a JSON object whose
- names are table names and whose values are <column-schema>s.
+ a human reader. 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:
Wire Protocol
-------------
-The database wire protocol is implemented in JSON-RPC 1.0. It
-consists of the following JSON-RPC methods:
+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.
+
+The database wire protocol consists of the following JSON-RPC methods:
get_schema
..........
individual operations. Some operations do not produce any
results, in which case the object will have no members.
- - A JSON object that contains a "error" member indicates that the
+ - A JSON object that contains an "error" member indicates that the
operation completed with an error. The value of the "error"
member is a short string, specified in this document, that
broadly indicates the class of the error. Besides the ones
Request object members:
"method": "cancel" required
- "params": the "id" for an outstanding request required
+ "params": [the "id" for an outstanding request] required
"id": null required
Response object members:
The "cancel" notification itself has no reply.
+monitor
+.......
+
+Request object members:
+
+ "method": "monitor" required
+ "params": [<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>.
+
+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. 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:
+
+ 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. If "columns" is omitted, all columns in the table,
+ except for "_uuid", are monitored.
+
+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": [<value>, <table-updates>]
+ "id": null
+
+The <value> in "params" is the same as the value passed as the <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": [<value>] required
+ "id": any JSON value except null required
+
+Response object members:
+
+ "result": {}
+ "error": null
+ "id": the request "id" member
+
+Cancels the ongoing table monitor request, identified by the <value>
+in "params" matching the <value> in "params" for an ongoing "monitor"
+request. No more "update" messages will be sent for this table
+monitor.
+
+echo
+....
+
+Request object members:
+
+ "method": "echo" required
+ "params": JSON array with any contents required
+ "id": <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
------------------------------
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 a previous "insert"
- operation's "uuid-name". For example, if a previous "insert"
+ 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:
["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>,
"op": "insert" required
"table": <table> required
"row": <row> required
- "uuid-name": <string> optional
+ "uuid-name": <id> optional
Result object members:
for all the columns in "table", those columns receive default
values.
- The new row receives a new, randomly generated UUID, which is
- returned as the "_uuid" member of the result. If "uuid-name"
- is supplied, then the UUID is made available under that name
- to later operations within the same transaction.
+ 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.
+
+ 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.
+
+ The UUID for the new row is returned as the "uuid" member of the
+ result.
+
+Errors:
+
+ "error": "duplicate uuid-name"
+
+ The same "uuid-name" appeared on an earlier "insert" operation
+ within this transaction.
select
......
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 updated.
- Columns designated read-only in the schema also may not be
- updated.
+ 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.
"error": "aborted"
This operation always fails with this error.
+
+declare
+.......
+
+Request object members:
+
+ "op": "declare" required
+ "uuid-name": <id> required
+
+Result object members:
+
+ none
+
+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.
+
+Result object members:
+
+ "uuid": <uuid>
+
+Errors:
+
+ "error": "duplicate uuid-name"
+
+ The same "uuid-name" appeared on an earlier "insert" or
+ "declare" operation within this transaction.
projects / openvswitch / blobdiff