SQL Service

The SQL service gives every space its own SQLite database, addressed as the sql service on that space and exercised through tinycloud.sql/* capabilities. It is how structured, relational, queryable data lives inside a sovereign space — the relational counterpart to the key/value KV service.

Role

A Layer 1 service: the protocol does not run a shared database, it hosts a per-space one. Because access is a capability over {spaceId}/sql, an owner can delegate table- or query-scoped read/write to an app or agent without surrendering the rest of the space — the relational analogue of path-scoped KV grants.

Shape

• resource — {spaceId}/sql[/{db}] (a space may hold multiple named databases).
• abilities — tinycloud.sql/{read, select, write, admin, schema} (capabilities.json). read/select are query-only, so a capability can grant read access without writes. The SDK's query/execute/batch are request shapes, not abilities.
• caveats — attenuations can restrict to specific tables/statements.

Mechanics

The node SQL service (tinycloud-core/src/sql/service.rs) runs statements against the space's SQLite file behind a statement authorizer that constrains what a given invocation may do. Writes flow through the same capability verification as any other invocation and are ordered as space events (see epochs-dag). The client side is SQLService / DatabaseHandle (packages/sdk-services/src/sql/), surfaced as db().query/execute/batch and the per-space helper sqlForSpace(spaceId) (see data-apis). Write-class statements are checked against the space's storage quota (402 when full); reads never are. The storage details are in per-space-sql.

Relationships

A service over an space; access granted by capabilities (with table/query caveats) and passed via delegation; its analytical sibling is duckdb; storage and the quota gate are described in per-space-sql; data is exercised by clients through data-apis; the worked example is Listen's conversations database.

Example

tinycloud.sql/query over tinycloud:pkh:eip155:1:0xf39f…2266:applications/sql/xyz.tinycloud.listen/conversations lets an agent read Listen's conversation table — and, if the delegation carried a table caveat, only that table.

Status & drift

Shipped in Node 1.17.3. Note: under the SQLite authorizer, app schemas have been constrained (e.g. PRIMARY-KEY-only patterns observed in Listen) — a node-enforced limitation, not a protocol-level guarantee.

Sources

• tinycloud-node @05c6a93 (Node 1.17.3): tinycloud-core/src/sql/service.rs, capabilities.json (tinycloud.sql/* abilities), tinycloud-node-server/src/routes/mod.rs:2197-2216 (SQL quota gate)
• js-sdk @d43e51ea: packages/sdk-services/src/sql/SQLService.ts, DatabaseHandle.ts