sqlpush 0.1.0__tar.gz → 0.3.0__tar.gz

{sqlpush-0.1.0 → sqlpush-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlpush
-Version: 0.1.0
+Version: 0.3.0
 Summary: Schema lifecycle tool for production PostgreSQL/TimescaleDB on SQLAlchemy 2.0 (SQLModel included): diff, push and check schema drift straight from your models
 Keywords: sqlalchemy,alembic,postgresql,timescaledb,prisma,schema,migrations,database,drift,cli
 Author: Juan Miguel Contreras
@@ -29,7 +29,6 @@ Description-Content-Type: text/markdown
 
 # sqlpush
 
-[![CI](https://github.com/juanmicl/sqlpush/actions/workflows/ci.yml/badge.svg?style=for-the-badge)](https://github.com/juanmicl/sqlpush/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/sqlpush?style=for-the-badge)](https://pypi.org/project/sqlpush/)
 [![Python](https://img.shields.io/pypi/pyversions/sqlpush?style=for-the-badge)](https://pypi.org/project/sqlpush/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE)

{sqlpush-0.1.0 → sqlpush-0.3.0}/README.md

@@ -1,6 +1,5 @@
 # sqlpush
 
-[![CI](https://github.com/juanmicl/sqlpush/actions/workflows/ci.yml/badge.svg?style=for-the-badge)](https://github.com/juanmicl/sqlpush/actions/workflows/ci.yml)
 [![PyPI](https://img.shields.io/pypi/v/sqlpush?style=for-the-badge)](https://pypi.org/project/sqlpush/)
 [![Python](https://img.shields.io/pypi/pyversions/sqlpush?style=for-the-badge)](https://pypi.org/project/sqlpush/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge)](LICENSE)

{sqlpush-0.1.0 → sqlpush-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlpush"
-version = "0.1.0"
+version = "0.3.0"
 description = "Schema lifecycle tool for production PostgreSQL/TimescaleDB on SQLAlchemy 2.0 (SQLModel included): diff, push and check schema drift straight from your models"
 readme = "README.md"
 requires-python = ">=3.10"

{sqlpush-0.1.0 → sqlpush-0.3.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlpush"
-version = "0.1.0"
+version = "0.3.0"
 description = "Schema lifecycle tool for production PostgreSQL/TimescaleDB on SQLAlchemy 2.0 (SQLModel included): diff, push and check schema drift straight from your models"
 readme = "README.md"
 authors = [

{sqlpush-0.1.0 → sqlpush-0.3.0}/src/sqlpush/core/classify.py

@@ -8,9 +8,13 @@ DESTRUCTIVE = frozenset({"drop_column", "drop_table", "drop_index", "drop_constr
 
 
 def classify(op_type: str) -> RiskClass:
-    """Standalone add_index targets an EXISTING table
-    (indexes of new tables ride along with add_table), so it is risky:
-    a plain CREATE INDEX takes a SHARE lock that blocks writes."""
+    """add_index renders standalone: on alembic 1.19.1 even plain
+    declared indexes of NEW tables arrive standalone
+    (CreateTableOp.from_table captures columns+constraints, not
+    indexes; only instrumentation-embedded ones ride inside the
+    add_table render, and the diff dedups those away). What survives
+    runs CREATE INDEX alone — a SHARE lock that blocks writes, hence
+    risky."""
     if op_type in DESTRUCTIVE:
         return RiskClass.DESTRUCTIVE
     if op_type in SAFE:

sqlpush-0.3.0/src/sqlpush/core/diff.py

@@ -0,0 +1,409 @@
+"""The ONLY module in sqlpush that imports alembic."""
+
+from __future__ import annotations
+
+import fnmatch
+import io
+from collections.abc import Sequence
+
+from alembic.autogenerate import produce_migrations
+from alembic.migration import MigrationContext
+from alembic.operations import Operations
+from alembic.operations.ops import AlterColumnOp, OpContainer
+from sqlalchemy import MetaData, text
+from sqlalchemy.engine import Engine
+
+from sqlpush.core.classify import classify
+from sqlpush.types import Plan, PlannedOperation
+
+_SYSTEM_SCHEMAS = ("_timescaledb%", "information_schema", "pg_%")
+_SYSTEM_TABLES = ("alembic_version", "spatial_ref_sys")
+
+# Leaf op class -> sqlpush op type. Class names follow alembic 1.19.1
+# autogen output as observed in docs/notes/alembic-notes.md and probes:
+# table create is CreateTableOp (not "AddTableOp"), column modify is
+# AlterColumnOp (not "ModifyColumnOp"), index create is CreateIndexOp,
+# and constraint creates are the concrete Create*ConstraintOp subclasses
+# The AddConstraintOp base class is never emitted as a leaf op.
+# AlterColumnOp is absent ON PURPOSE: its label is derived per-op (see
+# _alter_column_label) because default-only, nullable-only and type
+# changes all arrive as the same class.
+_OP_TYPE = {
+    "CreateTableOp": "add_table",
+    "DropTableOp": "drop_table",
+    "AddColumnOp": "add_column",
+    "DropColumnOp": "drop_column",
+    "CreateIndexOp": "add_index",
+    "DropIndexOp": "drop_index",
+    "CreateUniqueConstraintOp": "add_constraint",
+    "CreateForeignKeyOp": "add_constraint",
+    "CreatePrimaryKeyOp": "add_constraint",
+    "CreateCheckConstraintOp": "add_constraint",
+    "DropConstraintOp": "drop_constraint",
+}
+
+
+def _alter_column_label(op: AlterColumnOp) -> str:
+    """Precise op type for AlterColumnOp (alembic-notes Pattern C).
+
+    Sentinel semantics: ``False`` and ``None`` both mean "leave
+    unchanged"; any other value is the new setting. Default-only and
+    nullable-only drift arrive as AlterColumnOp just like type changes,
+    so disambiguate on the attributes.
+    """
+    if op.modify_server_default not in (False, None):
+        return "modify_default"
+    if op.modify_nullable not in (False, None):
+        return "modify_nullable"
+    return "modify_type"
+
+
+def _is_system_schema(schema: str) -> bool:
+    return any(fnmatch.fnmatch(schema, pat) for pat in _SYSTEM_SCHEMAS)
+
+
+def _extension_owned_schemas(conn) -> frozenset[str]:
+    """Namespaces owned by an installed extension (live server truth).
+
+    Extensions that install into their own namespace (e.g.
+    postgis_topology -> ``topology``) manage it: its objects are
+    extension state, not user metadata. NB: extensions relocated into
+    the default schema (timescaledb, postgis, pg_trgm all live in
+    ``public``) do NOT own it — the default schema stays user scope.
+    """
+    rows = conn.execute(
+        text("SELECT n.nspname FROM pg_extension e JOIN pg_namespace n ON n.oid = e.extnamespace")
+    ).scalars()
+    return frozenset(rows)
+
+
+def _search_path_schemas(conn, default_schema: str, extension_schemas: frozenset[str]) -> list[str]:
+    """Derive the diff scope from the live search_path.
+
+    Same parsing as before (``"$user"`` dropped, whitespace stripped)
+    with one exclusion: extension-owned non-default schemas never enter
+    the scope. They usually appear on the search_path because their
+    extension ``ALTER DATABASE``d it there at install time
+    (postgis_topology does exactly that), not because the user scoped
+    them in. A schema the caller passes explicitly via ``schemas=`` is
+    never filtered here — explicit user intent wins.
+    """
+    # a live PG session always reports a search_path
+    search_path = conn.execute(text("SHOW search_path")).scalar()
+    assert search_path is not None
+    candidates = [s.strip() for s in search_path.split(",") if s.strip() and s.strip() != '"$user"']
+    return [s for s in candidates if s == default_schema or s not in extension_schemas]
+
+
+def _timescale_auto_indexes(conn) -> dict[str, set[str]]:
+    """``{schema.index_name}`` -> set of ``{schema.hypertable}`` owners.
+
+    TimescaleDB's implicit per-hypertable time-column index
+    (``<hypertable>_<dimension>_idx``). Set-valued: distinct hypertables
+    can produce the SAME index name (table ``a`` dim ``b_c`` vs table
+    ``a_b`` dim ``c`` both yield ``a_b_c_idx``) — a str value would
+    last-win and leak the other as false drift. Qualified keys carry
+    cross-schema hypertables. Empty when the extension is absent.
+    """
+    installed = conn.execute(
+        text("SELECT 1 FROM pg_extension WHERE extname = 'timescaledb'")
+    ).first()
+    if installed is None:
+        return {}
+    rows = conn.execute(
+        text(
+            "SELECT hypertable_schema, hypertable_name, primary_dimension "
+            "FROM timescaledb_information.hypertables"
+        )
+    ).all()
+    out: dict[str, set[str]] = {}
+    for schema, hypertable, dimension in rows:
+        out.setdefault(f"{schema}.{hypertable}_{dimension}_idx", set()).add(
+            f"{schema}.{hypertable}"
+        )
+    return out
+
+
+def _spatial_auto_indexes(conn) -> frozenset[str]:
+    """Qualified names of geoalchemy2-style implicit spatial indexes.
+
+    Single-column indexes named ``<table>_<col>_idx`` on a geometry or
+    geography column — what geoalchemy2 (<0.18 or ``spatial_index=True``)
+    creates at table-create time and no model ever declares. Catalog-driven
+    (pg_type), so detection never depends on geoalchemy2 being importable
+    in this process.
+    """
+    rows = conn.execute(
+        text(
+            "SELECT n.nspname, i2.relname "
+            "FROM pg_index i "
+            "JOIN pg_class t ON t.oid = i.indrelid "
+            "JOIN pg_namespace n ON n.oid = t.relnamespace "
+            "JOIN pg_attribute a ON a.attrelid = t.oid AND a.attnum = ANY(i.indkey) "
+            "JOIN pg_class i2 ON i2.oid = i.indexrelid "
+            "JOIN pg_type ty ON ty.oid = a.atttypid "
+            "WHERE i.indnatts = 1 "
+            "AND ty.typname IN ('geometry', 'geography') "
+            "AND i2.relname = format('%s_%s_idx', t.relname, a.attname)"
+        )
+    ).all()
+    return frozenset(f"{nsp}.{idx}" for nsp, idx in rows)
+
+
+def _restrict_search_path(conn, default_schema: str, schemas: frozenset[str]) -> str | None:
+    """Confine the default-schema reflection pass to the default schema.
+
+    Alembic's unqualified (None-schema) reflection pass resolves table
+    names via ``pg_table_is_visible``, i.e. the SESSION search_path —
+    which ambient database-level settings can stretch beyond the
+    declared scope (postgis_topology ``ALTER DATABASE``s its own
+    namespace onto the search_path; its tables then surface both
+    unqualified and schema-qualified — one object, two drop ops).
+    ``pg_table_is_visible`` cannot deliver "reflection sees exactly
+    what the scope says" for a multi-schema scope: pinning the full
+    scope list would let the None-pass resolve NON-default tables as
+    unqualified default-schema tables — false destructive drops plus
+    duplicate unqualified drops in mixed scopes. So pin to the default
+    schema alone, and only when it is a scope member; otherwise the
+    None-pass is filtered out by ``_make_include_name`` before
+    reflection runs, so there is nothing visibility-based to confine
+    and no pin (nor restore) happens. Schema-qualified reflection is
+    unaffected either way. Returns the original setting for
+    :func:`_restore_search_path`, or ``None`` when nothing was pinned.
+    """
+    if default_schema not in schemas:
+        return None
+    original = conn.execute(text("SHOW search_path")).scalar()
+    assert original is not None
+    preparer = conn.dialect.identifier_preparer
+    conn.exec_driver_sql(f"SET search_path TO {preparer.quote(default_schema)}")
+    return original
+
+
+def _restore_search_path(conn, original: str | None) -> None:
+    # original None => nothing was pinned, nothing to restore.
+    if original is None:
+        return
+    # SET is session-level and survives ROLLBACK: a pooled connection
+    # must never hand the restricted path to its next borrower. The
+    # value is SHOW's own output — already a valid identifier list —
+    # so round-tripping it verbatim is safe.
+    try:
+        conn.exec_driver_sql(f"SET search_path TO {original}")
+    except Exception:  # noqa: BLE001
+        # A dead connection cannot be restored, and a restore failure must
+        # NEVER mask the root error from produce_migrations. A LIVE pooled
+        # connection whose restore failed must be discarded, not returned
+        # to the pool still carrying the restricted path (SET survives
+        # ROLLBACK) — hence invalidate(), which forces the pool to drop
+        # it transparently. Server-side session teardown drops the
+        # restricted path anyway.
+        conn.invalidate()
+
+
+def _make_include_name(schemas: frozenset[str], default_schema: str):
+    def include_name(name, type_, parent_names):
+        # Prune schemas (and everything inside them) BEFORE reflection:
+        # system catalogs (timescale et al.) are then never reflected at
+        # all. Schema filtering routes through include_name: alembic
+        # 1.19 never calls include_object with type_ == "schema", and
+        # its return value must be a real bool (falsy = exclude).
+        # NB: alembic substitutes None for the default schema name in
+        # the schema pass (compare/schema.py), so map None back.
+        if type_ == "schema":
+            schema = default_schema if name is None else name
+        else:
+            schema = parent_names.get("schema_name") or default_schema
+        return schema in schemas and not _is_system_schema(schema)
+
+    return include_name
+
+
+def _make_include(
+    schemas: frozenset[str],
+    default_schema: str,
+    ts_auto_indexes: dict[str, set[str]],
+    spatial_auto_indexes: frozenset[str],
+):
+    def include_object(obj, name, type_, reflected, compare_to):
+        # Bound the diff to the target schemas on every branch: derive
+        # the object's effective schema and require membership, for
+        # reflected-only, metadata-only and both-present objects alike.
+        # Column/Index/Constraint objects have no `.schema` of their own
+        # (SQLAlchemy 2.0.52): they resolve it through the parent table.
+        schema = (
+            getattr(obj, "schema", None)
+            or getattr(getattr(obj, "table", None), "schema", None)
+            or default_schema
+        )
+        if schema not in schemas or _is_system_schema(schema):
+            return False
+        if reflected and compare_to is None:
+            # DB-only object: skip system tables. NB: alembic also
+            # auto-excludes its own version table from autogen; the
+            # name check here is defense in depth.
+            if name in _SYSTEM_TABLES:
+                return False
+            # Skip TimescaleDB's implicit time-column index: extension
+            # state no model declares. Qualified name AND owner set must
+            # both match, so a same-named index on another table stays
+            # real drift, as does one the metadata actually declares
+            # (that arrives in the both-present branch above).
+            parent = getattr(obj, "table", None)
+            parent_table = getattr(parent, "name", None)
+            parent_schema = getattr(parent, "schema", None) or default_schema
+            qualified_index = f"{parent_schema}.{name}"
+            qualified_parent = f"{parent_schema}.{parent_table}"
+            if type_ == "index" and qualified_index in spatial_auto_indexes:
+                return False
+            owners = ts_auto_indexes.get(qualified_index, frozenset())
+            return not (type_ == "index" and qualified_parent in owners)
+        return True
+
+    return include_object
+
+
+def _flatten(ops):
+    # D1 (alembic-notes): ops targeting existing tables arrive wrapped in
+    # ModifyTableOps containers; Operations.invoke crashes on containers,
+    # so recurse into anything that is an OpContainer before invoking.
+    for op in ops:
+        if isinstance(op, OpContainer):
+            yield from _flatten(op.ops)
+        else:
+            yield op
+
+
+def _dedup_embedded_indexes(ops: list[PlannedOperation]) -> list[PlannedOperation]:
+    """Drop standalone ``add_index`` ops already embedded in an ``add_table`` render.
+
+    On alembic 1.19.1 ``CreateTableOp.from_table`` captures columns and
+    constraints only, NOT indexes: a plain declared ``Index(...)`` on a
+    new table never reaches the create render — it arrives
+    standalone-only and is untouched here. The embedding this dedup
+    targets happens when the table carries instrumentation-appended
+    indexes (geoalchemy2-style listeners attaching at Table
+    construction): ``to_table()`` reconstruction re-fires the
+    attachment, the rebuilt table carries the index again, the offline
+    create render embeds it, and autogen ALSO emits the standalone
+    CreateIndexOp — executing both is a guaranteed duplicate-object
+    failure (push fire-test F1/F2: the renders are byte-identical and
+    the second execution collides with 42P07). Suppression side: the
+    standalone op is the redundant one — its statement already runs
+    inside the add_table op, whose render embeds it verbatim; the
+    embedded copy has no other carrier op. Exact-statement containment
+    is safe: both renders come from the same renderer over the same
+    Index objects, so an embedded index matches its standalone op
+    byte-for-byte while a different index's statement cannot be a
+    substring of the create-table render (statement text runs to its
+    own terminator). Known limitation: the keys are bare table names,
+    so two NEW tables sharing a bare name across schemas under-dedup
+    (last-wins in the dict) — containment is SQL-qualified either way,
+    so no wrong suppression is possible.
+    """
+    table_renders = {op.table: op.sql for op in ops if op.type == "add_table"}
+    return [
+        op
+        for op in ops
+        if not (
+            op.type == "add_index"
+            and op.table in table_renders
+            and op.sql.strip() in table_renders[op.table]
+        )
+    ]
+
+
+def _render_op_sql(op, engine: Engine) -> str:
+    buf = io.StringIO()
+    offline = MigrationContext.configure(
+        dialect=engine.dialect, opts={"as_sql": True, "output_buffer": buf}
+    )
+    operations = Operations(offline)
+    operations.invoke(op)
+    # offline render terminates each op with ";\n\n"; normalize so each
+    # PlannedOperation.sql is a single clean statement
+    return buf.getvalue().strip().rstrip(";")
+
+
+class DiffEngine:
+    def plan(
+        self,
+        metadata: MetaData,
+        engine: Engine,
+        *,
+        schemas: Sequence[str] | None = None,
+        exclude: Sequence[str] = (),
+    ) -> Plan:
+        exclude = tuple(exclude)
+        # Typed `str | None` by SQLAlchemy; a dialect without a default
+        # schema is meaningless for this PostgreSQL-only tool; "public"
+        # matches every supported server config.
+        default_schema = engine.dialect.default_schema_name or "public"
+
+        # One connection for the whole plan: the scope derivation, the
+        # catalog probes and the reflection must all see the same
+        # session — the search_path pinning below would be meaningless
+        # on a second connection.
+        with engine.connect() as conn:
+            if schemas is None:
+                schemas = _search_path_schemas(conn, default_schema, _extension_owned_schemas(conn))
+            # New binding rather than a param reassignment: frozenset is
+            # a Set, not a Sequence, and the helpers below declare the
+            # exact type they take.
+            schema_set = frozenset(schemas)
+            ts_auto_indexes = _timescale_auto_indexes(conn)
+            spatial_auto_indexes = _spatial_auto_indexes(conn)
+
+            opts = {
+                "compare_type": True,
+                "compare_server_default": True,
+                "include_name": _make_include_name(schema_set, default_schema),
+                "include_object": _make_include(
+                    schema_set, default_schema, ts_auto_indexes, spatial_auto_indexes
+                ),
+                "include_schemas": True,
+            }
+            original_search_path = _restrict_search_path(conn, default_schema, schema_set)
+            try:
+                ctx = MigrationContext.configure(conn, opts=opts)
+                script = produce_migrations(ctx, metadata)
+            finally:
+                _restore_search_path(conn, original_search_path)
+
+        # produce_migrations always builds the upgrade bundle
+        assert script.upgrade_ops is not None
+        ops: list[PlannedOperation] = []
+        for op in _flatten(script.upgrade_ops.ops):
+            ops.extend(self._translate(op, engine, exclude))
+        ops = _dedup_embedded_indexes(ops)
+        return Plan(operations=tuple(ops))
+
+    def _translate(self, op, engine: Engine, exclude: tuple[str, ...]) -> list[PlannedOperation]:
+        op_type = _OP_TYPE.get(type(op).__name__, "raw_sql")
+        if isinstance(op, AlterColumnOp):
+            op_type = _alter_column_label(op)
+        sql_text = _render_op_sql(op, engine)
+        table = getattr(getattr(op, "table", None), "name", None) or getattr(op, "table_name", None)
+        # AddColumnOp carries a real Column in `.column`; DropColumnOp and
+        # AlterColumnOp only expose the plain string `column_name`
+        # (alembic-notes op reference).
+        column = getattr(getattr(op, "column", None), "name", None) or getattr(
+            op, "column_name", None
+        )
+        # table-level patterns reach column-level ops too; a qualified
+        # table.column pattern suppresses only that specific column op
+        if table and any(fnmatch.fnmatch(table, pat) for pat in exclude):
+            return []
+        if table and column:
+            full = f"{table}.{column}"
+            if any(fnmatch.fnmatch(full, pat) for pat in exclude):
+                return []
+        return [
+            PlannedOperation(
+                type=op_type,
+                risk=classify(op_type),
+                sql=sql_text,
+                table=table,
+                column=column,
+            )
+        ]

{sqlpush-0.1.0 → sqlpush-0.3.0}/src/sqlpush/directives/timescale.py

@@ -9,15 +9,15 @@ from sqlpush.annotations import HYPERTABLE_KEY
 from sqlpush.types import PlannedOperation, RiskClass
 
 
-def _is_hypertable(conn: Connection, table_name: str) -> bool:
+def _is_hypertable(conn: Connection, schema: str, table_name: str) -> bool:
     try:
         return bool(
             conn.execute(
                 text(
                     "SELECT 1 FROM timescaledb_information.hypertables "
-                    "WHERE hypertable_name = :name"
+                    "WHERE hypertable_schema = :schema AND hypertable_name = :name"
                 ),
-                {"name": table_name},
+                {"schema": schema, "name": table_name},
             ).scalar()
         )
     except ProgrammingError:
@@ -50,12 +50,22 @@ def hypertable_operations(
         table for table in metadata.tables.values() if table.info.get(HYPERTABLE_KEY) is not None
     ]
     if engine is not None and pending:
+        default_schema = engine.dialect.default_schema_name or "public"
         with engine.connect() as conn:
-            pending = [t for t in pending if not _is_hypertable(conn, t.name)]
+            pending = [
+                t for t in pending if not _is_hypertable(conn, t.schema or default_schema, t.name)
+            ]
     ops: list[PlannedOperation] = []
     for table in pending:
         info = table.info[HYPERTABLE_KEY]
-        name = _lit(table.name)
+        # Schema-qualified relation: create_hypertable resolves an
+        # unqualified name via the session search_path, so a table in a
+        # non-default schema MUST carry its schema or the op lands on
+        # public.<name> (UndefinedTable). Schema-less tables keep the
+        # bare name: they live in the default schema, which the
+        # search_path already resolves.
+        relation = table.name if table.schema is None else f"{table.schema}.{table.name}"
+        name = _lit(relation)
         time_column = _lit(info.time_column)
         parts = [f"SELECT create_hypertable('{name}', '{time_column}'"]
         if info.chunk_time_interval:

sqlpush-0.1.0/src/sqlpush/core/diff.py

@@ -1,205 +0,0 @@
-"""The ONLY module in sqlpush that imports alembic."""
-
-from __future__ import annotations
-
-import fnmatch
-import io
-from collections.abc import Sequence
-
-from alembic.autogenerate import produce_migrations
-from alembic.migration import MigrationContext
-from alembic.operations import Operations
-from alembic.operations.ops import AlterColumnOp, OpContainer
-from sqlalchemy import MetaData, text
-from sqlalchemy.engine import Engine
-
-from sqlpush.core.classify import classify
-from sqlpush.types import Plan, PlannedOperation
-
-_SYSTEM_SCHEMAS = ("_timescaledb%", "information_schema", "pg_%")
-_SYSTEM_TABLES = ("alembic_version", "spatial_ref_sys")
-
-# Leaf op class -> sqlpush op type. Class names follow alembic 1.19.1
-# autogen output as observed in docs/notes/alembic-notes.md and probes:
-# table create is CreateTableOp (not "AddTableOp"), column modify is
-# AlterColumnOp (not "ModifyColumnOp"), index create is CreateIndexOp,
-# and constraint creates are the concrete Create*ConstraintOp subclasses
-# The AddConstraintOp base class is never emitted as a leaf op.
-# AlterColumnOp is absent ON PURPOSE: its label is derived per-op (see
-# _alter_column_label) because default-only, nullable-only and type
-# changes all arrive as the same class.
-_OP_TYPE = {
-    "CreateTableOp": "add_table",
-    "DropTableOp": "drop_table",
-    "AddColumnOp": "add_column",
-    "DropColumnOp": "drop_column",
-    "CreateIndexOp": "add_index",
-    "DropIndexOp": "drop_index",
-    "CreateUniqueConstraintOp": "add_constraint",
-    "CreateForeignKeyOp": "add_constraint",
-    "CreatePrimaryKeyOp": "add_constraint",
-    "CreateCheckConstraintOp": "add_constraint",
-    "DropConstraintOp": "drop_constraint",
-}
-
-
-def _alter_column_label(op: AlterColumnOp) -> str:
-    """Precise op type for AlterColumnOp (alembic-notes Pattern C).
-
-    Sentinel semantics: ``False`` and ``None`` both mean "leave
-    unchanged"; any other value is the new setting. Default-only and
-    nullable-only drift arrive as AlterColumnOp just like type changes,
-    so disambiguate on the attributes.
-    """
-    if op.modify_server_default not in (False, None):
-        return "modify_default"
-    if op.modify_nullable not in (False, None):
-        return "modify_nullable"
-    return "modify_type"
-
-
-def _is_system_schema(schema: str) -> bool:
-    return any(fnmatch.fnmatch(schema, pat) for pat in _SYSTEM_SCHEMAS)
-
-
-def _make_include_name(schemas: frozenset[str], default_schema: str):
-    def include_name(name, type_, parent_names):
-        # Prune schemas (and everything inside them) BEFORE reflection:
-        # system catalogs (timescale et al.) are then never reflected at
-        # all. Schema filtering routes through include_name: alembic
-        # 1.19 never calls include_object with type_ == "schema", and
-        # its return value must be a real bool (falsy = exclude).
-        # NB: alembic substitutes None for the default schema name in
-        # the schema pass (compare/schema.py), so map None back.
-        if type_ == "schema":
-            schema = default_schema if name is None else name
-        else:
-            schema = parent_names.get("schema_name") or default_schema
-        return schema in schemas and not _is_system_schema(schema)
-
-    return include_name
-
-
-def _make_include(schemas: frozenset[str], default_schema: str):
-    def include_object(obj, name, type_, reflected, compare_to):
-        # Bound the diff to the target schemas on every branch: derive
-        # the object's effective schema and require membership, for
-        # reflected-only, metadata-only and both-present objects alike.
-        # Column/Index/Constraint objects have no `.schema` of their own
-        # (SQLAlchemy 2.0.52): they resolve it through the parent table.
-        schema = (
-            getattr(obj, "schema", None)
-            or getattr(getattr(obj, "table", None), "schema", None)
-            or default_schema
-        )
-        if schema not in schemas or _is_system_schema(schema):
-            return False
-        if reflected and compare_to is None:
-            # DB-only object: skip system tables. NB: alembic also
-            # auto-excludes its own version table from autogen; the
-            # name check here is defense in depth.
-            return name not in _SYSTEM_TABLES
-        return True
-
-    return include_object
-
-
-def _flatten(ops):
-    # D1 (alembic-notes): ops targeting existing tables arrive wrapped in
-    # ModifyTableOps containers; Operations.invoke crashes on containers,
-    # so recurse into anything that is an OpContainer before invoking.
-    for op in ops:
-        if isinstance(op, OpContainer):
-            yield from _flatten(op.ops)
-        else:
-            yield op
-
-
-def _render_op_sql(op, engine: Engine) -> str:
-    buf = io.StringIO()
-    offline = MigrationContext.configure(
-        dialect=engine.dialect, opts={"as_sql": True, "output_buffer": buf}
-    )
-    operations = Operations(offline)
-    operations.invoke(op)
-    # offline render terminates each op with ";\n\n"; normalize so each
-    # PlannedOperation.sql is a single clean statement
-    return buf.getvalue().strip().rstrip(";")
-
-
-class DiffEngine:
-    def plan(
-        self,
-        metadata: MetaData,
-        engine: Engine,
-        *,
-        schemas: Sequence[str] | None = None,
-        exclude: Sequence[str] = (),
-    ) -> Plan:
-        if schemas is None:
-            with engine.connect() as conn:
-                search_path = conn.execute(text("SHOW search_path")).scalar()
-                # a live PG session always reports a search_path
-                assert search_path is not None
-                schemas = [
-                    s.strip()
-                    for s in search_path.split(",")
-                    if s.strip() and s.strip() != '"$user"'
-                ]
-        # New binding rather than a param reassignment: frozenset is a
-        # Set, not a Sequence, and the helpers below declare the exact
-        # type they take.
-        schema_set = frozenset(schemas)
-        exclude = tuple(exclude)
-        # Typed `str | None` by SQLAlchemy; a dialect without a default
-        # schema is meaningless for this PostgreSQL-only tool; "public"
-        # matches every supported server config.
-        default_schema = engine.dialect.default_schema_name or "public"
-
-        opts = {
-            "compare_type": True,
-            "compare_server_default": True,
-            "include_name": _make_include_name(schema_set, default_schema),
-            "include_object": _make_include(schema_set, default_schema),
-            "include_schemas": True,
-        }
-        with engine.connect() as conn:
-            ctx = MigrationContext.configure(conn, opts=opts)
-            script = produce_migrations(ctx, metadata)
-
-        # produce_migrations always builds the upgrade bundle
-        assert script.upgrade_ops is not None
-        ops: list[PlannedOperation] = []
-        for op in _flatten(script.upgrade_ops.ops):
-            ops.extend(self._translate(op, engine, exclude))
-        return Plan(operations=tuple(ops))
-
-    def _translate(self, op, engine: Engine, exclude: tuple[str, ...]) -> list[PlannedOperation]:
-        op_type = _OP_TYPE.get(type(op).__name__, "raw_sql")
-        if isinstance(op, AlterColumnOp):
-            op_type = _alter_column_label(op)
-        sql_text = _render_op_sql(op, engine)
-        table = getattr(getattr(op, "table", None), "name", None) or getattr(op, "table_name", None)
-        # AddColumnOp carries a real Column in `.column`; DropColumnOp and
-        # AlterColumnOp only expose the plain string `column_name`
-        # (alembic-notes op reference).
-        column = getattr(getattr(op, "column", None), "name", None) or getattr(
-            op, "column_name", None
-        )
-        # table-level patterns reach column-level ops too; a qualified
-        # table.column pattern suppresses only that specific column op
-        if table and any(fnmatch.fnmatch(table, pat) for pat in exclude):
-            return []
-        if table and column:
-            full = f"{table}.{column}"
-            if any(fnmatch.fnmatch(full, pat) for pat in exclude):
-                return []
-        return [
-            PlannedOperation(
-                type=op_type,
-                risk=classify(op_type),
-                sql=sql_text,
-                table=table,
-                column=column,
-            )
-        ]