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

1"""Discover and apply versioned PostgreSQL migrations. 

2 

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. 

8 

9SQLite schemas stay owned by each store's ``_init_db``; this module does 

10nothing on SQLite. 

11""" 

12 

13from __future__ import annotations 

14 

15import importlib 

16import pkgutil 

17import re 

18from collections.abc import Callable 

19from dataclasses import dataclass 

20 

21from downtify.db.config import Dialect 

22from downtify.db.core import Connection, Database 

23 

24DEFAULT_PACKAGE = 'downtify.db.migrations.versions' 

25 

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""" 

35 

36 

37@dataclass(frozen=True) 

38class Migration: 

39 version: int 

40 name: str 

41 up: Callable[[Connection], None] 

42 

43 

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 

68 

69 

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] 

80 

81 

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) 

88 

89 

90def run_migrations(db: Database, package: str = DEFAULT_PACKAGE) -> list[int]: 

91 """Apply pending migrations; return the versions applied by this call. 

92 

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