Durable Objects
SQLite driver for a Cloudflare Durable Object's own storage (ctx.storage.sql)
Requirements
- A SQLite-backed Durable Object: its class is listed under
new_sqlite_classesin the Wrangler migrations. nodejs_compat(ornodejs_alsalone) recommended. The driver works without it, butAsyncLocalStorageis how it knows that a statement comes from inside a$transactioncallback; see the originating client.
Configuration
Create the client once, in the object’s constructor, and keep it for the object’s lifetime:
import { DurableObject } from "cloudflare:workers";
import { createClient } from "viborm/durable-object";
import { schema } from "./schema";
export class Workspace extends DurableObject {
readonly db = createClient({ storage: this.ctx.storage, schema });
async pages() {
return this.db.page.findMany({ where: { deletedAt: null } });
}
}
// wrangler.jsonc
{
"durable_objects": {
"bindings": [{ "name": "WORKSPACE", "class_name": "Workspace" }]
},
"migrations": [{ "tag": "v1", "new_sqlite_classes": ["Workspace"] }]
}
Options
| Option | Type | Description |
|---|---|---|
storage |
DurableObjectStorage |
The object’s ctx.storage |
adapter |
DatabaseAdapter |
Optional. Replaces the default adapter (see adapter defaults) |
createClient refuses any other key with a ClientInitializationError that
names it.
One driver per storage
The driver queues the object’s transactions and holds that queue for a
migration, so every client of one storage must share one driver. The entry
does not export the driver class: createDurableObjectDriver(storage) creates
the storage’s driver on its first call and returns that same driver on every
later one, and createClient goes through it. Two clients on one storage
(two schemas, or a client per request) therefore share it. The driver is the
SQL handle’s (storage.sql): a wrapper around ctx.storage that keeps its
sql gets the same driver. A wrapper with its own sql object gets another
one, whose statements do not wait for the first one’s transactions.
An adapter is read when the driver is created. A later call that names
another adapter object for the same storage is refused with a
ClientInitializationError, so create the adapter once and pass that object.
Statements
Statements run synchronously on ctx.storage.sql.exec. A Date is bound as
its ISO string, a boolean as 0/1, a bigint as a number inside ±2^53 and
as its decimal string beyond (SQLite’s INTEGER affinity stores it exactly),
and a Uint8Array as its own bytes. A model read returns a BLOB column as a
Uint8Array; raw SQL ($queryRaw, $queryRawUnsafe) returns the platform’s
value, an ArrayBuffer (wrap it: new Uint8Array(row.avatar)).
A write without RETURNING reports its row count from SQLite’s changes(),
read with one more SELECT changes() on the object’s own SQLite: a
synchronous call, with no I/O. There is no marker to skip it (an
application-side driver used a /*quiet*/ prefix for that). A write with
RETURNING, and every read, needs no such call.
The driver reports no insertId (last_insert_rowid()). VibORM never needs
it: a create reads the generated values back with RETURNING. In raw SQL, add
RETURNING id to the INSERT and read it with $queryRaw, or select
last_insert_rowid() inside the same $transaction.
Constraint failures map to UniqueConstraintError, ForeignKeyError,
NotNullConstraintError and CheckConstraintError, with their table and
columns. The platform’s errors carry no code; VibORM reads the message.
Transactions
A Durable Object refuses BEGIN and SAVEPOINT. The driver never sends them:
$transaction(async (tx) => …)is onectx.storage.transaction(). It commits when the callback resolves and rolls back every write, before and after anyawait, when it rejects.- A nested
$transactioninside it is a nestedctx.storage.transaction(), at any depth. A nested failure rolls back only its own writes. $transaction([...])runs the array in one transaction, in order.isolationLevel: "Serializable"is accepted (the object has one writer); the weaker levels are refused.timeoutrolls the transaction back.maxWaitbounds the wait for the driver’s queue.
Raw SQL cannot open or end a transaction. BEGIN, SAVEPOINT,
ROLLBACK [TO], RELEASE, COMMIT, END and PRAGMA busy_timeout, sent
through $executeRaw, $queryRaw or their Unsafe forms, are refused with
an UnsupportedOperationError before they reach the platform, whose message
points to $transaction. VibORM does not emulate them on top of
ctx.storage.transaction(): write the transaction as a $transaction
callback, nested where the SQL used a SAVEPOINT.
Top-level transactions and statements queue on the driver, so a statement
from another request never runs inside an open transaction. Do not await
non-storage I/O (fetch, timers) inside a transaction body: other requests
wait for it.
The originating client inside a transaction
Inside $transaction(async (tx) => …), use tx. A statement sent through
the client that opened the transaction would wait for that transaction, which
waits for it:
- With
nodejs_compatornodejs_als, the driver knows the statement comes from inside the callback and refuses it at once with aTransactionError(V5001) that says to usetx. - Without either flag, it cannot tell that statement from a concurrent one of
the same request (
Promise.all([db.$transaction(…), db.page.count()])), which must wait its turn. The statement then waits, and fails after 5 seconds withV5002(maxWait), the transaction with it.
// wrangler.jsonc
{ "compatibility_flags": ["nodejs_compat"] }
Migrations
push, apply, down, reset and verify run inside the object, on its
own storage. Run them before the object serves requests, in the
constructor’s blockConcurrencyWhile. With each object’s history kept in the
object itself (Durable Object storage):
import { createMigrationClient } from "viborm/migrations/sqlite";
import { createDurableObjectStorageWriter } from "viborm/migrations/storage/durable-object";
export class Workspace extends DurableObject {
readonly db = createClient({ storage: this.ctx.storage, schema });
constructor(ctx: DurableObjectState, env: Env) {
super(ctx, env);
const migrations = createMigrationClient(this.db, {
storage: createDurableObjectStorageWriter(ctx.storage),
// The history is a table of this same database: name yours.
tables: ["page", "grant", "teamspace"],
});
ctx.blockConcurrencyWhile(() => migrations.apply());
}
}
What the driver declares
The driver declares the Durable Object migration capability:
- Foreign keys. A table recreation switches foreign keys off with
PRAGMA foreign_keys = OFFbetween two transactions. A write still pending in the object turns that pragma into a silent no-op, so the driver first callsctx.storage.sync(). The pragma is read back, and the recreation is refused if it still reads 1. - Platform tables. Cloudflare’s
_cf_*tables (the KV API’s_cf_KV, alarms, metadata) are the platform’s, and refuse PRAGMAs. Introspection never reads them, sopushplans nothing for them. - The migration lock. Where a SQLite migration sends
BEGIN IMMEDIATE,COMMITandROLLBACK, this driver opens and settles a frame: onectx.storage.transaction()kept open until the migration commits or rolls it back. The migration holds the driver’s queue for its whole run, so the application’s other statements through the driver wait for it.
Tables VibORM does not manage
An FTS5 virtual table, or any table you create with raw SQL, must stay outside
the managed set: list your models’ tables in tables. FTS5 works on Durable
Objects; VibORM does not model it.
const migrations = createMigrationClient(db, {
storage: estate,
tables: ["page", "grant", "teamspace"],
});
Limits
- 100 bound values per statement. The driver declares it: VibORM splits a
createManyand other splittable statements to fit, binds aninlist as one value, and refuses a statement that cannot fit withUnsupportedOperationErrorbefore it reaches SQLite. A raw statement ($queryRaw,$executeRawand theirUnsafeforms) with more than 100 values is refused the same way, naming its count and the limit. - 100 KB per statement. A longer statement fails on the platform.
- Integers beyond ±2^53. The platform returns every integer as a
JavaScript number. A
bigInt()field written past ±2^53 is stored exactly; raw SQL reads it rounded. Read such a column as text (CAST(col AS TEXT)) in raw SQL. - Expression depth 100. See adapter defaults.
Adapter defaults
The driver renders with
new SQLiteAdapter({ temporaryObjects: false, deepExpressions: false }):
temporaryObjects: false: the platform refusesCREATE TEMP TABLE. The engine’s batch scratch table is an ordinary table, emptied after each use and left out of introspection.deepExpressions: false: workerd compiles SQLite with an expression depth of 100. A permissions policy over a page tree (a recursive walk of the ancestors, four levels) moves a page past that depth with deep expressions (“Expression tree is too large”); this form keeps it inside, for about 5 to 10 % more CPU.- No
sharedRelationBodies: it shortens statement text, which the 100 KB limit rarely needs here, and costs 30 to 45 % more CPU on such a policy.
Pass adapter to change them, for example to share relation bodies when a
statement reaches 100 KB:
import { SQLiteAdapter } from "viborm/adapters";
const adapter = new SQLiteAdapter({
temporaryObjects: false,
deepExpressions: false,
sharedRelationBodies: true,
});
const db = createClient({ storage: ctx.storage, schema, adapter });
Limitations
- Only available inside a Durable Object, on its own storage.
- SQLite dialect: no
LATERALjoins, limitedFULL OUTER JOIN. - JSON columns are parsed automatically; booleans are stored as
0/1.