<string>
A JSON string. Any Unicode string is allowed, as specified by RFC
- 4627. Implementations may disallowed null bytes.
+ 4627. Implementations may disallow null bytes.
<id>
A JSON number with an integer value, within a certain range
(currently -2**63...+2**63-1).
-<value>
+<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
-------------
A JSON object with the following members:
"name": <id> required
- "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 value of "tables" is a JSON object whose names
+ are table names and whose values are <table-schema>s.
<table-schema>
A JSON object with the following members:
- "comment": <string> optional
"columns": {<id>: <column-schema>, ...} required
+ "maxRows": <integer> optional
- The "comment" optionally provides information about this table for
- a human reader. The value of "columns" is a JSON object whose
- names are column names and whose values are <column-schema>s.
+ 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:
the database process is stopped and then started again, each
"_version" also changes to a new random value.
+ 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.
+
<column-schema>
A JSON object with the following members:
- "comment": <string> optional
"type": <type> required
"ephemeral": <boolean> optional
- The "comment" optionally provides information about this column
- for a human reader. 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.
+ 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.
<type>
object that describes the type of a database column, with the
following members:
- "key": <atomic-type> required
- "value": <atomic-type> optional
+ "key": <base-type> required
+ "value": <base-type> optional
"min": <integer> optional
"max": <integer> or "unlimited" optional
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
* The JSON-RPC specification for HTTP transport is incomplete.
+We are using TCP port 6632 for the database JSON-RPC connection.
+
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": [] required
- "id": any JSON value except null required
+ "params": [<db-name>] required
+ "id": <nonnull-json-value> 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": <nonnull-json-value> 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
individual operations. Some operations do not produce any
results, in which case the object will have no members.
- - 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
- listed for a specific operation, any operation may result in one
- the following "error"s:
-
- "error": "resources exhausted"
-
- The operation or the transaction requires more resources
- (memory, disk, CPU, etc.) than are currently available to
- the database server.
-
- "error": "syntax error"
-
- The operation is not specified correctly: a required request
- object member is missing, an unknown or unsupported request
- object member is present, the operation attempts to act on a
- table that does not exist, the operation modifies a
- read-only table column, etc.
-
- 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, the object 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. The object may
- also have other members that describe the error in more detail.
- This document does not specify the names or values of these
- 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.
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" 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>).
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>, <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>.
"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:
Notification object members:
"method": "update"
- "params": [<value>, <table-updates>]
+ "params": [<json-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.
+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>.
Request object members:
"method": "monitor_cancel" required
- "params": [<value>] required
- "id": any JSON value except null required
+ "params": [<json-value>] required
+ "id": <nonnull-json-value> required
Response object members:
"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.
+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.
echo
....
"method": "echo" required
"params": JSON array with any contents required
- "id": <value> required
+ "id": <json-value> required
Response object members:
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"]
difference, product, quotient, or remainder, respectively,
of <column> and <value>.
+ Constraints on <column> are ignored when parsing <value>.
+
boolean
string
uuid
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.
+ 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
Semantics:
- Inserts "row" into "table". If "row" does not specify values
- for all the columns in "table", those columns receive default
- values.
+ 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>:
- If "uuid-name" is not supplied, the new row receives a new,
- randomly generated UUID.
+ - "integer" or "real": 0
- If "uuid-name" is supplied, then it is an error if <id> has
- previously appeared as the "uuid-name" in an "insert" operation.
+ - "boolean": false
- 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".
+ - "string": "" (the empty string)
- 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.
+ - "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.
"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"
+
+ 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
......
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
......
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 or an arithmetic operation caused a
- set or map to have duplicate elements.
+ 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
......
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
.......