SqliteMigrator
Runs database migrations for Durable Object SQLite storage that uses Effect SQL.
This module re-exports the shared Migrator loaders and error types, then
provides run and layer helpers that execute ordered migrations through the
current Durable Object SQLite SqlClient. Use it when a Durable
Object needs to create or upgrade its local schema during construction, before
repositories or request handlers use the object storage, or in tests that
exercise Durable Object persistence.
Migrations are recorded in effect_sql_migrations by default and are loaded
using the shared <id>_<name> file or record-key convention. The underlying
storage is scoped to a Durable Object id, so running migrations for one object
does not update any other object instance; run the migrator against the same
DurableObjectStorage-backed client that the object uses for normal queries
so migrations can run in Cloudflare-managed transactions. These SQL
migrations are separate from Cloudflare's Durable Object class migrations, and
the Durable Object must already be configured with SQLite storage before this
module can apply schema changes. Repeated startup runs are expected and are
guarded by the migrations table, but request handling should wait until the
migration layer has finished. This adapter does not currently write SQLite
schema dumps for schemaDirectory.
Constructors
make
Creates a migrator that ensures the migrations table exists, runs pending migrations in a transaction, and optionally dumps the schema after successful migrations.
Signature
declare const make: <RD = never>({ dumpSchema }: { dumpSchema?: (path: string, migrationsTable: string) => Effect.Effect<void, MigrationError, RD>;}) => <R2 = never>({ loader, schemaDirectory, table }: MigratorOptions<R2>) => Effect.Effect<ReadonlyArray<readonly [id: number, name: string]>, MigrationError | SqlError, Client.SqlClient | RD | R2>Errors
MigrationError
Error raised while loading, validating, locking, or running SQL migrations.
Signature
declare class MigrationError extends MigrationError_base<{ readonly _tag: "MigrationError"; readonly cause?: unknown; readonly kind: "BadState" | "ImportError" | "Failed" | "Duplicates" | "Locked"; readonly message: string;}> { constructor(args: { readonly cause?: unknown; readonly kind: "BadState" | "ImportError" | "Failed" | "Duplicates" | "Locked"; readonly message: string; });}Layers
Loaders
fromBabelGlob
Creates a migration loader from a Babel-style glob record, parsing keys such
as _<id>_<name>Js, _<id>_<name>Ts, _<id>_<name>Mjs, or
_<id>_<name>Mts and sorting migrations by id.
Signature
declare const fromBabelGlob: (migrations: Record<string, any>) => LoaderfromFileSystem
Creates a migration loader that reads a directory with FileSystem, imports
files named <id>_<name>.js, <id>_<name>.ts,
<id>_<name>.mjs, or <id>_<name>.mts, and sorts migrations by id.
Details
Requires a Path service appropriate for the migration directory's path
syntax. On Windows, prefer a platform-aware implementation such as
NodePath.layer; the core Path.layer uses POSIX semantics and does not
preserve Windows drive-letter paths.
Signature
declare const fromFileSystem: (directory: string) => Loader<FileSystem | Path>fromGlob
Creates a migration loader from a glob record of dynamic import functions,
parsing files named <id>_<name>.js, <id>_<name>.ts,
<id>_<name>.mjs, or <id>_<name>.mts and sorting migrations by id.
Signature
declare const fromGlob: (migrations: Record<string, () => Promise<any>>) => LoaderfromRecord
Creates a migration loader from a record of migration effects keyed by
<id>_<name>, sorted by migration id.
Signature
declare const fromRecord: (migrations: Record<string, Effect.Effect<void, unknown, Client.SqlClient>>) => LoaderModels
Loader type
Effect that resolves the available migrations for the migrator or fails with a
MigrationError.
Signature
type Loader<R = never> = Effect.Effect<ReadonlyArray<ResolvedMigration>, MigrationError, R>Migration interface
Metadata for a migration recorded in the migrations table, including its id, name, and creation timestamp.
Signature
interface Migration { readonly createdAt: Date; readonly id: number; readonly name: string;}ResolvedMigration type
Tuple produced by a migration loader, containing the migration id, migration name, and an effect that loads the migration implementation.
Signature
type ResolvedMigration = readonly [id: number, name: string, load: Effect.Effect<any, any, Client.SqlClient>]Options
MigratorOptions interface
Options for running SQL migrations, including the migration loader, optional schema dump directory, and migrations table name.
Signature
interface MigratorOptions<R = never> { readonly loader: Loader<R>; readonly schemaDirectory?: string; readonly table?: string;}Running
Runs SQL migrations using the configured SqlClient, returning the migrations that were applied.
Signature
declare const run: <R2 = never>({ loader, schemaDirectory, table }: Migrator.MigratorOptions<R2>) => Effect.Effect<ReadonlyArray<readonly [id: number, name: string]>, Migrator.MigrationError | SqlError, Client.SqlClient | R2>