Coverage for downtify/db/migrations/runner.py: 100%
64 statements
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
« prev ^ index » next coverage.py v7.17.4, created at 2026-11-21 22:18 +0000
1"""Discover and apply versioned PostgreSQL migrations.
3Each migration is a module named ``NNNN_name`` (four digits, then a lowercase
4name) inside the versions package. It defines ``up(conn)``, which receives a
5``Connection`` and performs its DDL/DML. ``run_migrations`` applies every
6pending migration in one transaction, guarded by a PostgreSQL advisory lock
7so concurrent starters queue up instead of racing.
9SQLite schemas stay owned by each store's ``_init_db``; this module does
10nothing on SQLite.
11"""
13from __future__ import annotations
15import importlib
16import pkgutil
17import re
18from collections.abc import Callable
19from dataclasses import dataclass
21from downtify.db.config import Dialect
22from downtify.db.core import Connection, Database
24DEFAULT_PACKAGE = 'downtify.db.migrations.versions'
26_MODULE_PATTERN = re.compile(r'^(\d{4})_[a-z0-9_]+$')
27_LOCK_SQL = "select pg_advisory_xact_lock(hashtext('downtify_migrations'))"
28_CREATE_TABLE_SQL = """
29create table if not exists schema_migrations (
30 version integer primary key,
31 name text not null,
32 applied_at timestamptz not null default now()
33)
34"""
37@dataclass(frozen=True)
38class Migration:
39 version: int
40 name: str
41 up: Callable[[Connection], None]
44def discover(package: str = DEFAULT_PACKAGE) -> list[Migration]:
45 """Import the migration modules in ``package``, sorted by version."""
46 pkg = importlib.import_module(package)
47 found: list[Migration] = []
48 seen: dict[int, str] = {}
49 for info in pkgutil.iter_modules(pkg.__path__):
50 match = _MODULE_PATTERN.match(info.name)
51 if match is None:
52 continue
53 module_name = f'{package}.{info.name}'
54 module = importlib.import_module(module_name)
55 up = getattr(module, 'up', None)
56 if not callable(up):
57 raise RuntimeError(f'migration {module_name} has no up(conn)')
58 version = int(match.group(1))
59 if version in seen:
60 raise RuntimeError(
61 f'duplicate migration version {version:04d}: '
62 f'{seen[version]} and {info.name}'
63 )
64 seen[version] = info.name
65 found.append(Migration(version=version, name=info.name, up=up))
66 found.sort(key=lambda migration: migration.version)
67 return found
70def _applied(conn: Connection) -> list[int]:
71 exists = conn.execute(
72 "select to_regclass('schema_migrations') is not null"
73 ).fetchone()[0]
74 if not exists:
75 return []
76 rows = conn.execute(
77 'select version from schema_migrations order by version'
78 ).fetchall()
79 return [row[0] for row in rows]
82def applied_versions(db: Database) -> list[int]:
83 """Versions recorded in ``schema_migrations``; empty if none or SQLite."""
84 if db.dialect is Dialect.SQLITE:
85 return []
86 with db.connect() as conn:
87 return _applied(conn)
90def run_migrations(db: Database, package: str = DEFAULT_PACKAGE) -> list[int]:
91 """Apply pending migrations; return the versions applied by this call.
93 All pending migrations run in one transaction. Any failure rolls the
94 whole run back, so nothing is partially applied or recorded.
95 """
96 if db.dialect is Dialect.SQLITE:
97 return []
98 migrations = discover(package)
99 applied: list[int] = []
100 with db.transaction() as conn:
101 conn.execute(_LOCK_SQL)
102 conn.execute(_CREATE_TABLE_SQL)
103 done = set(_applied(conn))
104 for migration in migrations:
105 if migration.version in done:
106 continue
107 migration.up(conn)
108 conn.execute(
109 'insert into schema_migrations (version, name) values (?, ?)',
110 (migration.version, migration.name),
111 )
112 applied.append(migration.version)
113 return applied