Open-source personal finance manager. Self-hosted, privacy-first.
ci: fail when two migrations claim the same revision id (#720)
Tássio Noronha69503c0fae82
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 15242564..47c07820 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -113,6 +113,19 @@ jobs:minColorRange: 50maxColorRange: 90+ migration-chain:+ name: Migration Chain+ runs-on: ubuntu-latest++ steps:+ # No `ref:` override, so on a pull request this is the merge with the+ # base branch. That is the whole point: a revision id that only clashes+ # once both sides are together is visible here and nowhere else.+ - uses: actions/checkout@v7++ - name: Check the Alembic revision chain+ run: python3 backend/scripts/check_migration_chain.py+frontend-checks:name: Frontend Checksruns-on: ubuntu-latestdiff --git a/.pre-commit-config.yaml b/.pre-commit-config.yamlindex 9f2421b4..f3376990 100644--- a/.pre-commit-config.yaml+++ b/.pre-commit-config.yaml@@ -20,6 +20,14 @@ repos:files: ^backend/pass_filenames: false+ - id: migration-chain+ name: alembic chain (backend)+ entry: python3 backend/scripts/check_migration_chain.py+ language: system+ files: ^backend/alembic/versions/+ # The chain is a property of the whole directory, not of one file.+ pass_filenames: false+- id: tyname: ty (backend)entry: bash -c 'cd backend && ty check .'diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex a4d4af24..8b5c52fa 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -123,6 +123,9 @@ ty check .# commit uv.lock along with it (CI enforces this)./scripts/lock.sh+# After adding a migration: check the revision chain is still a single line+python3 scripts/check_migration_chain.py+# Frontend lintcd frontend && npm run lint@@ -130,6 +133,21 @@ cd frontend && npm run lintcd frontend && npm run build```+### Adding a migration++Number the file after the current head and chain it there, so+`backend/alembic/versions/` sorts in apply order:++```python+revision: str = "076"+down_revision: Union[str, None] = "075"+```++If another migration lands on `main` while your PR is open, your number is+taken and you have to renumber. CI catches this: the Migration Chain job runs+against your branch merged with `main`, so a clash fails there rather than on+someone's `alembic upgrade head` after both are merged.+## Pull Request Guidelines- Keep PRs focused — one feature or fix per PRdiff --git a/backend/scripts/check_migration_chain.py b/backend/scripts/check_migration_chain.pynew file mode 100755index 00000000..73c1a090--- /dev/null+++ b/backend/scripts/check_migration_chain.py@@ -0,0 +1,160 @@+#!/usr/bin/env python3+"""Fail when the Alembic revision chain is not a single straight line.++Two long-lived branches that each add a migration pick the same next number+without noticing: both say `revision = "074"`, both chain off `"073"`. Each+branch is fine on its own, and each one's CI is green, so the collision only+shows up once they are both on main — where `alembic upgrade head` refuses to+run at all:++ UserWarning: Revision 074 is present more than once+ FAILED: Multiple head revisions are present for given argument 'head'++That is a broken deploy for everyone, found after the fact. On a pull request+CI checks out the merge with the base branch, so running this there sees both+sides and catches the clash while it is still one rename to fix.++Parses the revision files directly rather than importing Alembic: this runs+before any dependency is installed, and it never touches a database.+"""++from __future__ import annotations++import re+import sys+from pathlib import Path++VERSIONS_DIR = Path(__file__).resolve().parent.parent / "alembic" / "versions"++# `revision: str = "074"` and `down_revision: Union[str, None] = "073"`, plus+# the plain unannotated forms, single or double quoted.+_REVISION_RE = re.compile(r"^revision(?:\s*:\s*[^=]+)?\s*=\s*['\"]([^'\"]+)['\"]", re.M)+_DOWN_RE = re.compile(r"^down_revision(?:\s*:\s*[^=]+)?\s*=\s*(?:['\"]([^'\"]+)['\"]|None)", re.M)+++class Revision:+ def __init__(self, path: Path, revision: str, down_revision: str | None):+ self.path = path+ self.revision = revision+ self.down_revision = down_revision++ @property+ def name(self) -> str:+ return self.path.name+++def load_revisions(versions_dir: Path) -> tuple[list[Revision], list[str]]:+ """Return every parsed revision, plus errors for the files that resisted."""+ revisions: list[Revision] = []+ errors: list[str] = []++ for path in sorted(versions_dir.glob("*.py")):+ if path.name == "__init__.py":+ continue+ source = path.read_text(encoding="utf-8")++ revision_match = _REVISION_RE.search(source)+ if revision_match is None:+ errors.append(f"{path.name}: no `revision = \"...\"` assignment found")+ continue++ down_match = _DOWN_RE.search(source)+ if down_match is None:+ errors.append(f"{path.name}: no `down_revision = ...` assignment found")+ continue++ revisions.append(Revision(path, revision_match.group(1), down_match.group(1)))++ return revisions, errors+++def check(versions_dir: Path) -> list[str]:+ """Return one message per problem; an empty list means the chain is sound."""+ revisions, errors = load_revisions(versions_dir)+ if not revisions:+ return errors + [f"no migration files found in {versions_dir}"]++ by_revision: dict[str, list[Revision]] = {}+ for rev in revisions:+ by_revision.setdefault(rev.revision, []).append(rev)++ # The collision this script exists for: two files claiming one id.+ for revision_id, group in sorted(by_revision.items()):+ if len(group) > 1:+ files = ", ".join(sorted(rev.name for rev in group))+ errors.append(+ f"revision id {revision_id!r} is claimed by {len(group)} files: {files}. "+ f"Renumber the newer one and point its down_revision at the current head."+ )++ # A typo in down_revision, or a migration deleted out from under its child.+ for rev in revisions:+ if rev.down_revision is not None and rev.down_revision not in by_revision:+ errors.append(+ f"{rev.name}: down_revision {rev.down_revision!r} does not exist"+ )++ bases = [rev for rev in revisions if rev.down_revision is None]+ if len(bases) != 1:+ listed = ", ".join(sorted(rev.name for rev in bases)) or "none"+ errors.append(+ f"expected exactly one base migration (down_revision = None), found "+ f"{len(bases)}: {listed}"+ )++ # A head is a revision nothing chains off. More than one means the history+ # forked, which is what `alembic upgrade head` refuses to resolve.+ parents = {rev.down_revision for rev in revisions if rev.down_revision}+ heads = [rev for rev in revisions if rev.revision not in parents]+ if len(heads) != 1:+ listed = ", ".join(f"{rev.revision} ({rev.name})" for rev in sorted(heads, key=lambda r: r.name))+ errors.append(+ f"expected exactly one head, found {len(heads)}: {listed}. "+ f"`alembic upgrade head` cannot pick between them."+ )++ # Repo convention: the filename is the revision id plus a description, so+ # `ls versions/` reads in apply order.+ for rev in revisions:+ prefix = rev.name.split("_", 1)[0]+ if prefix != rev.revision:+ errors.append(+ f"{rev.name}: filename starts with {prefix!r} but the revision id "+ f"is {rev.revision!r}; keep them the same so the directory sorts "+ f"in apply order"+ )++ return errors+++def main() -> int:+ versions_dir = Path(sys.argv[1]) if len(sys.argv) > 1 else VERSIONS_DIR+ if not versions_dir.is_dir():+ print(f"migration chain: {versions_dir} is not a directory", file=sys.stderr)+ return 1++ problems = check(versions_dir)+ if problems:+ print("Alembic revision chain is broken:\n", file=sys.stderr)+ for problem in problems:+ print(f" - {problem}", file=sys.stderr)+ print(+ "\nOn a pull request this compares your branch merged with the base "+ "branch, so a clash here means another migration landed on main "+ "while yours was open.",+ file=sys.stderr,+ )+ return 1++ revisions, _ = load_revisions(versions_dir)+ parents = {rev.down_revision for rev in revisions if rev.down_revision}+ head = next(rev for rev in revisions if rev.revision not in parents)+ print(+ f"Alembic revision chain is a single line: {len(revisions)} migrations, "+ f"head {head.revision} ({head.name})."+ )+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/backend/tests/test_migration_chain.py b/backend/tests/test_migration_chain.pynew file mode 100644index 00000000..c342d3c9--- /dev/null+++ b/backend/tests/test_migration_chain.py@@ -0,0 +1,125 @@+"""Tests for the Alembic revision chain guard.++The guard exists because two branches can each pick the same next revision+number and stay green until they are both on main, where `alembic upgrade+head` then refuses to run. These build that situation on disk and assert the+guard reports it.+"""++import importlib.util+from pathlib import Path++import pytest++_SCRIPT = Path(__file__).resolve().parent.parent / "scripts" / "check_migration_chain.py"+_spec = importlib.util.spec_from_file_location("check_migration_chain", _SCRIPT)+assert _spec and _spec.loader+check_migration_chain = importlib.util.module_from_spec(_spec)+_spec.loader.exec_module(check_migration_chain)++check = check_migration_chain.check++_TEMPLATE = '''"""{description}"""+from typing import Sequence, Union++revision: str = "{revision}"+down_revision: Union[str, None] = {down}+branch_labels: Union[str, Sequence[str], None] = None+depends_on: Union[str, Sequence[str], None] = None+++def upgrade() -> None:+ pass+++def downgrade() -> None:+ pass+'''+++def _write(directory: Path, filename: str, revision: str, down: str | None) -> None:+ down_literal = "None" if down is None else f'"{down}"'+ directory.joinpath(filename).write_text(+ _TEMPLATE.format(description=filename, revision=revision, down=down_literal),+ encoding="utf-8",+ )+++def versions(tmp_path: Path) -> Path:+ """A sound three-migration chain: 001 -> 002 -> 003."""+ directory = tmp_path / "versions"+ directory.mkdir()+ _write(directory, "001_initial.py", "001", None)+ _write(directory, "002_second.py", "002", "001")+ _write(directory, "003_third.py", "003", "002")+ return directory+++def test_straight_chain_passes(versions: Path):+ assert check(versions) == []+++def test_duplicate_revision_id_is_reported(versions: Path):+ # The real case: two branches both numbered their migration 004.+ _write(versions, "004_from_branch_a.py", "004", "003")+ _write(versions, "004_from_branch_b.py", "004", "003")++ problems = check(versions)++ assert any("'004' is claimed by 2 files" in p for p in problems)+ assert any("004_from_branch_a.py" in p and "004_from_branch_b.py" in p for p in problems)+++def test_two_heads_without_duplicate_ids_are_reported(versions: Path):+ # Distinct ids, but both chain off 003, so the history forks.+ _write(versions, "004_from_branch_a.py", "004", "003")+ _write(versions, "005_from_branch_b.py", "005", "003")++ problems = check(versions)++ assert any("expected exactly one head, found 2" in p for p in problems)+++def test_missing_down_revision_target_is_reported(versions: Path):+ _write(versions, "004_orphan.py", "004", "999")++ problems = check(versions)++ assert any("down_revision '999' does not exist" in p for p in problems)+++def test_second_base_is_reported(versions: Path):+ _write(versions, "004_second_base.py", "004", None)++ problems = check(versions)++ assert any("expected exactly one base migration" in p for p in problems)+++def test_filename_prefix_must_match_revision_id(versions: Path):+ _write(versions, "999_mislabelled.py", "004", "003")++ problems = check(versions)++ assert any("filename starts with '999'" in p for p in problems)+++def test_unparseable_file_is_reported(versions: Path):+ versions.joinpath("004_broken.py").write_text("# no revision here\n", encoding="utf-8")++ problems = check(versions)++ assert any("no `revision" in p for p in problems)+++def test_empty_directory_is_reported(tmp_path: Path):+ empty = tmp_path / "versions"+ empty.mkdir()++ assert any("no migration files found" in p for p in check(empty))+++def test_the_repository_chain_is_sound():+ """The guard's own subject: this repo's real migrations."""+ assert check(check_migration_chain.VERSIONS_DIR) == []