dbly 0.0.1__tar.gz → 0.2.0__tar.gz

{dbly-0.0.1 → dbly-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dbly
-Version: 0.0.1
+Version: 0.2.0
 Summary: State-based, cross-engine database deployment — git-driven, parser-assisted, SQL-first.
 Project-URL: Homepage, https://angrydata.info/dbly
 Project-URL: Repository, https://github.com/angrydat/dbly
@@ -81,10 +81,17 @@ db/
     v_open_orders.vw
     grants.sql
   init/                 # optional: privileged greenfield groundwork (CREATE DATABASE/ROLE…)
+  migrations/           # optional: ordered, run-once ALTERs for renames / data backfills
 hooks/pre/  hooks/post/  # optional: .sql or .py hooks (e.g. ArcGIS/ArcPy steps)
 .dbignore               # files in the repo that should not be deployed
 ```
 
+Most changes are declarative — edit the object file, dbly figures out the additive diff. For
+changes the diff can't do safely (renaming a column, moving data), drop an ordered script in
+`migrations/` (`0001_…sql`); it runs exactly once, is recorded in the ledger, and the table
+it touches defers to it for that deploy. On a fresh database, migrations are *baselined*
+(recorded, not run) since the object files already describe the end state.
+
 ## Connect
 
 A connection profile (reuses the familiar `connection.properties` format):

{dbly-0.0.1 → dbly-0.2.0}/README.md

@@ -43,10 +43,17 @@ db/
     v_open_orders.vw
     grants.sql
   init/                 # optional: privileged greenfield groundwork (CREATE DATABASE/ROLE…)
+  migrations/           # optional: ordered, run-once ALTERs for renames / data backfills
 hooks/pre/  hooks/post/  # optional: .sql or .py hooks (e.g. ArcGIS/ArcPy steps)
 .dbignore               # files in the repo that should not be deployed
 ```
 
+Most changes are declarative — edit the object file, dbly figures out the additive diff. For
+changes the diff can't do safely (renaming a column, moving data), drop an ordered script in
+`migrations/` (`0001_…sql`); it runs exactly once, is recorded in the ledger, and the table
+it touches defers to it for that deploy. On a fresh database, migrations are *baselined*
+(recorded, not run) since the object files already describe the end state.
+
 ## Connect
 
 A connection profile (reuses the familiar `connection.properties` format):

{dbly-0.0.1 → dbly-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dbly"
-version = "0.0.1"
+version = "0.2.0"
 description = "State-based, cross-engine database deployment — git-driven, parser-assisted, SQL-first."
 readme = "README.md"
 license = { text = "MIT" }

{dbly-0.0.1 → dbly-0.2.0}/src/dbly/__init__.py

@@ -4,4 +4,4 @@ git (what changed) + sqlglot (what it is) + live introspection (what's really th
 See CONCEPT.md for the design rationale.
 """
 
-__version__ = "0.0.1"
+__version__ = "0.2.0"

{dbly-0.0.1 → dbly-0.2.0}/src/dbly/adapters/base.py

@@ -13,11 +13,11 @@ from __future__ import annotations
 
 import abc
 
-from sqlalchemy import Engine
+from sqlalchemy import Engine, text
 
 from dbly.config import ConnectionConfig
 from dbly.engine import make_engine
-from dbly.model import Column, ObjectId
+from dbly.model import Column, LiveObject, ObjectId, ObjectKind
 
 __all__ = ["Adapter", "Column"]
 
@@ -28,6 +28,10 @@ class Adapter(abc.ABC):
     #: whether DDL participates in transactions (drives apply strategy)
     transactional_ddl: bool = False
 
+    #: the engine's implicit schema — an unqualified repo object maps here (used by drift
+    #: matching so repo `kunde` aligns with live `public.kunde` / `dbo.kunde`).
+    default_schema: str | None = None
+
     def __init__(self, cfg: ConnectionConfig):
         self.cfg = cfg
         self._engine: Engine | None = None
@@ -45,6 +49,19 @@ class Adapter(abc.ABC):
     @abc.abstractmethod
     def get_columns(self, schema: str | None, name: str) -> list[Column]: ...
 
+    @abc.abstractmethod
+    def has_object(self, kind: ObjectKind, schema: str | None, name: str) -> bool:
+        """Existence check for a non-table object (used for index/sequence create-if-missing).
+
+        Indexes and sequences have no ``CREATE OR REPLACE`` form on most engines, so they
+        are created only when absent.
+        """
+
+    @abc.abstractmethod
+    def inventory(self) -> list[LiveObject]:
+        """Read-only live inventory of user objects across kinds, for drift detection
+        (``dbly check``). Procedural/definitional objects carry a canonical source hash."""
+
     # --- dialect-specific DDL generation -----------------------------------------------
     @abc.abstractmethod
     def add_column_sql(self, table: ObjectId, col: Column) -> str:
@@ -78,6 +95,20 @@ class Adapter(abc.ABC):
     @abc.abstractmethod
     def record_deploy(self, ref: str, migration_ids: list[str]) -> None: ...
 
+    # --- explicit migrations (run-once, ledger-tracked) --------------------------------
+    def applied_migrations(self) -> set[str]:
+        """Migration ids already recorded in the ledger (standard SQL, all engines)."""
+        self.ensure_state_table()
+        with self.engine.connect() as conn:
+            rows = conn.execute(
+                text("SELECT DISTINCT migration_id FROM dbly_state WHERE migration_id IS NOT NULL")
+            )
+            return {r[0] for r in rows}
+
+    def record_migration(self, ref: str, migration_id: str) -> None:
+        """Mark a migration applied (reuses the per-engine record_deploy insert)."""
+        self.record_deploy(ref, [migration_id])
+
     # --- pure SQL builders (no connection — used by `plan --sql` export) ----------------
     @abc.abstractmethod
     def state_table_ddl(self) -> str:

{dbly-0.0.1 → dbly-0.2.0}/src/dbly/adapters/mssql.py

@@ -19,7 +19,8 @@ import re
 from sqlalchemy import inspect, text
 
 from dbly.adapters.base import Adapter, Column
-from dbly.model import ObjectId
+from dbly.model import LiveObject, ObjectId, ObjectKind
+from dbly.parsing import canonical_hash
 
 _GO_RE = re.compile(r"^\s*GO\s*$", re.IGNORECASE | re.MULTILINE)
 
@@ -38,6 +39,7 @@ END
 
 class MssqlAdapter(Adapter):
     transactional_ddl = True
+    default_schema = "dbo"
 
     def table_exists(self, schema: str | None, name: str) -> bool:
         return inspect(self.engine).has_table(name, schema=schema)
@@ -54,6 +56,66 @@ class MssqlAdapter(Adapter):
             for c in cols
         ]
 
+    def has_object(self, kind: ObjectKind, schema: str | None, name: str) -> bool:
+        with self.engine.connect() as conn:
+            if kind is ObjectKind.INDEX:
+                # index names are unique per table, not globally — best-effort by name
+                return conn.execute(
+                    text("SELECT TOP 1 1 FROM sys.indexes WHERE name = :n"), {"n": name}
+                ).first() is not None
+            if kind is ObjectKind.SEQUENCE:
+                return conn.execute(
+                    text(
+                        "SELECT 1 FROM sys.sequences s "
+                        "JOIN sys.schemas c ON c.schema_id = s.schema_id "
+                        "WHERE s.name = :n AND (:s IS NULL OR c.name = :s)"
+                    ),
+                    {"n": name, "s": schema},
+                ).first() is not None
+            qname = f"{schema}.{name}" if schema else name
+            return conn.execute(text("SELECT OBJECT_ID(:q)"), {"q": qname}).scalar() is not None
+
+    _OBJTYPE = {
+        "U": ObjectKind.TABLE, "V": ObjectKind.VIEW, "P": ObjectKind.PROCEDURE,
+        "FN": ObjectKind.FUNCTION, "IF": ObjectKind.FUNCTION, "TF": ObjectKind.FUNCTION,
+        "TR": ObjectKind.TRIGGER,
+    }
+
+    def inventory(self) -> list[LiveObject]:
+        objs = text(
+            "SELECT s.name, o.name, RTRIM(o.type), OBJECT_DEFINITION(o.object_id) "
+            "FROM sys.objects o JOIN sys.schemas s ON s.schema_id = o.schema_id "
+            "WHERE o.is_ms_shipped = 0 AND RTRIM(o.type) IN ('U','V','P','FN','IF','TF','TR')"
+        )
+        idx = text(
+            "SELECT s.name, i.name FROM sys.indexes i "
+            "JOIN sys.objects o ON o.object_id = i.object_id "
+            "JOIN sys.schemas s ON s.schema_id = o.schema_id "
+            "WHERE o.is_ms_shipped = 0 AND i.name IS NOT NULL "
+            "  AND i.is_primary_key = 0 AND i.type > 0"
+        )
+        seqs = text(
+            "SELECT s.name, q.name FROM sys.sequences q "
+            "JOIN sys.schemas s ON s.schema_id = q.schema_id"
+        )
+        hashed = {ObjectKind.VIEW, ObjectKind.PROCEDURE, ObjectKind.FUNCTION, ObjectKind.TRIGGER}
+        found: dict[str, LiveObject] = {}
+        with self.engine.connect() as conn:
+            for schema, name, otype, src in conn.execute(objs):
+                kind = self._OBJTYPE.get(otype)
+                if kind is None:
+                    continue
+                h = canonical_hash(src, dialect="tsql") if kind in hashed else None
+                obj = LiveObject(kind, ObjectId(schema, name), h)
+                found[obj.key()] = obj
+            for schema, name in conn.execute(idx):
+                obj = LiveObject(ObjectKind.INDEX, ObjectId(schema, name))
+                found[obj.key()] = obj
+            for schema, name in conn.execute(seqs):
+                obj = LiveObject(ObjectKind.SEQUENCE, ObjectId(schema, name))
+                found[obj.key()] = obj
+        return list(found.values())
+
     def add_column_sql(self, table: ObjectId, col: Column) -> str:
         # T-SQL: ADD, not ADD COLUMN
         parts = [f"ALTER TABLE {table} ADD {col.name} {col.type}"]

{dbly-0.0.1 → dbly-0.2.0}/src/dbly/adapters/oracle.py

@@ -24,7 +24,8 @@ import re
 from sqlalchemy import inspect, text
 
 from dbly.adapters.base import Adapter, Column
-from dbly.model import ObjectId
+from dbly.model import LiveObject, ObjectId, ObjectKind
+from dbly.parsing import canonical_hash
 
 _SLASH_RE = re.compile(r"(?m)^\s*/\s*$")
 _PLSQL_RE = re.compile(
@@ -103,6 +104,61 @@ class OracleAdapter(Adapter):
             for c in cols
         ]
 
+    def has_object(self, kind: ObjectKind, schema: str | None, name: str) -> bool:
+        n = name.upper()
+        s = schema.upper() if schema else None
+        if kind is ObjectKind.INDEX:
+            q = "SELECT 1 FROM all_indexes WHERE index_name = :n AND (:s IS NULL OR owner = :s)"
+        elif kind is ObjectKind.SEQUENCE:
+            q = ("SELECT 1 FROM all_sequences "
+                 "WHERE sequence_name = :n AND (:s IS NULL OR sequence_owner = :s)")
+        else:
+            q = "SELECT 1 FROM all_objects WHERE object_name = :n AND (:s IS NULL OR owner = :s)"
+        with self.engine.connect() as conn:
+            return conn.execute(text(q), {"n": n, "s": s}).first() is not None
+
+    _TYPEMAP = {
+        "TABLE": ObjectKind.TABLE, "VIEW": ObjectKind.VIEW, "INDEX": ObjectKind.INDEX,
+        "SEQUENCE": ObjectKind.SEQUENCE, "FUNCTION": ObjectKind.FUNCTION,
+        "PROCEDURE": ObjectKind.PROCEDURE, "TRIGGER": ObjectKind.TRIGGER,
+        "PACKAGE": ObjectKind.PACKAGE, "PACKAGE BODY": ObjectKind.PACKAGE,
+        "TYPE": ObjectKind.TYPE,
+    }
+
+    def inventory(self) -> list[LiveObject]:
+        existence = text(
+            "SELECT object_type, object_name FROM all_objects "
+            "WHERE owner = USER AND object_name NOT LIKE 'BIN$%' AND object_type IN "
+            "('TABLE','VIEW','INDEX','SEQUENCE','FUNCTION','PROCEDURE','TRIGGER',"
+            " 'PACKAGE','PACKAGE BODY','TYPE')"
+        )
+        # procedural source, one round-trip, grouped by object (line-ordered VARCHAR2 — no LONG)
+        sources = text(
+            "SELECT name, type, text FROM all_source "
+            "WHERE owner = USER AND type IN "
+            "('FUNCTION','PROCEDURE','TRIGGER','PACKAGE','PACKAGE BODY','TYPE') "
+            "ORDER BY name, type, line"
+        )
+        found: dict[str, LiveObject] = {}
+        src_text: dict[str, list[str]] = {}
+        with self.engine.connect() as conn:
+            for otype, name in conn.execute(existence):
+                kind = self._TYPEMAP.get(otype)
+                if kind is None:
+                    continue
+                obj = LiveObject(kind, ObjectId(None, name))
+                found[obj.key()] = obj
+            for name, otype, line in conn.execute(sources):
+                kind = self._TYPEMAP.get(otype)
+                if kind is None:
+                    continue
+                key = LiveObject(kind, ObjectId(None, name)).key()
+                src_text.setdefault(key, []).append(line or "")
+        for key, lines in src_text.items():
+            if key in found:
+                found[key].source_hash = canonical_hash("".join(lines), dialect="oracle")
+        return list(found.values())
+
     def add_column_sql(self, table: ObjectId, col: Column) -> str:
         parts = [f"ALTER TABLE {table} ADD {col.name} {col.type}"]
         if col.default is not None:

{dbly-0.0.1 → dbly-0.2.0}/src/dbly/adapters/postgres.py

@@ -9,7 +9,8 @@ from __future__ import annotations
 from sqlalchemy import inspect, text
 
 from dbly.adapters.base import Adapter, Column
-from dbly.model import ObjectId
+from dbly.model import LiveObject, ObjectId, ObjectKind
+from dbly.parsing import canonical_hash
 
 _STATE_DDL = """
 CREATE TABLE IF NOT EXISTS dbly_state (
@@ -23,6 +24,7 @@ CREATE TABLE IF NOT EXISTS dbly_state (
 
 class PostgresAdapter(Adapter):
     transactional_ddl = True
+    default_schema = "public"
 
     def table_exists(self, schema: str | None, name: str) -> bool:
         insp = inspect(self.engine)
@@ -41,6 +43,66 @@ class PostgresAdapter(Adapter):
             for c in cols
         ]
 
+    def has_object(self, kind: ObjectKind, schema: str | None, name: str) -> bool:
+        qname = f"{schema}.{name}" if schema else name
+        with self.engine.connect() as conn:
+            if kind in (ObjectKind.INDEX, ObjectKind.SEQUENCE, ObjectKind.TABLE, ObjectKind.VIEW):
+                return conn.execute(
+                    text("SELECT to_regclass(:q)"), {"q": qname}
+                ).scalar() is not None
+            return conn.execute(
+                text(
+                    "SELECT 1 FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace "
+                    "WHERE p.proname = :n AND (:s IS NULL OR n.nspname = :s) LIMIT 1"
+                ),
+                {"n": name, "s": schema},
+            ).first() is not None
+
+    _RELKIND = {
+        "r": ObjectKind.TABLE, "p": ObjectKind.TABLE, "v": ObjectKind.VIEW,
+        "m": ObjectKind.VIEW, "i": ObjectKind.INDEX, "S": ObjectKind.SEQUENCE,
+    }
+
+    def inventory(self) -> list[LiveObject]:
+        rels = text(
+            "SELECT n.nspname, c.relname, c.relkind, "
+            "  CASE WHEN c.relkind IN ('v','m') THEN pg_get_viewdef(c.oid) END "
+            "FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace "
+            "WHERE n.nspname NOT IN ('pg_catalog','information_schema','pg_toast') "
+            "  AND c.relkind IN ('r','p','v','m','i','S')"
+        )
+        routines = text(
+            "SELECT n.nspname, p.proname, p.prokind, pg_get_functiondef(p.oid) "
+            "FROM pg_proc p JOIN pg_namespace n ON n.oid = p.pronamespace "
+            "WHERE n.nspname NOT IN ('pg_catalog','information_schema') "
+            "  AND p.prokind IN ('f','p')"
+        )
+        triggers = text(
+            "SELECT n.nspname, t.tgname, pg_get_triggerdef(t.oid) "
+            "FROM pg_trigger t JOIN pg_class c ON c.oid = t.tgrelid "
+            "JOIN pg_namespace n ON n.oid = c.relnamespace "
+            "WHERE NOT t.tgisinternal "
+            "  AND n.nspname NOT IN ('pg_catalog','information_schema')"
+        )
+        found: dict[str, LiveObject] = {}
+        with self.engine.connect() as conn:
+            for schema, name, relkind, src in conn.execute(rels):
+                kind = self._RELKIND.get(relkind)
+                if kind is None:
+                    continue
+                h = canonical_hash(src, dialect="postgres") if kind is ObjectKind.VIEW else None
+                obj = LiveObject(kind, ObjectId(schema, name), h)
+                found[obj.key()] = obj
+            for schema, name, prokind, src in conn.execute(routines):
+                kind = ObjectKind.PROCEDURE if prokind == "p" else ObjectKind.FUNCTION
+                obj = LiveObject(kind, ObjectId(schema, name), canonical_hash(src, dialect="postgres"))
+                found[obj.key()] = obj
+            for schema, name, src in conn.execute(triggers):
+                obj = LiveObject(ObjectKind.TRIGGER, ObjectId(schema, name),
+                                 canonical_hash(src, dialect="postgres"))
+                found[obj.key()] = obj
+        return list(found.values())
+
     def add_column_sql(self, table: ObjectId, col: Column) -> str:
         parts = [f"ALTER TABLE {table} ADD COLUMN {col.name} {col.type}"]
         if not col.nullable:

{dbly-0.0.1 → dbly-0.2.0}/src/dbly/adapters/sqlite.py

@@ -9,7 +9,8 @@ from __future__ import annotations
 from sqlalchemy import inspect, text
 
 from dbly.adapters.base import Adapter, Column
-from dbly.model import ObjectId
+from dbly.model import LiveObject, ObjectId, ObjectKind
+from dbly.parsing import canonical_hash
 
 _STATE_DDL = """
 CREATE TABLE IF NOT EXISTS dbly_state (
@@ -39,6 +40,37 @@ class SqliteAdapter(Adapter):
             for c in cols
         ]
 
+    def has_object(self, kind: ObjectKind, schema: str | None, name: str) -> bool:
+        if kind is ObjectKind.SEQUENCE:
+            return False  # SQLite has no sequences
+        if kind is ObjectKind.INDEX:
+            q = "SELECT 1 FROM sqlite_master WHERE type='index' AND name=:n"
+        else:
+            q = "SELECT 1 FROM sqlite_master WHERE name=:n"
+        with self.engine.connect() as conn:
+            return conn.execute(text(q), {"n": name}).first() is not None
+
+    _TYPEMAP = {
+        "table": ObjectKind.TABLE, "view": ObjectKind.VIEW,
+        "index": ObjectKind.INDEX, "trigger": ObjectKind.TRIGGER,
+    }
+
+    def inventory(self) -> list[LiveObject]:
+        out: dict[str, LiveObject] = {}
+        with self.engine.connect() as conn:
+            rows = conn.execute(
+                text("SELECT type, name, sql FROM sqlite_master WHERE name NOT LIKE 'sqlite_%'")
+            )
+            for typ, name, sql in rows:
+                kind = self._TYPEMAP.get(typ)
+                if kind is None:
+                    continue
+                h = (canonical_hash(sql, dialect="sqlite")
+                     if kind in (ObjectKind.VIEW, ObjectKind.TRIGGER) else None)
+                obj = LiveObject(kind, ObjectId(None, name), h)
+                out[obj.key()] = obj
+        return list(out.values())
+
     def add_column_sql(self, table: ObjectId, col: Column) -> str:
         # SQLite has no schemas; ignore the schema qualifier.
         parts = [f"ALTER TABLE {table.name} ADD COLUMN {col.name} {col.type}"]

{dbly-0.0.1 → dbly-0.2.0}/src/dbly/cli.py

@@ -14,7 +14,7 @@ from typing import Optional
 import typer
 from rich.console import Console
 
-from dbly import __version__, hooks, initializer, report
+from dbly import __version__, drift, hooks, initializer, report
 from dbly.adapters import get_adapter
 from dbly.config import resolve_target
 from dbly.engine import detect_dialect
@@ -137,7 +137,7 @@ def apply(
         s.sql for s in plan_obj.steps
         if allow_destructive or s.severity is not Severity.DESTRUCTIVE
     ]
-    if not statements:
+    if not statements and not plan_obj.migrations and not plan_obj.baselined:
         console.print("[green]nothing to apply.[/green]")
         return
 
@@ -147,13 +147,24 @@ def apply(
     try:
         _run_hooks(repo, "pre", py_interpreter)
         adapter.ensure_state_table()
-        adapter.apply(statements)
+        # baseline (bootstrap): record migrations as applied without running them
+        for mid in plan_obj.baselined:
+            adapter.record_migration(plan_obj.to_ref, mid)
+        # explicit migrations run first — they reshape the schema before reconciliation
+        for m in plan_obj.migrations:
+            adapter.run_init_script(m.sql)  # engine-aware multi-statement / PL-SQL runner
+            adapter.record_migration(plan_obj.to_ref, m.id)
+            console.print(f"[magenta]migration[/magenta] applied {m.id}")
+        if statements:
+            adapter.apply(statements)
         adapter.record_deploy(plan_obj.to_ref, migration_ids=[])
         _run_hooks(repo, "post", py_interpreter)
     finally:
         adapter.dispose()
-    console.print(f"[green]applied[/green] {len(statements)} step(s); "
-                  f"deployed ref → {plan_obj.to_ref}")
+    console.print(
+        f"[green]applied[/green] {len(statements)} step(s), "
+        f"{len(plan_obj.migrations)} migration(s); deployed ref → {plan_obj.to_ref}"
+    )
 
 
 @app.command()
@@ -216,15 +227,39 @@ def check(
     target: str = typer.Option(..., "--target"),
     to: str = typer.Option("HEAD", "--to"),
     repo_path: Path = typer.Option(Path("."), "--repo"),
+    orphans: bool = typer.Option(
+        False, "--orphans", help="also report objects in the DB but not in the repo."
+    ),
 ) -> None:
-    """Detect drift: compare desired state at <to> against the live database."""
-    plan_obj = _make_plan(repo_path, target, None, to)
-    drift = [s for s in plan_obj.steps] + plan_obj.warnings
-    if not drift:
-        console.print("[green]no drift — database matches desired state.[/green]")
+    """Detect drift: compare the desired state at <to> against the live database."""
+    repo = Repo(repo_path)
+    cfg = resolve_target(target)
+    dialect = sqlglot_dialect(detect_dialect(cfg))
+    adapter = get_adapter(cfg)
+    try:
+        rep = drift.compute_drift(
+            repo, adapter,
+            to_ref=repo.resolve_ref(to), dialect=dialect, include_orphans=orphans,
+        )
+    finally:
+        adapter.dispose()
+
+    if rep.clean:
+        console.print("[green]no drift — database matches the desired state.[/green]")
         return
-    report.render_plan(plan_obj, console)
-    console.print("\n[yellow]drift detected (see steps/warnings above).[/yellow]")
+
+    for kind, oid in rep.missing:
+        console.print(f"[yellow]missing[/yellow]   {kind.value} {oid}  (in repo, not in DB)")
+    for cd in rep.columns:
+        if cd.added:
+            console.print(f"[yellow]columns[/yellow]   {cd.table}  to add: {', '.join(cd.added)}")
+        if cd.removed:
+            console.print(f"[red]columns[/red]   {cd.table}  only in DB: {', '.join(cd.removed)}")
+    for kind, oid in rep.definitions:
+        console.print(f"[yellow]changed[/yellow]   {kind.value} {oid}  (definition differs — advisory)")
+    for kind, oid in rep.orphaned:
+        console.print(f"[dim]orphaned[/dim]  {kind.value} {oid}  (in DB, not in repo)")
+    raise typer.Exit(code=1)
 
 
 def _run_hooks(repo: Repo, phase: str, py_interpreter: str) -> None:

dbly-0.2.0/src/dbly/drift.py

@@ -0,0 +1,98 @@
+"""Drift detection for ``dbly check`` — desired (repo) vs. live (introspected) state.
+
+Compares the full desired state at a git ref against the database's live inventory and
+reports four kinds of drift:
+
+* **missing**     — in the repo, absent from the DB (would be created on the next apply)
+* **orphaned**    — in the DB, absent from the repo (opt-in via ``--orphans``; on a partially
+                    managed database everything unmanaged shows up here, so it is off by default)
+* **columns**     — tables present in both whose column sets differ
+* **definitions** — procedural objects (view/function/procedure/trigger) whose canonical
+                    source hash differs (advisory — may have false positives, see parsing)
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from dbly import parsing
+from dbly.adapters.base import Adapter
+from dbly.model import ObjectId, ObjectKind
+from dbly.repo import Repo
+
+_HASHED_KINDS = {ObjectKind.VIEW, ObjectKind.FUNCTION, ObjectKind.PROCEDURE, ObjectKind.TRIGGER}
+_LEDGER_KEY = "table:dbly_state"
+
+
+@dataclass(slots=True)
+class ColumnDrift:
+    table: ObjectId
+    added: list[str]    # in the desired CREATE TABLE, missing from the DB
+    removed: list[str]  # in the DB, absent from the desired CREATE TABLE
+
+
+@dataclass(slots=True)
+class DriftReport:
+    missing: list[tuple[ObjectKind, ObjectId]] = field(default_factory=list)
+    orphaned: list[tuple[ObjectKind, ObjectId]] = field(default_factory=list)
+    columns: list[ColumnDrift] = field(default_factory=list)
+    definitions: list[tuple[ObjectKind, ObjectId]] = field(default_factory=list)
+
+    @property
+    def clean(self) -> bool:
+        return not (self.missing or self.orphaned or self.columns or self.definitions)
+
+
+def _norm_key(kind: ObjectKind, oid: ObjectId, default_schema: str | None) -> str:
+    schema = oid.schema
+    if schema and default_schema and schema.lower() == default_schema.lower():
+        schema = None  # an unqualified repo object maps to the engine's implicit schema
+    body = f"{schema.lower()}.{oid.name.lower()}" if schema else oid.name.lower()
+    return f"{kind.value}:{body}"
+
+
+def compute_drift(
+    repo: Repo,
+    adapter: Adapter,
+    *,
+    to_ref: str,
+    dialect: str | None,
+    include_orphans: bool = False,
+) -> DriftReport:
+    ds = adapter.default_schema
+
+    desired = {}  # normalized key -> ParsedObject
+    for rel in repo.list_files(to_ref):
+        sql = repo.read_at(to_ref, rel)
+        for obj in parsing.parse_file(
+            sql, rel, default_schema=repo.schema_for(rel), dialect=dialect
+        ):
+            desired[_norm_key(obj.kind, obj.id, ds)] = obj
+
+    live = {_norm_key(o.kind, o.id, ds): o for o in adapter.inventory()}
+    live.pop(_LEDGER_KEY, None)  # dbly's own ledger is never "orphaned"
+
+    report = DriftReport()
+    for key, obj in desired.items():
+        if key not in live:
+            report.missing.append((obj.kind, obj.id))
+
+    if include_orphans:
+        for key, o in live.items():
+            if key not in desired:
+                report.orphaned.append((o.kind, o.id))
+
+    for key, obj in desired.items():
+        if obj.kind is ObjectKind.TABLE and key in live:
+            actual = {c.key() for c in adapter.get_columns(obj.id.schema, obj.id.name)}
+            want = {c.key() for c in parsing.desired_columns(obj.sql, dialect=dialect)}
+            added, removed = sorted(want - actual), sorted(actual - want)
+            if added or removed:
+                report.columns.append(ColumnDrift(obj.id, added, removed))
+
+    for key, obj in desired.items():
+        if obj.kind in _HASHED_KINDS and key in live and live[key].source_hash:
+            want = parsing.canonical_hash(obj.sql, dialect=dialect)
+            if want and want != live[key].source_hash:
+                report.definitions.append((obj.kind, obj.id))
+
+    return report