# Durable Objects

> How to use Reylo with a Cloudflare Durable Object's SQLite database. The Vite plugin, the schema the type check reads, synchronous queries, migrations the object runs on itself, tests, and the SQLite functions Cloudflare blocks.

Reylo on a Durable Object's database

A Durable Object's database is SQLite, so everything on the [SQLite](https://reylo.dev/sqlite) page holds for it. D1 is on [Cloudflare D1](https://reylo.dev/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](https://github.com/reylosql/reylo/tree/main/examples/cloudflare-workers), a Worker with D1 and a Durable Object that runs locally with no Cloudflare account |

**View the schema behind the examples**

```sql
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`:

```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`](https://reylo.dev/configuration#direct_url) at it:

`.reylo.yaml`:

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

Your [migrations](https://reylo.dev/durable-objects#migrations) create it:

```sh
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:

`worker.ts`:

```ts
import { DurableObject } from "cloudflare:workers";
import createUser from "./create_user.sql";
import getUser from "./get_user.sql";

export class Board extends DurableObject {
  user(id: number) {
    return getUser.runSync(this.ctx.storage.sql, { id });
  }

  // both inserts land, or neither
  addPair() {
    const sql = this.ctx.storage.sql;
    this.ctx.storage.transactionSync(() => {
      createUser.runSync(sql, { name: "Ada" });
      createUser.runSync(sql, { name: "Grace" });
    });
  }
}
```

`get_user.sql`:

```sql
select id, name, email from users where id = :id
```

`create_user.sql`:

```sql
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`:

```ts
import { DurableObject } from "cloudflare:workers";
import { migrate } from "reylo";

export class Board extends DurableObject {
  constructor(ctx: DurableObjectState, env: Env) {
    super(ctx, env);
    migrate(ctx.storage);
  }
}
```

- 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`:

```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`:

```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`:

```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](https://reylo.dev/d1#without-vite). The esbuild plugin puts your migrations in the bundle too.
