Skip to content

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.yml
index 15242564..47c07820 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -113,6 +113,19 @@ jobs:
minColorRange: 50
maxColorRange: 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 Checks
runs-on: ubuntu-latest
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 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: ty
name: ty (backend)
entry: bash -c 'cd backend && ty check .'
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 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 lint
cd frontend && npm run lint
@@ -130,6 +133,21 @@ cd frontend && npm run lint
cd 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 PR
diff --git a/backend/scripts/check_migration_chain.py b/backend/scripts/check_migration_chain.py
new file mode 100755
index 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.py
new file mode 100644
index 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) == []