SqliteMigrator
Utilities for applying Effect SQL migrations to SQLite WASM databases.
This module re-exports the shared Migrator loaders and error types, then provides run and layer helpers that execute ordered migrations through the current SQLite WASM SqlClient. Use it when a browser, worker, or test runtime needs to create or upgrade a local SQLite schema before repositories, caches, sync services, or other database-backed services start.
The migrator operates on whichever WASM client is in the environment. With SqliteClient.makeMemory, migrations update an in-memory database, so the resulting schema is transient unless you persist it with the client's export and import operations. With worker-backed OPFS databases, run the migrator against the same worker configuration and OPFS database name used by the rest of the application, and coordinate startup across tabs or workers so only one migrator upgrades a given database at a time. OPFS availability is browser- and origin-dependent, and this adapter does not currently write SQLite schema dumps for schemaDirectory.
Constructors
make
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>) => Loader;fromFileSystem
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.
Signature
declare const fromFileSystem: (directory: string) => Loader<FileSystem>;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>>) => Loader;fromRecord
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>>,
) => Loader;Models
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 for a SQLite WASM database using the shared Migrator implementation and the current SqlClient.
Signature
declare const run: <R>(
options: Migrator.MigratorOptions<R>,
) => Effect.Effect<
ReadonlyArray<readonly [id: number, name: string]>,
SqlError | Migrator.MigrationError,
Client.SqlClient | R
>;
Creates a migrator that ensures the migrations table exists, runs pending migrations in a transaction, and optionally dumps the schema after successful migrations.