Durable Objects
Reylo on a Durable Object's database
A Durable Object's database is SQLite, so everything on the SQLite page holds for it. D1 is on Cloudflare D1.
| Database | Each Durable Object's own, through ctx.storage.sql |
| Bundler | Vite, with Cloudflare's Vite plugin |
| Tests | Vitest inside workerd, with Cloudflare's Vitest plugin |
| Example | cloudflare-workers, a Worker with D1 and a Durable Object that runs locally with no Cloudflare account |
View the schema behind the examples
create table users (
id integer primary key,
name text not null,
email text,
created_at text not null default current_timestamp
) strict;Setup
Add Reylo's Vite plugin beside Cloudflare's:
import { cloudflare } from "@cloudflare/vite-plugin";
import { defineConfig } from "vite";
import reylo from "reylo/vite";
export default defineConfig({
plugins: [reylo(), cloudflare()],
});- Import each
.sqlfile by a relative path. A path through an alias, such as a tsconfigpathsentry, reaches the Cloudflare plugin's text rule before Reylo. - A Worker that only uses Durable Objects needs no
nodejs_compatflag.
Local database
The type check reads your schema from a local SQLite file. Point direct_url at it:
direct_url: file:./dev.sqliteYour migrations create it:
reylo migrate dev- Set it in
.reylo.yaml, not in.env: Wrangler loads.envinto the Worker as secrets. - The type check reads one database per package, the one its
.reylo.yamlnames. An object whose tables match D1's can run D1's migrations. An object with tables of its own goes in a package of its own, whose.reylo.yamlnames a SQLite file made from that object's schema.
Queries
Pass the object's ctx.storage.sql. It's synchronous, so .runSync() works on it:
import { } from "cloudflare:workers";
import from "./create_user.sql";
import from "./get_user.sql";
export class extends {
(: number) {
return .(this..., { });
}
// both inserts land, or neither
() {
const = this...;
this...(() => {
.(, { : "Ada" });
.(, { : "Grace" });
});
}
}select id, name, email from users where id = :idinsert into users (name) values (:name)- Each object is a database of its own: before its tables exist, a query fails with the database's own error.
- The storage rounds an integer past 2^53, so Reylo throws an error rather than return it, even for a
BIGINTcolumn. It can't bind abigintparameter past 2^53 either, so Reylo rejects one unless it's written to aBIGINTcolumn.
Migrations
A Durable Object runs its migrations on itself. Pass its storage to migrate in its constructor:
import { } from "cloudflare:workers";
import { } from "reylo";
export class extends {
constructor(: , : Env) {
super(, );
(.);
}
}- Reylo's Vite or esbuild plugin puts your locked migrations in the bundle, in the lock's order, and a bundle that never calls
migrateleaves them out. - Where
reylo migrate deploywould refuse your files, as for a migration the lock doesn't list yet, a file inreylo/migrationsthat isn't a migration, or aschema.sqlchanged since the lock,migratethrows that refusal and runs nothing. - Each object runs the ones it hasn't run when it starts, each in a transaction, and records them in
__reylo_migrations, so a deploy reaches every object the next time it runs. - An object that ran a migration the bundle lacks, or one edited since, throws and runs nothing.
- A Durable Object always enforces foreign keys, where
reylo migrateturns them off around a migration and checks them before it commits. So a migration that rebuilds a table other tables reference fails and rolls back, or, where they reference it withon delete cascadeoron delete set null, changes their rows. Read each migration that drops a table before you deploy it.
Blocked functions
Durable Objects block some of SQLite's functions, such as json_pretty and power. The type check also runs each query on Cloudflare's SQLite, as Wrangler runs it locally, so a blocked function is a type error. It does so when your package.json has wrangler and its config has a SQLite-backed Durable Object:
{
// ...
// a durable object class with a sqlite database
"migrations": [{ "tag": "v1", "new_sqlite_classes": ["Board"] }]
}Tests
Run the tests inside workerd with Cloudflare's Vitest plugin, and Reylo's beside it:
import { cloudflareTest } from "@cloudflare/vitest-plugin";
import { defineConfig } from "vitest/config";
import reylo from "reylo/vite";
export default defineConfig({
plugins: [
reylo(),
cloudflareTest({ wrangler: { configPath: "./wrangler.jsonc" } }),
],
});Wrangler makes every imported .sql file a text module, and the Vitest plugin applies that rule before Vite runs any plugin. List Wrangler's other text types so that .sql is left to Reylo:
{
// ...
// wrangler's default text types, without .sql
"rules": [{ "type": "Text", "globs": ["**/*.txt", "**/*.html"] }]
}Without Vite
Wrangler's own bundler takes no plugins: build with esbuild and Reylo's esbuild plugin, as on Cloudflare D1. The esbuild plugin puts your migrations in the bundle too.