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#
| Type | Definition | Description |
|---|---|---|
MigrationKind | type MigrationKind = Literal['BadState', 'ImportError', 'Failed', 'Duplicates', 'Locked'] | |
Migration | type Migration = Effect[object, object, SqlClient] | A migration: an effect run with the client. |
ResolvedMigration | type ResolvedMigration = tuple[int, str, Effect[object, object, SqlClient]] | A migration's id, name, and the effect that loads it. |
Loader | type Loader[R = Never] = Effect[Sequence[ResolvedMigration], MigrationError, R] | |
DumpSchema | type 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.
| Parameter | Type | Description |
|---|---|---|
dump_schema | DumpSchema[RD] | None = None | |
transform_writes | TransformWrites = _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 runfrom_record#
from_record(migrations) -> LoaderMigrations keyed "<id>_<name>" ("1_create_users"); any other
key is skipped.
| Parameter | Type | Description |
|---|---|---|
migrations | Mapping[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))