PgMigrator unstable

Runs database migrations for PostgreSQL projects that use Effect SQL.

This module reuses the shared SQL migrator and connects it to PostgreSQL. It exposes the common migration helpers and adds run and layer functions that apply pending migration files with the current SQL client. When schema dumps are requested, it uses pg_dump and the usual process and filesystem services.

12 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.

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

unstable

Since v4.0.0

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

layer

unstable

Since v4.0.0

Creates a layer that runs PostgreSQL migrations during layer construction, including pg_dump-based schema dump support when requested.

Signature

declare function layer<R>(options: MigratorOptions<R>): Layer<never, SqlError | MigrationError, PgClient | SqlClient | ChildProcessSpawner | FileSystem | Path | R>

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

fromFileSystem

unstable

Since v4.0.0

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

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

Running

run

unstable

Since v4.0.0

Runs PostgreSQL SQL migrations using the configured clients. Schema dumps use pg_dump and require child process, filesystem, and path services.

Details

pg_dump connects with the same resolved settings as PgClient: URL and explicit fields, Unix socket path, user, database, application_name, options, and connect timeout. The password is passed through PGPASSWORD and the inherited environment is not used.

TLS maps to libpq as follows: no TLS uses sslmode=disable, rejectUnauthorized: false uses require, and verified TLS uses verify-full with the client's trusted CAs (ssl.ca, or Node's default CAs) written to a temporary sslrootcert file. A PEM ssl.cert / ssl.key pair is passed as sslcert / sslkey.

URL sslmode=prefer / allow also uses verify-full, because the client verifies the certificate whenever the server accepts TLS and libpq cannot verify while keeping a plaintext fallback. Dumps from servers that refuse TLS therefore fail, even though the client falls back to plaintext.

Node's default CAs require tls.getCACertificates (Node.js 22.15 / 23.10 or later). On older runtimes, verified TLS dumps require an explicit ssl.ca.

The dump fails, and the migrator logs the error, for custom stream connections, TLS over Unix sockets, socket paths not named .s.PGSQL.<port>, a servername different from the host, and other ssl options.

Signature

declare const run: <R2 = never>(options: Migrator.MigratorOptions<R2>) => Effect.Effect<ReadonlyArray<readonly [id: number, name: string]>, Migrator.MigrationError | SqlError, SqlClient | PgClient | ChildProcessSpawner.ChildProcessSpawner | FileSystem.FileSystem | Path.Path | R2>