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/{query, execute, batch, …} (read vs write split so a capability can grant query-only).
• 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).

Relationships

A service over an space; access granted by capabilities (with table/query caveats) and passed via delegation; its analytical sibling is duckdb; 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. 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: tinycloud-core/src/sql/service.rs
• js-sdk: packages/sdk-services/src/sql/SQLService.ts, DatabaseHandle.ts