SchemaGuard
SchemaGuard catches database migrations that would break your data team's dbt models, in the backend pull request, before they are merged.
It reads the migrations changed in a PR (Alembic or raw SQL), maps the changed tables and columns to dbt sources through manifest.json, walks dbt lineage downstream, and posts the result as one PR comment. The check fails when a change is breaking.
Demo
schemaguard check on the branches behind the two demo PRs, against main. The output is real; the GIF is rendered from it.
Two live PRs in the demo backend repo (gazi04/demoBackRepo):
- PR #1 renames
customers.nametofull_name. dbt'sstg_customersreadsname, so the check fails. - PR #2 adds a nullable
customers.surnamethat nothing reads, so the check passes.
The comment on PR #1:
SchemaGuard
worst: breaking · 1 breaking, 0 risky, 0 safe · 0 unmapped · 0 not analyzed
Severity Change Location Source Affected models Tests Exposures 🔴 breaking rename_column customers.name -> full_name alembic/versions/4f2f54d90f25_rename_customers_name_to_full_name.py:24 ecom.raw_customers stg_customers (hop 1), customers (hop 2) 7 -
Each new push to the PR updates the same comment instead of adding another one.
How it works
- Parse migrations. Alembic files are read with Python's
ast(onlyupgrade()); raw SQL andop.execute("...")strings go through sqlglot. Both give the same list of changes. Anything the parsers don't understand is listed as "not analyzed", never skipped silently. - Map to dbt.
schemaguard.ymlsays which backend table is which dbt source. - Walk lineage. Models that read the source directly are checked column by column, by parsing their
compiled_code. Everything further downstream is followed table by table throughchild_map.SELECT *counts as reading every column and is marked uncertain. - Rate each change.
| Severity | When |
|---|---|
| 🔴 breaking | A column that a model or source test reads is dropped or renamed; a table behind a dbt source is dropped or renamed |
| 🟡 risky | A column in use changes type or becomes nullable |
| 🟢 safe | Nothing downstream reads the column; a column becomes NOT NULL; a column is added |
A drop and an add on the same table in one migration are flagged as a possible rename.
Setup
You need a backend repo with Alembic or raw SQL migrations, and a dbt project whose sources point at that database.
1. Commit a compiled dbt manifest
In the dbt project, run dbt compile (or dbt build) and copy target/manifest.json into the backend repo, e.g. as dbt/manifest.json. dbt parse is not enough: it leaves compiled_code empty, and every first-hop model then falls back to uncertain table-level matching.
The manifest is a snapshot. Refresh it when the data team changes models.
2. Add schemaguard.yml to the backend repo root
manifest: dbt/manifest.json # default: target/manifest.json
migrations: alembic/versions # default: alembic/versions
sources: # required: backend table -> <source>.<table> in dbt
customers: ecom.raw_customers
orders: ecom.raw_orders
ignore: # tables to skip (default: none)
- alembic_version
fail_on: breaking # breaking | risky | never (default: breaking)
Paths are relative to the config file. Keys are bare table names (customers, not public.customers). Changes to tables that are neither in sources nor in ignore are listed as unmapped.
3. Add the workflow
.github/workflows/schemaguard.yml:
name: SchemaGuard
on:
pull_request:
concurrency:
group: schemaguard-${{ github.event.pull_request.number }}
cancel-in-progress: true
jobs:
schemaguard:
runs-on: ubuntu-latest
timeout-minutes: 5
permissions:
contents: read
pull-requests: write # to post the comment
steps:
- uses: actions/checkout@v5
with:
fetch-depth: 2 # SchemaGuard diffs the PR's merge commit against HEAD^1
- uses: gazi04/schemaGuard@main
Only the migrations changed in the PR are checked, so a breaking migration merged earlier doesn't fail every later PR. Keep the default checkout (no custom ref:): it gives the merge commit, whose first parent is the base branch.
Action inputs, all optional:
| Input | Default | Meaning |
|---|---|---|
config |
schemaguard.yml |
Path to the config, relative to working-directory |
fail-on |
the config's fail_on |
breaking, risky or never |
github-token |
${{ github.token }} |
Token for the comment; needs pull-requests: write |
working-directory |
. |
Folder of the backend project |
CLI
The Action wraps the same CLI, which also runs locally:
uvx --from git+https://github.com/gazi04/schemaGuard schemaguard check --base main
| Command | What it does |
|---|---|
schemaguard check [FILES]... |
Checks the given migrations, or with --base REF the ones changed since REF, or every migration in the folder |
schemaguard parse <file> |
Prints the changes found in one migration |
schemaguard lineage <source>.<table> --manifest <path> |
Prints the models downstream of a dbt source and the columns first-hop models read |
check options: --config/-c (default schemaguard.yml), --format/-f text|json|markdown, --fail-on breaking|risky|never, --base REF, --pr N (posts the comment; reads GITHUB_TOKEN and GITHUB_REPOSITORY).
Exit codes: 0 below the fail_on threshold, 1 at or above it, 2 for a usage problem (bad config, missing manifest, unknown file type, a mapped source missing from the manifest). Unmapped and not-analyzed entries never fail the run.
Metrics
Measured on 2026-11-13. They come from a small suite I wrote myself, so treat them as a sanity check, not a benchmark.
| Metric | Result | How it was measured |
|---|---|---|
| Detection rate | 15 / 15 (100%) | Changes that truly break or may break dbt (a read column dropped, renamed, retyped or made nullable; a read table dropped or renamed; a column with a source test) that check marks risky or breaking |
| False-alarm rate | 2 / 11 (18%) | Harmless changes that check marks risky or breaking. Both are DROP TABLE payments, a table no model reads: a table-level drop is always breaking because the dbt source would still point at it |
| Column-level vs table-level | 6 / 12 models (50%) vs 6 / 12 (50%) | In the demo dbt project, models reading a source directly are matched by column; the other 6 are matched by table. All 12 have compiled_code |
| Run time | 0.36 s | schemaguard check on the demo backend repo, local, with the manifest already committed |
The suite is the 26 migrations in tests/fixtures/scenarios/ (21 Alembic, 5 raw SQL), 26 analyzed changes in total. "Truly breaks" was labelled by hand per change, not taken from the tool's own expected output. Only the tool run itself is timed: the Action adds checkout and the uvx install on top.
Known limitations
SchemaGuard is an MVP: Alembic and raw SQL, Postgres, GitHub. The main limits:
- Manifest: must be committed (or otherwise present) and compiled; the Action does not run dbt, so a stale manifest gives stale results.
- Lineage: columns are matched only at the first hop; deeper models are matched by table.
SELECT *and SQL that can't be parsed fall back to table level, marked uncertain. A column with the same name in a joined table counts as used. - Migrations: only
upgrade()is read. Table and column names must be string literals;batch_alter_table, keyword-only arguments,sa.text(...), f-strings and variables become "not analyzed". Index, constraint and enum changes are not checked, and harmless statements (CREATE INDEX,BEGIN) show up as not analyzed. - Not analyzed never fails: a PR whose only change can't be read passes, with the entry listed in the comment.
- Names: schema prefixes are dropped (
public.ordersandstaging.ordersare bothorders); the table-to-source mapping is written by hand; renames are not followed across migrations in the same PR. - GitHub: PRs from forks get a read-only token, so no comment is posted (the check still fails on severity). The workflow above uses
@main, not a pinned version. - Replication: tools like Fivetran or Airbyte may soften renames and drops; SchemaGuard assumes the change reaches the warehouse as written.
The full list is in docs/architecture.md.
Development
uv sync
uv run pytest # tests
uv run pyright # type check (strict)
uv run ruff check . # lint
uv run pre-commit run --all-files
Design and decisions: docs/architecture.md. Plan and progress: docs/roadmap.md.
Metadata
Release files for schemaguard-ci 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| schemaguard_ci-0.1.0.tar.gz | 21.4 kB | Without provenance | Details for schemaguard_ci-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| schemaguard_ci-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for schemaguard_ci-0.1.0-py3-none-any.whl |
Total release size: 48.9 kB
Release files / schemaguard_ci-0.1.0.tar.gz
| Download URL | schemaguard_ci-0.1.0.tar.gz |
|---|---|
| Size | 21.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7e22c62ece25db3eccff0d299c6c3e7a80045d6f332e4cdd7106449d70a53523
|
|
BLAKE2b-256 checksum How to use checksums |
b8866546ce78e06b66a1ffca945cd55024074ca401a42c92608c92fb6ecbf912
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Arch Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / schemaguard_ci-0.1.0-py3-none-any.whl
| Download URL | schemaguard_ci-0.1.0-py3-none-any.whl |
|---|---|
| Size | 27.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
02a387bcd439a40dc70fc69010f0f401ec8b88cdeb1d3bbbb552f2624b78dc91
|
|
BLAKE2b-256 checksum How to use checksums |
11d5b4d76b3736a2249a85757d5b7a7a8cc4c3acb66b886309c69e9d9f30ed6d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.13.7 {"installer":{"name":"uv","version":"0.13.7","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Arch Linux","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for schemaguard-ci 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.