Fail-fast schema validation for SQLAlchemy. Bring Hibernate's
hibernate.ddl-auto=validate to Python: at startup, reflect the connected
database and verify it matches your ORM entities. Catch entity↔DB drift at
boot time instead of as a runtime column does not exist error.
pip install ormguard
python -m ormguard --selfcheck # see it catch drift against in-memory SQLite — no DB, no setupGuard your app at boot so it refuses to start on drift (FastAPI):
from ormguard.integrations.fastapi import schema_guard_lifespan
app = FastAPI(lifespan=schema_guard_lifespan(engine, Base, strict=True))...or fail CI before you ship (exit code 1 on ERROR findings):
python -m ormguard --url "$DATABASE_URL" --metadata myapp.db:Base...or test your Alembic migrations without any database at all:
python -m ormguard replay --migrations migration/versions --metadata myapp.db:BaseThat's it. Details and every mode are below.
In JPA/Hibernate, ddl-auto=validate checks every entity against the live
schema when the app starts and refuses to boot on a mismatch. SQLAlchemy
has no equivalent — create_all() only creates missing tables, nothing
validates existing ones. So an entity can map a column the database doesn't
have (or ignore a column it does have) and the server starts perfectly fine…
until the request that touches that column blows up in production.
alembic check and Atlas help, but both compare against migration metadata /
a live DB through autogenerate and run in CI. ormguard checks the actual
database the app is about to use, at the moment it boots.
pip install ormguard # (POC: install from source — see below)python -m ormguard --selfcheckSpins up an in-memory SQLite database with deliberate drift and prints exactly what ormguard catches — a zero-setup way to see it work or sanity-check an install.
- docs/DESIGN.md — problem, the Hibernate
validateanalogy, why existing tools don't fit, architecture, roadmap. - docs/USAGE.md — every usage mode with examples.
- docs/V2_OFFLINE_REPLAY.md — the offline multi-tenant Alembic replay mode (the differentiator), shipped M1–M4.
from ormguard.integrations.fastapi import schema_guard_lifespan
app = FastAPI(lifespan=schema_guard_lifespan(engine, Base, strict=True))
# strict=True -> app refuses to start on ERROR-level driftfrom ormguard import assert_schema, validate
assert_schema(engine, Base, strict=True) # raise on drift
report = validate(engine, Base) # or inspect findings yourself
if not report.ok:
print(report.format_text())python -m ormguard --url "$DATABASE_URL" --metadata myapp.db:Base --schema aivelabs_sv
# exit code 1 on ERROR findingsOr drop in the GitHub Action — no install step needed:
- uses: gogo1414/ormguard@v1
with:
database-url: ${{ secrets.DATABASE_URL }}
metadata: myapp.db:Base
args: --schema public --check-indexes # optional(Until ormguard is on PyPI, set version: to a VCS URL, e.g.
version: git+https://github.com/gogo1414/ormguard@main.)
Get a team-channel ping when drift is found — one webhook works for Slack or
Discord (add --notify-on any to include warnings):
python -m ormguard --url "$DATABASE_URL" --metadata myapp.db:Base \
--notify-webhook "$SLACK_OR_DISCORD_WEBHOOK"- uses: gogo1414/ormguard@v1
with:
database-url: ${{ secrets.DATABASE_URL }}
metadata: myapp.db:Base
notify-webhook: ${{ secrets.SLACK_WEBHOOK }}The Action also runs the offline modes — test migrations with no database in CI and surface drift in the GitHub Security tab via SARIF:
- uses: gogo1414/ormguard@v1
id: ormguard
with:
command: replay # or: check (with config: ormguard.toml)
migrations: migration/versions
metadata: myapp.db:Base
format: sarif
args: --tenant cafe24:shop_a --tenant larosee:larosee_co_kr
- uses: github/codeql-action/upload-sarif@v3
if: always()
with:
sarif_file: ${{ steps.ormguard.outputs.sarif-file }}format: github instead prints inline ::error:: annotations, and
--format json|sarif|github works on the CLI for validate, replay, and
check alike.
python -m ormguard --url "$DB" --metadata myapp.db:Base --baseline .ormguard-baseline.json --write-baseline
python -m ormguard --url "$DB" --metadata myapp.db:Base --baseline .ormguard-baseline.json # only NEW drift failsWorks for replay too (fingerprints are tenant-scoped in multi-tenant runs),
so CI ratchets: accepted drift stays quiet, new drift fails the build.
from ormguard import validate_many, format_matrix
reports = validate_many({"larosee": e1, "hmall": e2, "cafe24": e3}, Base)
print(format_matrix(reports))When tenants have genuinely different targets, go fleet-first — each tenant
declares its own engine and its own Base(s) (validate also accepts a list
of Bases, merged):
from ormguard import validate_fleet, format_tenant_matrix, find_divergence
reports = validate_fleet({
"larosee": (e1, [ServiceBase, MartBase]),
"cafe24": (e2, ServiceBase),
})
print(format_tenant_matrix(reports)) # label × finding matrix + divergenceAnd before slimming a shared ETL model, ask what the fleet actually has in
common — column_analysis reflects every tenant and reports, per table, the
intersection (safe to map) vs partial columns (and which tenants have them).
Multi-tenant services often branch inside migrations
(if platform_type == "cafe24": ...), so the same migration set produces a
different schema per tenant — and the tenant that breaks is the one whose DB
doesn't exist yet. ormguard replays your Alembic migrations offline, once per
tenant profile, executing the real branches, and diffs each computed schema
against the ORM:
pip install "ormguard[replay]"
python -m ormguard replay --migrations migration/versions --metadata myapp.db:Base \
--tenant cafe24:shop_a --tenant larosee:larosee_co_krfinding shop_a larosee_co_kr
column_missing @ users.order · ✗
tenant divergence — 1 finding(s) hit only a subset of tenants:
column_missing @ users.order — only on: larosee_co_kr
Raw SQL in op.execute() is parsed too (sqlglot); anything uninterpretable is
flagged as unparsed_migration_sql instead of silently ignored. No other tool
executes migration branches per tenant — alembic check and Atlas compare one
live DB. See docs/V2_OFFLINE_REPLAY.md.
Guard a whole deployment — e.g. an API's service DB and an ETL pipeline's warehouse DB, each with its own Base and Alembic environment — from one file:
# ormguard.toml
[[target]]
name = "service"
mode = "replay" # offline, no DB needed
metadata = "src.db:Base"
migrations = "migration/versions"
tenants = [["cafe24", "shop_a"], ["larosee", "larosee_co_kr"]]
[[target]]
name = "warehouse"
mode = "live" # reflect a running DB
metadata = "src.models.aace_mart:Base"
url_env = "WAREHOUSE_DB_URL"
schemas = ["aace_mart"]python -m ormguard check --config ormguard.toml # exit 1 if any target driftsReal databases produce noisy first runs. ormguard has four levers:
cfg = Config(
external_tables={"articles", "orders_mart"}, # ETL-owned: lenient (WARN, no extra-column noise)
server_managed_columns={"created_at", "updated_at"}, # DB-managed: skip nullable/default noise
)
report = validate(engine, Base, cfg)
from ormguard import columns_in_sql, rank_findings, format_ranked, suggest_fixes, format_suggestions
ranked = rank_findings(report, columns_in_sql(sql_log)) # code-referenced findings first
print(format_ranked(ranked))
print(format_suggestions(suggest_fixes(report, Base)))
# column_missing @ users.nickname -> op.add_column("users", sa.Column("nickname", sa.String(50)))Ownership tiers make ormguard a contract checker (you own the columns you
map, not the whole warehouse table); usage ranking (feed it SQL from a query
log or a SQLAlchemy listener) splits findings into code-referenced high
priority vs unused low priority; and fix suggestions render the actual
op.add_column(...) from your ORM's column type.
| Finding | Default severity | Meaning |
|---|---|---|
table_missing |
ERROR | entity declares a table the DB lacks |
column_missing |
ERROR | entity maps a column the DB lacks (the crash case) |
column_extra |
WARN | DB column not mapped by any entity (silently unused) |
nullable_mismatch |
WARN | NOT NULL / NULL disagreement |
type_mismatch |
WARN (opt-in) | column type differs — off by default (dialect-dependent) |
index_missing |
WARN (opt-in) | ORM declares an index the DB lacks — off by default |
index_extra |
WARN (opt-in) | DB has an index not declared in the ORM — off by default |
fk_missing |
WARN (opt-in) | ORM declares a foreign key the DB lacks — off by default |
fk_extra |
WARN (opt-in) | DB has a foreign key not declared in the ORM — off by default |
default_missing |
WARN (opt-in) | ORM sets a server_default the DB column lacks — off by default |
default_extra |
WARN (opt-in) | DB column has a default the ORM doesn't declare — off by default |
enum_mismatch |
WARN (opt-in) | enum's allowed values differ between ORM and DB (native enums) |
check_missing / check_extra |
WARN (opt-in) | named CHECK constraint present on one side only |
Configurable via Config: restrict schemas, ignore tables/columns, flip
severities, toggle nullable/type/index/foreign-key/default/extra checks.
Index checks (--check-indexes / Config(check_indexes=True)) compare by column
set and uniqueness — not by name — and skip indexes that merely back a primary
key or unique constraint. Foreign-key checks (--check-foreign-keys) compare by
local columns, referred table, and referred columns. Server-default checks
(--check-defaults) compare only whether a DB default exists — not its value,
which is too dialect-dependent — and skip primary keys. All keep false positives low.
Views and materialized views backing an ORM-mapped name are reflected and
compared (not false table_missing), with index/FK/CHECK checks skipped for
them. The offline multi-tenant Alembic replay mode (v2) additionally emits
unparsed_migration_sql (WARN) when replay cannot interpret raw SQL — the
report never claims a false "clean". Planned next: downgrade replay, more
dialect coverage.
pip install -e ".[dev]"
pytest # runs against in-memory SQLite, no external DB neededMIT