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.

DatabaseEach Durable Object's own, through ctx.storage.sql
BundlerVite, with Cloudflare's Vite plugin
TestsVitest inside workerd, with Cloudflare's Vitest plugin
Examplecloudflare-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:

vite.config.ts
import { cloudflare } from "@cloudflare/vite-plugin";
import { defineConfig } from "vite";
import reylo from "reylo/vite";

export default defineConfig({
  plugins: [reylo(), cloudflare()],
});
  • Import each .sql file by a relative path. A path through an alias, such as a tsconfig paths entry, reaches the Cloudflare plugin's text rule before Reylo.
  • A Worker that only uses Durable Objects needs no nodejs_compat flag.

Local database

The type check reads your schema from a local SQLite file. Point direct_url at it:

.reylo.yaml
direct_url: file:./dev.sqlite

Your migrations create it:

reylo migrate dev
  • Set it in .reylo.yaml, not in .env: Wrangler loads .env into the Worker as secrets.
  • The type check reads one database per package, the one its .reylo.yaml names. 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.yaml names 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 = :id
insert 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 BIGINT column. It can't bind a bigint parameter past 2^53 either, so Reylo rejects one unless it's written to a BIGINT column.

Migrations

A Durable Object runs its migrations on itself. Pass its storage to migrate in its constructor:

board.ts
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 migrate leaves them out.
  • Where reylo migrate deploy would refuse your files, as for a migration the lock doesn't list yet, a file in reylo/migrations that isn't a migration, or a schema.sql changed since the lock, migrate throws 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 migrate turns 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 with on delete cascade or on 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:

wrangler.jsonc
{
  // ...
  // 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:

vitest.config.ts
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.jsonc
{
  // ...
  // 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.

Released under the MIT License. Copyright © 2026 Colin McDonnell.

On this page