alembic-guard 0.1.0__tar.gz

alembic_guard-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,44 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync
+      - run: uv run pytest -q
+
+  # Dogfood the action itself: the safe examples must pass, the dangerous one must fail.
+  action:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Safe migrations pass
+        uses: ./
+        with:
+          paths: examples/migrations/versions/0001_create_users.py examples/migrations/versions/0003_add_email_safely.py
+          strict: "true"
+          changed-only: "false"
+      - name: Dangerous migration fails
+        id: dangerous
+        continue-on-error: true
+        uses: ./
+        with:
+          paths: examples/migrations/versions/0002_add_email.py
+          changed-only: "false"
+      - name: Assert the dangerous migration was caught
+        if: steps.dangerous.outcome != 'failure'
+        run: |
+          echo "alembic-guard should have failed on 0002_add_email.py"
+          exit 1

alembic_guard-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,20 @@
+name: Publish to PyPI
+
+# Runs when a GitHub release is published. Uses PyPI trusted publishing,
+# so no API token is stored in the repo.
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv run --with pytest pytest -q
+      - run: uv build
+      - run: uv publish --trusted-publishing always

alembic_guard-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.egg-info/
+.venv/
+dist/
+.pytest_cache/
+EXPLAINED.md

alembic_guard-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shalom Hunukumbura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

alembic_guard-0.1.0/PKG-INFO

@@ -0,0 +1,158 @@
+Metadata-Version: 2.5
+Name: alembic-guard
+Version: 0.1.0
+Summary: Catch Alembic migrations that lock tables or break running code before they reach production.
+Project-URL: Homepage, https://github.com/ShalomHunukumbura/alembic-guard
+Project-URL: Issues, https://github.com/ShalomHunukumbura/alembic-guard/issues
+Author: Shalom Hunukumbura
+License-Expression: MIT
+License-File: LICENSE
+Keywords: alembic,linter,migrations,postgresql,sqlalchemy,zero-downtime
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Description-Content-Type: text/markdown
+
+# alembic-guard
+
+**Catch Alembic migrations that lock tables or break running code, before they reach production.**
+
+This migration passes code review, passes tests on an empty dev database, and takes down production:
+
+```python
+def upgrade():
+    op.add_column("users", sa.Column("email", sa.String(255), nullable=False))
+    op.create_index("ix_users_email", "users", ["email"], unique=True)
+    op.alter_column("users", "name", new_column_name="full_name")
+    op.create_foreign_key("fk_orders_user", "orders", "users", ["user_id"], ["id"])
+```
+
+```console
+$ alembic-guard
+migrations/versions/0002_add_email.py:13:5  AG001 error  Adding NOT NULL column "users.email" without a server_default fails on a table with rows.
+    fix: Add a server_default, or add the column as nullable, backfill it, then set NOT NULL in a later migration.
+migrations/versions/0002_add_email.py:14:5  AG002 warning  Creating index "ix_users_email" on "users" blocks writes until it is built.
+    fix: Pass postgresql_concurrently=True and run it inside `with op.get_context().autocommit_block():`.
+migrations/versions/0002_add_email.py:15:5  AG004 error  Renaming "users.name" to "full_name" breaks code still using the old name.
+    fix: Expand and contract: add the new column or table, write to both, backfill, move reads over, then drop the old one in a later release.
+migrations/versions/0002_add_email.py:16:5  AG008 warning  Foreign key from "orders" to "users" is validated while blocking writes on both tables.
+    fix: Pass postgresql_not_valid=True, then run `ALTER TABLE ... VALIDATE CONSTRAINT ...` in a separate migration. Validation only takes a light lock.
+Found 2 errors and 2 warnings in 3 migrations.
+```
+
+Tools like [squawk](https://squawkhq.com) do this for raw SQL. alembic-guard reads your
+**Alembic Python migrations** directly, so it understands `op.add_column`,
+`batch_alter_table`, `autocommit_block` and the rest, with no database and no SQL
+generation step.
+
+## Install
+
+```bash
+pip install alembic-guard      # or: uv tool install alembic-guard
+```
+
+## Usage
+
+```bash
+alembic-guard                                 # finds every Alembic versions/ dir
+alembic-guard migrations/versions             # or point it at files / dirs
+alembic-guard --diff-base origin/main         # only migrations this branch added or changed
+alembic-guard --strict                        # fail on warnings too
+alembic-guard --explain AG003                 # why a rule exists and how to fix it
+alembic-guard --format github | json          # CI annotations or machine-readable output
+```
+
+Exit code `0` = clean, `1` = findings that fail the run (errors, or anything with `--strict`),
+`2` = usage error.
+
+### GitHub Action
+
+Findings show up as annotations on the pull request diff.
+
+```yaml
+# .github/workflows/migrations.yml
+on: pull_request
+jobs:
+  alembic-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # needed to diff against the base branch
+      - uses: ShalomHunukumbura/alembic-guard@v0
+        with:
+          strict: "false"        # set "true" to fail on warnings
+          # paths: "app/migrations/versions"
+          # ignore: "AG005"
+```
+
+By default only migrations changed in the PR are checked, so adopting it on a repo
+with years of history doesn't flood you with old findings.
+
+## Rules
+
+| ID | Severity | Catches |
+|----|----------|---------|
+| AG001 | error | `NOT NULL` column added without a `server_default`: fails on any table with rows |
+| AG002 | warning | Index created without `CONCURRENTLY`: blocks writes while it builds |
+| AG003 | error | `CONCURRENTLY` inside Alembic's transaction: Postgres rejects it |
+| AG004 | error | Table or column rename: old app version breaks mid-deploy |
+| AG005 | warning | Table or column drop: running code that still reads it breaks |
+| AG006 | warning | Column type change: usually rewrites the table under an exclusive lock |
+| AG007 | warning | `SET NOT NULL` on an existing column: full scan under an exclusive lock |
+| AG008 | warning | Foreign key or check constraint without `NOT VALID`: validated while blocking writes |
+| AG009 | warning | Column added with a volatile default (`gen_random_uuid()`, `nextval`): table rewrite |
+| AG010 | warning | Unique or primary key constraint on an existing table: builds an index while blocking writes |
+
+Operations on a table **created earlier in the same migration** are not flagged,
+since nobody can be using it yet. Raw SQL in `op.execute("...")` is checked for
+the common cases too.
+
+## Silencing a finding
+
+Sometimes you know better (the table has 12 rows, or it's a maintenance window):
+
+```python
+op.drop_column("users", "legacy_flag")  # alembic-guard: ignore[AG005]
+
+# alembic-guard: ignore
+op.rename_table("tmp_import", "imports")
+```
+
+Or project-wide in `pyproject.toml`:
+
+```toml
+[tool.alembic-guard]
+paths = ["app/migrations/versions"]
+ignore = ["AG005"]
+strict = false
+include-downgrade = false
+```
+
+## How it works
+
+Migrations are parsed with Python's `ast` module and never imported or executed.
+The checker walks `upgrade()` in order, keeping track of three things: which
+tables were created in this migration, which variables are `batch_alter_table`
+contexts (and for which table), and whether it's inside an `autocommit_block()`.
+Each `op.*` call is matched against Alembic's real signatures, so positional and
+keyword arguments are both understood.
+
+The rules target **PostgreSQL**, where these locking behaviours are well documented.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run alembic-guard examples/migrations/versions
+```
+
+## License
+
+MIT

alembic_guard-0.1.0/README.md

@@ -0,0 +1,138 @@
+# alembic-guard
+
+**Catch Alembic migrations that lock tables or break running code, before they reach production.**
+
+This migration passes code review, passes tests on an empty dev database, and takes down production:
+
+```python
+def upgrade():
+    op.add_column("users", sa.Column("email", sa.String(255), nullable=False))
+    op.create_index("ix_users_email", "users", ["email"], unique=True)
+    op.alter_column("users", "name", new_column_name="full_name")
+    op.create_foreign_key("fk_orders_user", "orders", "users", ["user_id"], ["id"])
+```
+
+```console
+$ alembic-guard
+migrations/versions/0002_add_email.py:13:5  AG001 error  Adding NOT NULL column "users.email" without a server_default fails on a table with rows.
+    fix: Add a server_default, or add the column as nullable, backfill it, then set NOT NULL in a later migration.
+migrations/versions/0002_add_email.py:14:5  AG002 warning  Creating index "ix_users_email" on "users" blocks writes until it is built.
+    fix: Pass postgresql_concurrently=True and run it inside `with op.get_context().autocommit_block():`.
+migrations/versions/0002_add_email.py:15:5  AG004 error  Renaming "users.name" to "full_name" breaks code still using the old name.
+    fix: Expand and contract: add the new column or table, write to both, backfill, move reads over, then drop the old one in a later release.
+migrations/versions/0002_add_email.py:16:5  AG008 warning  Foreign key from "orders" to "users" is validated while blocking writes on both tables.
+    fix: Pass postgresql_not_valid=True, then run `ALTER TABLE ... VALIDATE CONSTRAINT ...` in a separate migration. Validation only takes a light lock.
+Found 2 errors and 2 warnings in 3 migrations.
+```
+
+Tools like [squawk](https://squawkhq.com) do this for raw SQL. alembic-guard reads your
+**Alembic Python migrations** directly, so it understands `op.add_column`,
+`batch_alter_table`, `autocommit_block` and the rest, with no database and no SQL
+generation step.
+
+## Install
+
+```bash
+pip install alembic-guard      # or: uv tool install alembic-guard
+```
+
+## Usage
+
+```bash
+alembic-guard                                 # finds every Alembic versions/ dir
+alembic-guard migrations/versions             # or point it at files / dirs
+alembic-guard --diff-base origin/main         # only migrations this branch added or changed
+alembic-guard --strict                        # fail on warnings too
+alembic-guard --explain AG003                 # why a rule exists and how to fix it
+alembic-guard --format github | json          # CI annotations or machine-readable output
+```
+
+Exit code `0` = clean, `1` = findings that fail the run (errors, or anything with `--strict`),
+`2` = usage error.
+
+### GitHub Action
+
+Findings show up as annotations on the pull request diff.
+
+```yaml
+# .github/workflows/migrations.yml
+on: pull_request
+jobs:
+  alembic-guard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # needed to diff against the base branch
+      - uses: ShalomHunukumbura/alembic-guard@v0
+        with:
+          strict: "false"        # set "true" to fail on warnings
+          # paths: "app/migrations/versions"
+          # ignore: "AG005"
+```
+
+By default only migrations changed in the PR are checked, so adopting it on a repo
+with years of history doesn't flood you with old findings.
+
+## Rules
+
+| ID | Severity | Catches |
+|----|----------|---------|
+| AG001 | error | `NOT NULL` column added without a `server_default`: fails on any table with rows |
+| AG002 | warning | Index created without `CONCURRENTLY`: blocks writes while it builds |
+| AG003 | error | `CONCURRENTLY` inside Alembic's transaction: Postgres rejects it |
+| AG004 | error | Table or column rename: old app version breaks mid-deploy |
+| AG005 | warning | Table or column drop: running code that still reads it breaks |
+| AG006 | warning | Column type change: usually rewrites the table under an exclusive lock |
+| AG007 | warning | `SET NOT NULL` on an existing column: full scan under an exclusive lock |
+| AG008 | warning | Foreign key or check constraint without `NOT VALID`: validated while blocking writes |
+| AG009 | warning | Column added with a volatile default (`gen_random_uuid()`, `nextval`): table rewrite |
+| AG010 | warning | Unique or primary key constraint on an existing table: builds an index while blocking writes |
+
+Operations on a table **created earlier in the same migration** are not flagged,
+since nobody can be using it yet. Raw SQL in `op.execute("...")` is checked for
+the common cases too.
+
+## Silencing a finding
+
+Sometimes you know better (the table has 12 rows, or it's a maintenance window):
+
+```python
+op.drop_column("users", "legacy_flag")  # alembic-guard: ignore[AG005]
+
+# alembic-guard: ignore
+op.rename_table("tmp_import", "imports")
+```
+
+Or project-wide in `pyproject.toml`:
+
+```toml
+[tool.alembic-guard]
+paths = ["app/migrations/versions"]
+ignore = ["AG005"]
+strict = false
+include-downgrade = false
+```
+
+## How it works
+
+Migrations are parsed with Python's `ast` module and never imported or executed.
+The checker walks `upgrade()` in order, keeping track of three things: which
+tables were created in this migration, which variables are `batch_alter_table`
+contexts (and for which table), and whether it's inside an `autocommit_block()`.
+Each `op.*` call is matched against Alembic's real signatures, so positional and
+keyword arguments are both understood.
+
+The rules target **PostgreSQL**, where these locking behaviours are well documented.
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run alembic-guard examples/migrations/versions
+```
+
+## License
+
+MIT

alembic_guard-0.1.0/action.yml

@@ -0,0 +1,59 @@
+name: alembic-guard
+description: Catch Alembic migrations that lock tables or break running code before they reach production.
+author: Shalom Hunukumbura
+branding:
+  icon: shield
+  color: blue
+
+inputs:
+  paths:
+    description: Space-separated migration files or directories. Defaults to every Alembic versions/ directory found.
+    required: false
+    default: ""
+  strict:
+    description: Fail on warnings as well as errors.
+    required: false
+    default: "false"
+  ignore:
+    description: Comma-separated rule ids to skip, e.g. AG002,AG005.
+    required: false
+    default: ""
+  changed-only:
+    description: On pull requests, only check migrations the PR adds or changes. Needs actions/checkout with fetch-depth 0.
+    required: false
+    default: "true"
+  python-version:
+    description: Python version used to run the checker.
+    required: false
+    default: "3.12"
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-python@v5
+      with:
+        python-version: ${{ inputs.python-version }}
+
+    - name: Install alembic-guard
+      shell: bash
+      run: pip install --quiet "${{ github.action_path }}"
+
+    - name: Check migrations
+      shell: bash
+      env:
+        AG_PATHS: ${{ inputs.paths }}
+        AG_STRICT: ${{ inputs.strict }}
+        AG_IGNORE: ${{ inputs.ignore }}
+        AG_CHANGED_ONLY: ${{ inputs.changed-only }}
+        AG_BASE_REF: ${{ github.base_ref }}
+      run: |
+        args=(--format github)
+        [[ "$AG_STRICT" == "true" ]] && args+=(--strict)
+        [[ -n "$AG_IGNORE" ]] && args+=(--ignore "$AG_IGNORE")
+        if [[ "$AG_CHANGED_ONLY" == "true" && -n "$AG_BASE_REF" ]]; then
+          git fetch --no-tags --quiet origin "$AG_BASE_REF"
+          args+=(--diff-base "origin/$AG_BASE_REF")
+        fi
+        # Word-splitting on AG_PATHS is intended: it is a space-separated list.
+        # shellcheck disable=SC2086
+        alembic-guard "${args[@]}" $AG_PATHS

alembic_guard-0.1.0/examples/migrations/versions/0001_create_users.py

@@ -0,0 +1,23 @@
+"""create users
+
+Revision ID: 0001
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0001"
+down_revision = None
+
+
+def upgrade():
+    # Brand-new table: indexes and constraints on it can't block anyone.
+    op.create_table(
+        "users",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("name", sa.String(120), nullable=False),
+    )
+    op.create_index("ix_users_name", "users", ["name"])
+
+
+def downgrade():
+    op.drop_table("users")

alembic_guard-0.1.0/examples/migrations/versions/0002_add_email.py

@@ -0,0 +1,23 @@
+"""add email to users -- the migration that looks fine in review
+
+Revision ID: 0002
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0002"
+down_revision = "0001"
+
+
+def upgrade():
+    op.add_column("users", sa.Column("email", sa.String(255), nullable=False))
+    op.create_index("ix_users_email", "users", ["email"], unique=True)
+    op.alter_column("users", "name", new_column_name="full_name")
+    op.create_foreign_key("fk_orders_user", "orders", "users", ["user_id"], ["id"])
+
+
+def downgrade():
+    op.drop_constraint("fk_orders_user", "orders")
+    op.alter_column("users", "full_name", new_column_name="name")
+    op.drop_index("ix_users_email", "users")
+    op.drop_column("users", "email")

alembic_guard-0.1.0/examples/migrations/versions/0003_add_email_safely.py

@@ -0,0 +1,29 @@
+"""add email to users -- the zero-downtime version
+
+Revision ID: 0003
+"""
+from alembic import op
+import sqlalchemy as sa
+
+revision = "0003"
+down_revision = "0001"
+
+
+def upgrade():
+    # Nullable first; the app backfills it, and a later migration sets NOT NULL.
+    op.add_column("users", sa.Column("email", sa.String(255), nullable=True))
+
+    # Built without blocking writes. CONCURRENTLY can't run inside a transaction.
+    with op.get_context().autocommit_block():
+        op.create_index("ix_users_email", "users", ["email"], unique=True, postgresql_concurrently=True)
+
+    # Skip the full-table check now; VALIDATE CONSTRAINT runs later under a light lock.
+    op.create_foreign_key(
+        "fk_orders_user", "orders", "users", ["user_id"], ["id"], postgresql_not_valid=True
+    )
+
+
+def downgrade():
+    op.drop_constraint("fk_orders_user", "orders")
+    op.drop_index("ix_users_email", "users")
+    op.drop_column("users", "email")

alembic_guard-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "alembic-guard"
+version = "0.1.0"
+description = "Catch Alembic migrations that lock tables or break running code before they reach production."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Shalom Hunukumbura" }]
+keywords = ["alembic", "postgresql", "migrations", "linter", "sqlalchemy", "zero-downtime"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Topic :: Database",
+    "Topic :: Software Development :: Quality Assurance",
+]
+dependencies = ["tomli>=2.0; python_version < '3.11'"]
+
+[project.urls]
+Homepage = "https://github.com/ShalomHunukumbura/alembic-guard"
+Issues = "https://github.com/ShalomHunukumbura/alembic-guard/issues"
+
+[project.scripts]
+alembic-guard = "alembic_guard.cli:main"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/alembic_guard"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

alembic_guard-0.1.0/src/alembic_guard/__init__.py

@@ -0,0 +1,8 @@
+"""Catch Alembic migrations that lock tables or break running code."""
+
+from .checker import Finding, check_file, check_source
+from .rules import RULES, Rule, Severity
+
+__version__ = "0.1.0"
+
+__all__ = ["Finding", "RULES", "Rule", "Severity", "check_file", "check_source", "__version__"]

alembic_guard-0.1.0/src/alembic_guard/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())