ormguard 0.1.0__py3-none-any.whl

ormguard/__init__.py

@@ -0,0 +1,42 @@
+"""ormguard — fail-fast schema validation for SQLAlchemy.
+
+Brings Hibernate's ``ddl-auto=validate`` to SQLAlchemy: at startup, reflect the
+connected database and check that it matches your ORM entities. Catch
+entity↔DB drift at boot instead of as a runtime ``column does not exist``.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version as _pkg_version
+
+from .config import Config
+from .core import (
+    assert_schema,
+    format_matrix,
+    validate,
+    validate_many,
+)
+from .model import (
+    Finding,
+    SchemaValidationError,
+    Severity,
+    ValidationReport,
+)
+
+try:
+    __version__ = _pkg_version("ormguard")
+except PackageNotFoundError:  # source tree without installed metadata
+    __version__ = "0.0.0+unknown"
+
+__all__ = [
+    "validate",
+    "assert_schema",
+    "validate_many",
+    "format_matrix",
+    "Config",
+    "Severity",
+    "Finding",
+    "ValidationReport",
+    "SchemaValidationError",
+    "__version__",
+]

ormguard/__main__.py

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

ormguard/_schema.py

@@ -0,0 +1,75 @@
+"""Normalized, dialect-light schema representation shared by both sides
+of the comparison (ORM-expected and DB-reflected)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass(frozen=True)
+class ColumnInfo:
+    name: str
+    type_str: str          # normalized (dialect-compiled, upper-cased) type
+    nullable: bool
+    primary_key: bool = False
+    has_server_default: bool = False   # a DB-side default exists (value not compared)
+    enum_values: tuple[str, ...] | None = None   # allowed values if this is an enum, else None
+
+
+@dataclass(frozen=True)
+class CheckConstraintInfo:
+    # CHECK constraints are compared by name only — the expression text is
+    # rewritten by each dialect on reflection, so comparing it produces noise.
+    name: str
+
+
+@dataclass(frozen=True)
+class IndexInfo:
+    name: str
+    columns: tuple[str, ...]   # in declared order
+    unique: bool = False
+
+    @property
+    def key(self) -> tuple[tuple[str, ...], bool]:
+        # Indexes are compared by column set + uniqueness, not by name —
+        # names differ between the ORM and the database and across dialects.
+        return (self.columns, self.unique)
+
+
+@dataclass(frozen=True)
+class ForeignKeyInfo:
+    columns: tuple[str, ...]            # local columns, in order
+    referred_table: str
+    referred_columns: tuple[str, ...]
+    name: str = ""
+
+    @property
+    def key(self) -> tuple[tuple[str, ...], str, tuple[str, ...]]:
+        # Compared by (local columns, referred table, referred columns), not by
+        # name — constraint names differ between the ORM and dialects.
+        return (self.columns, self.referred_table, self.referred_columns)
+
+
+@dataclass
+class TableInfo:
+    name: str
+    schema: str | None
+    columns: dict[str, ColumnInfo] = field(default_factory=dict)
+    indexes: dict[tuple[tuple[str, ...], bool], IndexInfo] = field(default_factory=dict)
+    foreign_keys: dict[tuple[tuple[str, ...], str, tuple[str, ...]], ForeignKeyInfo] = field(
+        default_factory=dict
+    )
+    checks: dict[str, CheckConstraintInfo] = field(default_factory=dict)  # keyed by constraint name
+
+    @property
+    def key(self) -> tuple[str | None, str]:
+        return (self.schema, self.name)
+
+
+def type_to_string(type_engine, dialect) -> str:
+    """Best-effort normalized type string. Falls back to repr when a type
+    cannot be compiled for the given dialect (common for reflected types)."""
+    try:
+        return type_engine.compile(dialect=dialect).upper()
+    except Exception:
+        return str(type_engine).upper()

ormguard/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.1.0'
+__version_tuple__ = version_tuple = (0, 1, 0)
+
+__commit_id__ = commit_id = None

ormguard/cli.py

@@ -0,0 +1,120 @@
+"""Command-line interface: ``python -m ormguard``.
+
+Validate a database against ORM metadata in CI. Exit code 1 on ERROR findings.
+
+    python -m ormguard --url postgresql://u:p@host/db --metadata myapp.db:Base --schema aivelabs_sv
+"""
+
+from __future__ import annotations
+
+import argparse
+import importlib
+import sys
+
+from sqlalchemy import create_engine
+
+from .config import Config
+from .core import validate
+
+
+def _force_utf8_output() -> None:
+    """Emit UTF-8 even on legacy consoles (e.g. Windows cp949).
+
+    Report output contains characters like ``—`` and ``→``; without this, a
+    ``print`` on a cp949 terminal raises ``UnicodeEncodeError``.
+    """
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            try:
+                reconfigure(encoding="utf-8")
+            except (ValueError, OSError):  # pragma: no cover - stream may not support it
+                pass
+
+
+def _load_metadata(spec: str):
+    """Load 'package.module:attr' where attr is a declarative Base or MetaData."""
+    if ":" not in spec:
+        raise SystemExit("--metadata must be 'package.module:attr' (e.g. myapp.db:Base)")
+    module_name, attr = spec.split(":", 1)
+    module = importlib.import_module(module_name)
+    return getattr(module, attr)
+
+
+def main(argv: list[str] | None = None) -> int:
+    _force_utf8_output()
+    parser = argparse.ArgumentParser(prog="ormguard", description="Validate DB schema against SQLAlchemy ORM.")
+    parser.add_argument(
+        "--selfcheck", action="store_true",
+        help="run a self-contained demo against in-memory SQLite (no --url/--metadata needed)",
+    )
+    parser.add_argument("--url", help="SQLAlchemy database URL")
+    parser.add_argument("--metadata", help="'package.module:attr' (Base or MetaData)")
+    parser.add_argument("--schema", action="append", default=None, help="restrict to schema (repeatable)")
+    parser.add_argument("--check-types", action="store_true", help="also compare column types")
+    parser.add_argument("--check-indexes", action="store_true", help="also compare indexes (opt-in)")
+    parser.add_argument(
+        "--check-foreign-keys", action="store_true", help="also compare foreign keys (opt-in)",
+    )
+    parser.add_argument(
+        "--check-defaults", action="store_true",
+        help="also compare server-default presence (opt-in)",
+    )
+    parser.add_argument("--no-nullable", action="store_true", help="skip nullable comparison")
+    parser.add_argument("--no-extra", action="store_true", help="do not flag DB-only columns")
+    parser.add_argument("--ignore-table", action="append", default=[], help="table to skip (repeatable)")
+    parser.add_argument(
+        "--warn-only", action="store_true",
+        help="exit 0 even on errors (report only)",
+    )
+    parser.add_argument(
+        "--notify-webhook",
+        help="POST the report to a Slack/Discord incoming webhook when drift is found",
+    )
+    parser.add_argument(
+        "--notify-on", choices=("error", "any"), default="error",
+        help="send the webhook on 'error' findings (default) or on 'any' finding",
+    )
+    args = parser.parse_args(argv)
+
+    if args.selfcheck:
+        from .selfcheck import run_selfcheck
+
+        report = run_selfcheck()
+        return 1 if (report.has_errors() and not args.warn_only) else 0
+
+    if not args.url or not args.metadata:
+        parser.error("--url and --metadata are required (or use --selfcheck)")
+
+    config = Config(
+        schemas=set(args.schema) if args.schema else None,
+        check_types=args.check_types,
+        check_indexes=args.check_indexes,
+        check_foreign_keys=args.check_foreign_keys,
+        check_server_defaults=args.check_defaults,
+        check_nullable=not args.no_nullable,
+        flag_extra_columns=not args.no_extra,
+        ignore_tables=set(args.ignore_table),
+    )
+
+    target = _load_metadata(args.metadata)
+    engine = create_engine(args.url)
+    report = validate(engine, target, config)
+
+    print(report.format_text())
+
+    if args.notify_webhook:
+        should_notify = report.has_errors() if args.notify_on == "error" else bool(report.findings)
+        if should_notify:
+            from .notify import notify_webhook
+
+            if not notify_webhook(args.notify_webhook, report):
+                print("ormguard: warning — webhook notification failed", file=sys.stderr)
+
+    if report.has_errors() and not args.warn_only:
+        return 1
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

ormguard/config.py

@@ -0,0 +1,78 @@
+"""Validation configuration for ormguard."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .model import (
+    CHECK_EXTRA,
+    CHECK_MISSING,
+    COLUMN_EXTRA,
+    DEFAULT_EXTRA,
+    DEFAULT_MISSING,
+    ENUM_MISMATCH,
+    FK_EXTRA,
+    FK_MISSING,
+    INDEX_EXTRA,
+    INDEX_MISSING,
+    NULLABLE_MISMATCH,
+    TYPE_MISMATCH,
+    Severity,
+)
+
+
+@dataclass
+class Config:
+    """Controls what ormguard checks and how loud each finding is.
+
+    The defaults are tuned for low false positives: presence checks are
+    ERROR (these are the cases that crash at runtime), structural nuances
+    default to WARN, and type comparison is off until you opt in.
+    """
+
+    # Restrict validation to these schemas. None = every schema present in the
+    # ORM metadata. Useful for multi-schema setups (e.g. {"aivelabs_sv"}).
+    schemas: set[str] | None = None
+
+    # Tables to skip entirely (unqualified name, e.g. "alembic_version").
+    ignore_tables: set[str] = field(default_factory=set)
+
+    # Columns to skip, as "table.column" (e.g. "users.legacy_flag").
+    ignore_columns: set[str] = field(default_factory=set)
+
+    # Toggles.
+    check_nullable: bool = True
+    check_types: bool = False  # dialect-dependent; opt in once tuned for your DB.
+    check_indexes: bool = False  # dialect-dependent; opt in. Compares by column set + uniqueness.
+    check_foreign_keys: bool = False  # opt in. Compares by (columns, referred table, referred columns).
+    check_server_defaults: bool = False  # opt in. Compares presence of a DB default, not its value.
+    check_constraints: bool = False  # opt in. Compares named CHECK constraints by name (not expression).
+    check_enums: bool = False  # opt in. Compares an enum column's allowed values.
+    flag_extra_columns: bool = True  # DB columns not present on the entity.
+
+    # Severity per kind — override to make e.g. nullable mismatches fatal.
+    severity_overrides: dict[str, Severity] = field(
+        default_factory=lambda: {
+            COLUMN_EXTRA: Severity.WARN,
+            NULLABLE_MISMATCH: Severity.WARN,
+            TYPE_MISMATCH: Severity.WARN,
+            INDEX_MISSING: Severity.WARN,
+            INDEX_EXTRA: Severity.WARN,
+            FK_MISSING: Severity.WARN,
+            FK_EXTRA: Severity.WARN,
+            DEFAULT_MISSING: Severity.WARN,
+            DEFAULT_EXTRA: Severity.WARN,
+            CHECK_MISSING: Severity.WARN,
+            CHECK_EXTRA: Severity.WARN,
+            ENUM_MISMATCH: Severity.WARN,
+        }
+    )
+
+    def severity_for(self, kind: str, default: Severity) -> Severity:
+        return self.severity_overrides.get(kind, default)
+
+    def is_table_ignored(self, table: str) -> bool:
+        return table in self.ignore_tables
+
+    def is_column_ignored(self, table: str, column: str) -> bool:
+        return f"{table}.{column}" in self.ignore_columns

ormguard/core.py

@@ -0,0 +1,71 @@
+"""Public validation entry points."""
+
+from __future__ import annotations
+
+from .config import Config
+from .diff import diff_schemas
+from .model import SchemaValidationError, ValidationReport
+from .orm import build_expected
+from .reflect import reflect_actual
+
+
+def _resolve_metadata(target):
+    """Accept either a declarative Base (has ``.metadata``) or a MetaData."""
+    return getattr(target, "metadata", target)
+
+
+def validate(engine, target, config: Config | None = None, *, label: str | None = None) -> ValidationReport:
+    """Validate ORM ``target`` (declarative Base or MetaData) against the schema
+    of the database behind ``engine``. Never raises on drift — inspect the
+    returned :class:`ValidationReport` (or call ``.raise_if_errors()``)."""
+    config = config or Config()
+    metadata = _resolve_metadata(target)
+    dialect = engine.dialect
+
+    expected = build_expected(metadata, dialect, config)
+    actual = reflect_actual(engine, expected, config)
+    findings = diff_schemas(expected, actual, config, dialect_name=dialect.name)
+
+    if label is None:
+        label = getattr(getattr(engine, "url", None), "database", None)
+    return ValidationReport(findings=findings, label=label)
+
+
+def assert_schema(engine, target, config: Config | None = None, *, strict: bool = True) -> ValidationReport:
+    """Validate and, when ``strict``, raise :class:`SchemaValidationError` if any
+    ERROR-level drift is found. Returns the report either way."""
+    report = validate(engine, target, config)
+    if strict:
+        report.raise_if_errors()
+    return report
+
+
+def validate_many(
+    engines: dict[str, object],
+    target,
+    config: Config | None = None,
+) -> dict[str, ValidationReport]:
+    """Validate the same ORM metadata against several databases (multi-tenant).
+    Keys are tenant labels; values are engines."""
+    return {
+        label: validate(engine, target, config, label=label)
+        for label, engine in engines.items()
+    }
+
+
+def format_matrix(reports: dict[str, ValidationReport]) -> str:
+    """One-line-per-tenant summary for multi-tenant runs."""
+    lines = []
+    for label, rep in reports.items():
+        status = "OK" if rep.ok else f"{len(rep.errors)}E/{len(rep.warnings)}W"
+        lines.append(f"{label:<24} {status}")
+    return "\n".join(lines)
+
+
+__all__ = [
+    "validate",
+    "assert_schema",
+    "validate_many",
+    "format_matrix",
+    "SchemaValidationError",
+]

ormguard/diff.py

@@ -0,0 +1,256 @@
+"""Compare expected (ORM) vs actual (DB) schema and emit findings."""
+
+from __future__ import annotations
+
+from ._schema import TableInfo
+from .config import Config
+from .model import (
+    CHECK_EXTRA,
+    CHECK_MISSING,
+    COLUMN_EXTRA,
+    COLUMN_MISSING,
+    DEFAULT_EXTRA,
+    DEFAULT_MISSING,
+    ENUM_MISMATCH,
+    FK_EXTRA,
+    FK_MISSING,
+    INDEX_EXTRA,
+    INDEX_MISSING,
+    NULLABLE_MISMATCH,
+    TABLE_MISSING,
+    TYPE_MISMATCH,
+    Finding,
+    Severity,
+)
+from .types import normalize_type
+
+
+def diff_schemas(
+    expected: dict[tuple[str | None, str], TableInfo],
+    actual: dict[tuple[str | None, str], TableInfo | None],
+    config: Config,
+    dialect_name: str = "",
+) -> list[Finding]:
+    findings: list[Finding] = []
+
+    for key, exp in expected.items():
+        schema, table = key
+        act = actual.get(key)
+
+        if act is None:
+            findings.append(
+                Finding(
+                    severity=config.severity_for(TABLE_MISSING, Severity.ERROR),
+                    kind=TABLE_MISSING,
+                    schema=schema,
+                    table=table,
+                    detail="ORM declares this table but it is absent from the database",
+                )
+            )
+            continue
+
+        # Columns the entity expects but the DB lacks -> runtime crash case.
+        for cname, ecol in exp.columns.items():
+            acol = act.columns.get(cname)
+            if acol is None:
+                findings.append(
+                    Finding(
+                        severity=config.severity_for(COLUMN_MISSING, Severity.ERROR),
+                        kind=COLUMN_MISSING,
+                        schema=schema,
+                        table=table,
+                        column=cname,
+                        detail="entity maps this column but the database has no such column",
+                    )
+                )
+                continue
+
+            # PK columns are always NOT NULL; some dialects (SQLite) misreport
+            # them as nullable on reflection, so skip the nullable check there.
+            if config.check_nullable and not ecol.primary_key and ecol.nullable != acol.nullable:
+                findings.append(
+                    Finding(
+                        severity=config.severity_for(NULLABLE_MISMATCH, Severity.WARN),
+                        kind=NULLABLE_MISMATCH,
+                        schema=schema,
+                        table=table,
+                        column=cname,
+                        detail=(
+                            f"entity nullable={ecol.nullable} but "
+                            f"database nullable={acol.nullable}"
+                        ),
+                    )
+                )
+
+            if config.check_types and normalize_type(
+                ecol.type_str, dialect_name
+            ) != normalize_type(acol.type_str, dialect_name):
+                findings.append(
+                    Finding(
+                        severity=config.severity_for(TYPE_MISMATCH, Severity.WARN),
+                        kind=TYPE_MISMATCH,
+                        schema=schema,
+                        table=table,
+                        column=cname,
+                        detail=f"entity type {ecol.type_str} != database type {acol.type_str}",
+                    )
+                )
+
+            # Server-side default presence (opt-in) — value is not compared, only
+            # whether a DB default exists. PK identity defaults are skipped.
+            if (
+                config.check_server_defaults
+                and not ecol.primary_key
+                and ecol.has_server_default != acol.has_server_default
+            ):
+                if ecol.has_server_default:
+                    findings.append(
+                        Finding(
+                            severity=config.severity_for(DEFAULT_MISSING, Severity.WARN),
+                            kind=DEFAULT_MISSING,
+                            schema=schema,
+                            table=table,
+                            column=cname,
+                            detail="entity sets a server_default but the database column has none",
+                        )
+                    )
+                else:
+                    findings.append(
+                        Finding(
+                            severity=config.severity_for(DEFAULT_EXTRA, Severity.WARN),
+                            kind=DEFAULT_EXTRA,
+                            schema=schema,
+                            table=table,
+                            column=cname,
+                            detail="database column has a default the ORM does not declare",
+                        )
+                    )
+
+            # Enum allowed-values comparison (opt-in). Only when both sides
+            # expose enum values (native enums on Postgres/MySQL).
+            if (
+                config.check_enums
+                and ecol.enum_values is not None
+                and acol.enum_values is not None
+                and set(ecol.enum_values) != set(acol.enum_values)
+            ):
+                missing = sorted(set(ecol.enum_values) - set(acol.enum_values))
+                extra = sorted(set(acol.enum_values) - set(ecol.enum_values))
+                parts = []
+                if missing:
+                    parts.append(f"missing in DB: {missing}")
+                if extra:
+                    parts.append(f"only in DB: {extra}")
+                findings.append(
+                    Finding(
+                        severity=config.severity_for(ENUM_MISMATCH, Severity.WARN),
+                        kind=ENUM_MISMATCH,
+                        schema=schema,
+                        table=table,
+                        column=cname,
+                        detail="enum values differ (" + "; ".join(parts) + ")",
+                    )
+                )
+
+        # Columns in the DB that no entity maps.
+        if config.flag_extra_columns:
+            for cname in act.columns.keys() - exp.columns.keys():
+                findings.append(
+                    Finding(
+                        severity=config.severity_for(COLUMN_EXTRA, Severity.WARN),
+                        kind=COLUMN_EXTRA,
+                        schema=schema,
+                        table=table,
+                        column=cname,
+                        detail="database column not mapped by any entity (silently unused)",
+                    )
+                )
+
+        # Indexes (opt-in), compared by column set + uniqueness.
+        if config.check_indexes:
+            for k in exp.indexes.keys() - act.indexes.keys():
+                idx = exp.indexes[k]
+                findings.append(
+                    Finding(
+                        severity=config.severity_for(INDEX_MISSING, Severity.WARN),
+                        kind=INDEX_MISSING,
+                        schema=schema,
+                        table=table,
+                        detail=(
+                            f"ORM declares an index on ({', '.join(idx.columns)})"
+                            f"{' unique' if idx.unique else ''} but the database has none"
+                        ),
+                    )
+                )
+            for k in act.indexes.keys() - exp.indexes.keys():
+                idx = act.indexes[k]
+                findings.append(
+                    Finding(
+                        severity=config.severity_for(INDEX_EXTRA, Severity.WARN),
+                        kind=INDEX_EXTRA,
+                        schema=schema,
+                        table=table,
+                        detail=(
+                            f"database has an index on ({', '.join(idx.columns)})"
+                            f"{' unique' if idx.unique else ''} not declared in the ORM"
+                        ),
+                    )
+                )
+
+        # Foreign keys (opt-in), compared by (columns, referred table, referred columns).
+        if config.check_foreign_keys:
+            for k in exp.foreign_keys.keys() - act.foreign_keys.keys():
+                fk = exp.foreign_keys[k]
+                findings.append(
+                    Finding(
+                        severity=config.severity_for(FK_MISSING, Severity.WARN),
+                        kind=FK_MISSING,
+                        schema=schema,
+                        table=table,
+                        detail=(
+                            f"ORM declares a foreign key ({', '.join(fk.columns)}) -> "
+                            f"{fk.referred_table}({', '.join(fk.referred_columns)}) "
+                            "but the database has none"
+                        ),
+                    )
+                )
+            for k in act.foreign_keys.keys() - exp.foreign_keys.keys():
+                fk = act.foreign_keys[k]
+                findings.append(
+                    Finding(
+                        severity=config.severity_for(FK_EXTRA, Severity.WARN),
+                        kind=FK_EXTRA,
+                        schema=schema,
+                        table=table,
+                        detail=(
+                            f"database has a foreign key ({', '.join(fk.columns)}) -> "
+                            f"{fk.referred_table}({', '.join(fk.referred_columns)}) "
+                            "not declared in the ORM"
+                        ),
+                    )
+                )
+
+        # Named CHECK constraints (opt-in), compared by name only.
+        if config.check_constraints:
+            for cname in exp.checks.keys() - act.checks.keys():
+                findings.append(
+                    Finding(
+                        severity=config.severity_for(CHECK_MISSING, Severity.WARN),
+                        kind=CHECK_MISSING,
+                        schema=schema,
+                        table=table,
+                        detail=f"ORM declares CHECK constraint '{cname}' but the database has none",
+                    )
+                )
+            for cname in act.checks.keys() - exp.checks.keys():
+                findings.append(
+                    Finding(
+                        severity=config.severity_for(CHECK_EXTRA, Severity.WARN),
+                        kind=CHECK_EXTRA,
+                        schema=schema,
+                        table=table,
+                        detail=f"database has CHECK constraint '{cname}' not declared in the ORM",
+                    )
+                )
+
+    return findings