Migrator unstable

Runs SQL migrations with SqlClient.

A migrator loads numbered migration effects, records completed ids in a migrations table, and runs only pending migrations in a transaction. It creates the table when needed, detects duplicate ids, treats concurrent runs as locked, and can dump the schema after successful migrations.

9 exports Since v4.0.0 Source

Constructors

make

unstable

Since v4.0.0

Creates a migrator that ensures the migrations table exists, runs pending migrations in a transaction, and optionally dumps the schema after successful migrations. ClickHouse runs without a transaction and records each migration only after it succeeds.

Details

transformWrites transforms only the effects that create the migrations table and insert into it, for clients such as ClickHouse that run row-less statements differently from queries. Reads of the migrations table and the migrations themselves are not transformed. It defaults to identity.

Signature

declare function make<RD = never>(__namedParameters: {
  dumpSchema?: (path: string, migrationsTable: string) => Effect<void, MigrationError, RD>;
  transformWrites?: <A, E, R>(effect: Effect<A, E, R>) => Effect<A, E, R>;
}): <R2 = never>(__namedParameters: MigratorOptions<R2>) => Effect<readonly Array<readonly [number, string]>, SqlError | MigrationError, SqlClient | RD | R2>

Errors

MigrationError

unstable

Since v4.0.0

Error raised while loading, validating, locking, or running SQL migrations.

Signature

declare class MigrationError extends YieldableError<this> & {
  readonly _tag: "MigrationError";
} & Readonly<{
  readonly _tag: "MigrationError";
  readonly cause?: unknown;
  readonly kind: "Locked" | "BadState" | "ImportError" | "Failed" | "Duplicates";
  readonly message: string;
}> {
  constructor(args: {
    readonly cause?: unknown;
    readonly kind: "Locked" | "BadState" | "ImportError" | "Failed" | "Duplicates";
    readonly message: string;
  });
}

Loaders

fromBabelGlob

unstable

Since v4.0.0

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 function fromBabelGlob(migrations: Record<string, any>): Loader

fromGlob

unstable

Since v4.0.0

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 function fromGlob(migrations: Record<string, () => Promise<any>>): Loader

fromRecord

unstable

Since v4.0.0

Creates a migration loader from a record of migration effects keyed by <id>_<name>, sorted by migration id.

Signature

declare function fromRecord(migrations: Record<string, Effect.Effect<void, unknown, Client.SqlClient>>): Loader

Models

Loader

type unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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 unstable

Since v4.0.0

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;
}