GitHub

migrator

API reference for migrator.

Database migrations (Effect's effect/sql/Migrator).

A loader lists the migrations as (id, name, load): load succeeds with the migration, an effect needing SqlClient (or a module whose default is one). make() gives the function that runs the migrations newer than the latest one recorded in the migrations table, in one transaction (except on ClickHouse), recording each::

run = migrator.make()
yield from run(loader=migrator.from_record({"1_create_users": create_users}))

Two runners at once: the second finds the rows already recorded and returns [].

Types

TypeDefinitionDescription
MigrationKindtype MigrationKind = Literal['BadState', 'ImportError', 'Failed', 'Duplicates', 'Locked']
Migrationtype Migration = Effect[object, object, SqlClient]

A migration: an effect run with the client.

ResolvedMigrationtype ResolvedMigration = tuple[int, str, Effect[object, object, SqlClient]]

A migration's id, name, and the effect that loads it.

Loadertype Loader[R = Never] = Effect[Sequence[ResolvedMigration], MigrationError, R]
DumpSchematype DumpSchema[RD] = Callable[[str, str], Effect[None, MigrationError, RD]]

Writes the schema to a path, given the migrations table.

Classes

Functions

make

make[RD = Never](dump_schema=None, transform_writes=_identity) -> Runner[RD]

The migration runner: run(loader=, schema_directory=None, table="effect_sql_migrations") runs the new migrations and succeeds with their ids and names. With schema_directory and migrations run, dump_schema writes <schema_directory>/_schema.sql.

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

ParameterTypeDescription
dump_schemaDumpSchema[RD] | None = None
transform_writesTransformWrites = _identity

Returns Runner[RD]

def make[RD = Never](
    dump_schema: DumpSchema[RD] | None = None, transform_writes: TransformWrites = _identity
) -> Runner[RD]:
    """The migration runner: ``run(loader=, schema_directory=None,
    table="effect_sql_migrations")`` runs the new migrations and succeeds
    with their ids and names. With ``schema_directory`` and migrations run,
    ``dump_schema`` writes ``<schema_directory>/_schema.sql``.

    ``transform_writes`` 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."""

    def run[R2 = Never](
        *,
        loader: Loader[R2],
        schema_directory: str | None = None,
        table: str = "effect_sql_migrations",
    ) -> Effect[list[tuple[int, str]], MigrationError | SqlError, SqlClient | RD | R2]:
        return SqlClient().flat_map(
            lambda sql: _run(sql, dump_schema, transform_writes, loader, schema_directory, table)
        )

    return run

from_record

from_record(migrations) -> Loader

Migrations keyed "<id>_<name>" ("1_create_users"); any other key is skipped.

ParameterTypeDescription
migrationsMapping[str, Migration]

Returns Loader

def from_record(migrations: Mapping[str, Migration]) -> Loader:
    """Migrations keyed ``"<id>_<name>"`` (``"1_create_users"``); any other
    key is skipped."""
    found: list[ResolvedMigration] = []
    for key, migration in migrations.items():
        match = _RECORD_KEY.fullmatch(key)
        if match is not None:
            found.append((int(match[1]), match[2], succeed(migration)))
    return succeed(_sorted(found))