Migrator.ts
Migrator.ts overview
Section titled “Migrator.ts overview”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.
Since v4.0.0
Exports Grouped by Category
Section titled “Exports Grouped by Category”constructors
Section titled “constructors”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>Since v4.0.0
errors
Section titled “errors”MigrationError (class)
Section titled “MigrationError (class)”Error raised while loading, validating, locking, or running SQL migrations.
Signature
declare class MigrationErrorSince v4.0.0
loaders
Section titled “loaders”fromBabelGlob
Section titled “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>) => LoaderSince v4.0.0
fromFileSystem
Section titled “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>Since v4.0.0
fromGlob
Section titled “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>>) => LoaderSince v4.0.0
fromRecord
Section titled “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>>) => LoaderSince v4.0.0
models
Section titled “models”Loader (type alias)
Section titled “Loader (type alias)”Effect that resolves the available migrations for the migrator or fails with a
MigrationError.
Signature
type Loader<R> = Effect.Effect<ReadonlyArray<ResolvedMigration>, MigrationError, R>Since v4.0.0
Migration (interface)
Section titled “Migration (interface)”Metadata for a migration recorded in the migrations table, including its id, name, and creation timestamp.
Signature
export interface Migration { readonly id: number readonly name: string readonly createdAt: Date}Since v4.0.0
ResolvedMigration (type alias)
Section titled “ResolvedMigration (type alias)”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>]Since v4.0.0
options
Section titled “options”MigratorOptions (interface)
Section titled “MigratorOptions (interface)”Options for running SQL migrations, including the migration loader, optional schema dump directory, and migrations table name.
Signature
export interface MigratorOptions<R = never> { readonly loader: Loader<R> readonly schemaDirectory?: string readonly table?: string}Since v4.0.0