SqliteMigrator

Utilities for applying Effect SQL migrations to React Native SQLite 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 React Native SQLite SqlClient. Use it when a mobile app needs to bring its on-device database schema up to date during startup, before opening repositories or sync services, or in integration tests that create app-local database files.

React Native SQLite databases are scoped by the client configuration, so the migrator should be run with the same filename, location, and encryption key as the rest of the application. Migrations run through the package's single serialized connection; by default statements use the synchronous driver API and can block the JS thread, so long migration sets may want to run under SqliteClient.withAsyncQuery. Mobile upgrades can be interrupted by app suspension or process death, so keep migrations transaction-aware and avoid assuming a fresh database on every launch.

12 exports Added in v4.0.0 Source

Constructors

make

Added in 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

Added in 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

Added in v4.0.0 Source

Creates a layer that runs the configured React Native SQLite migrations during layer construction and provides no services.

Signature

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

Loaders

fromBabelGlob

Added in 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

Added in 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

Added in 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

Added in 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

Added in 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

Added in 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

Added in 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

Added in 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

Added in v4.0.0 Source

Runs SQL migrations for a React Native SQLite 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>