<string>
- A JSON string.
+ A JSON string. Any Unicode string is allowed, as specified by RFC
+ 4627. Implementations may disallowed null bytes.
<id>
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
..........
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
......
"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.