sqlpush 0.4.0__tar.gz → 0.4.2__tar.gz

{sqlpush-0.4.0 → sqlpush-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlpush
-Version: 0.4.0
+Version: 0.4.2
 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

{sqlpush-0.4.0 → sqlpush-0.4.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "sqlpush"
-version = "0.4.0"
+version = "0.4.2"
 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.4.0 → sqlpush-0.4.2}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "sqlpush"
-version = "0.4.0"
+version = "0.4.2"
 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.4.2/src/sqlpush/annotations.py

@@ -0,0 +1,103 @@
+# src/sqlpush/annotations.py
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+HYPERTABLE_KEY = "sqlpush_hypertable"
+
+
+@dataclass(frozen=True)
+class HypertableInfo:
+    time_column: str
+    chunk_time_interval: str | None = None
+
+
+def _lit(value: str) -> str:
+    # single-quoted SQL literal escaping: ' -> '' (defense in depth
+    # against quote break-out via table/column names from user metadata)
+    return value.replace("'", "''")
+
+
+def create_hypertable_sql(table_name: str, schema: str | None, info: HypertableInfo) -> str:
+    """Render the idempotent ``create_hypertable`` statement for an annotated table.
+
+    Single source of truth shared by the directive planner
+    (``directives/timescale.py`` — push/revision) and the decorator's
+    ``after_create`` listener (``create_all``): both mechanisms must
+    always emit identical SQL.
+    """
+    # 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 schema is None else f"{schema}.{table_name}"
+    parts = [f"SELECT create_hypertable('{_lit(relation)}', '{_lit(info.time_column)}'"]
+    if info.chunk_time_interval:
+        parts.append(f", chunk_time_interval => INTERVAL '{_lit(info.chunk_time_interval)}'")
+    # if_not_exists: race insurance between state checks and apply —
+    # and what makes listener (create_all) + directive (push) coexistence
+    # duplicate-free. migrate_data: required when the directive runs on an
+    # existing populated table; a no-op on the empty table the listener
+    # just created. create_default_indexes=false: timescale's implicit
+    # time-column index is invisible to metadata, so the default would
+    # drift forever (destructive drop_index) on a fully synced schema;
+    # users declare wanted indexes in the Table instead (metadata is the
+    # source of truth).
+    parts.append(", migrate_data => true, if_not_exists => true, create_default_indexes => false)")
+    return "".join(parts)
+
+
+def _listen_after_create(table, info: HypertableInfo) -> None:
+    # Dual-mechanism (0.4.1): besides the info entry (planned from
+    # metadata on push/revision paths), register an after_create
+    # listener so create_all paths register the hypertable too —
+    # the same idempotent SQL the directive plans, executed via
+    # text() exactly like the executor runs planned ops. With a
+    # declared index on the time column, create_hypertable sees the
+    # column indexed and create_default_indexes => false adds nothing
+    # (see tests/test_annotations_createall.py).
+    # Imports stay inside the function: this module must remain free of
+    # heavy imports at module level (pinned by test_annotations.py).
+    from sqlalchemy import event, text
+
+    sql = create_hypertable_sql(table.name, table.schema, info)
+
+    def _after_create(target, connection, **kw):
+        connection.execute(text(sql))
+
+    event.listen(table, "after_create", _after_create)
+
+
+def hypertable(*, time_column: str, chunk_time_interval: str | None = None):
+    """Record hypertable intent on the model's Table (dual-mechanism).
+
+    Works with SQLModel, Flask-SQLAlchemy and plain declarative, anything
+    whose class already carries a built ``__table__`` when decorated.
+
+    Mechanism 1 (metadata): the annotation is recorded on ``Table.info``
+    and planned as a ``create_hypertable`` op by push/revision.
+
+    Mechanism 2 (create_all): an ``after_create`` listener runs the same
+    idempotent ``create_hypertable``, so ``MetaData.create_all`` paths
+    register the hypertable too; coexistence with a later push is
+    duplicate-free (``if_not_exists``) and ``check()`` stays clean.
+
+    The generated ``create_hypertable`` runs with
+    ``create_default_indexes => false``: timescale's implicit time-column
+    index is invisible to metadata and would drift forever. Declare it
+    yourself (``Index(..., "<time_column>")`` on the model) if you rely
+    on it for time-range scans.
+    """
+
+    def decorator(cls):
+        table = getattr(cls, "__table__", None)
+        if table is None:
+            raise TypeError(f"{cls.__name__} has no __table__; decorate a mapped class")
+        info = HypertableInfo(time_column=time_column, chunk_time_interval=chunk_time_interval)
+        table.info[HYPERTABLE_KEY] = info
+        _listen_after_create(table, info)
+        return cls
+
+    return decorator

{sqlpush-0.4.0 → sqlpush-0.4.2}/src/sqlpush/api.py

@@ -139,7 +139,12 @@ def revision(
     risk = max((op.risk for op in p.operations), key=lambda r: RISK_RANK[r])
     ops = [(f"[{op.risk.name}] {op.type} {op.table or '?'}", op.sql) for op in p.operations]
     out = Path(out_dir)
-    out.mkdir(parents=True, exist_ok=True)
+    try:
+        out.mkdir(parents=True, exist_ok=True)
+    except OSError as exc:
+        # same typing as the write below: only SqlpushError subclasses
+        # escape the API surface (e.g. out_dir under a file)
+        raise SqlpushError(f"cannot create migrations directory {out}: {exc}") from exc
     rev_id = next_revision_id(out)
     slug = re.sub(r"[^a-z0-9_]+", "_", (message or "migration").lower())[:40]
     path = out / f"{rev_id}_{slug}.sql"
@@ -163,16 +168,32 @@ def revision(
     return path
 
 
-def migrate(target, *, chain_dir="migrations/versions", allow_destructive=False) -> MigrateReport:
+def migrate(
+    target,
+    *,
+    chain_dir="migrations/versions",
+    allow_destructive=False,
+    advisory_wait=30.0,
+    lock_timeout=5.0,
+) -> MigrateReport:
     """Replay annotated-SQL chain files with gates + same-txn bookkeeping.
 
     ``target`` is a DSN string, sync ``Engine`` or ``AsyncEngine`` (resolved
-    via ``_sync_engine_from``; engines created here are disposed). See
+    via ``_sync_engine_from``; engines created here are disposed).
+    ``advisory_wait`` bounds the advisory-lock wait and ``lock_timeout``
+    bounds each per-file transaction's lock wait (seconds; 0 = fail
+    immediately — same contract as ``push``). See
     ``chain.migrate.run_migrate`` for the execution contract.
     """
     engine, dispose = _sync_engine_from(target)
     try:
-        return run_migrate(engine, chain_dir=chain_dir, allow_destructive=allow_destructive)
+        return run_migrate(
+            engine,
+            chain_dir=chain_dir,
+            allow_destructive=allow_destructive,
+            advisory_wait=advisory_wait,
+            lock_timeout=lock_timeout,
+        )
     except SQLAlchemyError as exc:
         # MigrationFileError/SqlpushError (typed) pass through untouched
         _raise_typed(exc)
@@ -181,16 +202,19 @@ def migrate(target, *, chain_dir="migrations/versions", allow_destructive=False)
             engine.dispose()
 
 
-def stamp(target, *, chain_dir="migrations/versions") -> MigrateReport:
+def stamp(target, *, chain_dir="migrations/versions", force: bool = False) -> MigrateReport:
     """Bootstrap: register chain files as applied WITHOUT executing SQL.
 
-    For adopting a DB whose schema already reflects the chain. ``target``
-    resolution and error typing match :func:`migrate`. See
-    ``chain.migrate.run_stamp`` for the report convention.
+    For adopting a DB whose schema already reflects the chain. A file
+    already registered with a different checksum (edited after apply)
+    is refused unless ``force`` is set — edit detection survives
+    re-stamping. ``target`` resolution and error typing match
+    :func:`migrate`. See ``chain.migrate.run_stamp`` for the report
+    convention.
     """
     engine, dispose = _sync_engine_from(target)
     try:
-        return run_stamp(engine, chain_dir=chain_dir)
+        return run_stamp(engine, chain_dir=chain_dir, force=force)
     except SQLAlchemyError as exc:
         # MigrationFileError/SqlpushError (typed) pass through untouched
         _raise_typed(exc)
@@ -199,18 +223,35 @@ def stamp(target, *, chain_dir="migrations/versions") -> MigrateReport:
             engine.dispose()
 
 
+def _translate_asyncpg(url):
+    """Map a ``postgresql+asyncpg`` URL onto the sync psycopg driver.
+
+    An asyncpg URL cannot back a SYNC engine (the dialect is
+    async-only), but psycopg is a runtime dependency — the translated
+    engine actually connects. asyncpg itself is never required in this
+    process. Everything but the driver (host/db/credentials/query
+    options) is preserved via the URL API, no string surgery.
+    """
+    if url.drivername == "postgresql+asyncpg":
+        return url.set(drivername="postgresql+psycopg")
+    return url
+
+
 def _sync_engine_from(target):
     if isinstance(target, AsyncEngine):
         from sqlalchemy import create_engine
         from sqlalchemy.pool import NullPool
 
-        dsn = target.url.render_as_string(hide_password=False)
-        return create_engine(dsn, poolclass=NullPool), True
+        dsn = _translate_asyncpg(target.url)
+        return create_engine(dsn.render_as_string(hide_password=False), poolclass=NullPool), True
     if isinstance(target, str):
         from sqlalchemy import create_engine
+        from sqlalchemy.engine import make_url
         from sqlalchemy.pool import NullPool
 
-        return create_engine(target, poolclass=NullPool), True
+        # make_url raises the same ArgumentError a bad DSN would raise
+        # inside create_engine — error typing downstream is unchanged
+        return create_engine(_translate_asyncpg(make_url(target)), poolclass=NullPool), True
     return target, False
 
 

{sqlpush-0.4.0 → sqlpush-0.4.2}/src/sqlpush/chain/migrate.py

@@ -11,13 +11,15 @@ let a crash between apply and registry re-apply the file forever
 
 Fail-loud ordering: any blocked file (parse error, checksum mismatch,
 destructive gate, SQL failure) stops the chain — nothing later runs (R4).
-A hung migrate (stuck waiting on the advisory lock) is diagnosed via
-pg_locks / pg_stat_activity.
+The advisory lock wait is BOUNDED (--advisory-wait, default 30s): an
+exhausted budget raises a typed error instead of hanging on a stuck
+holder — diagnose the holder via pg_locks / pg_stat_activity.
 """
 
 from __future__ import annotations
 
 import contextlib
+import time
 from collections.abc import Iterator
 from pathlib import Path
 
@@ -26,7 +28,7 @@ from sqlalchemy.engine import Connection, Engine
 
 from sqlpush.apply.executor import advisory_key
 from sqlpush.chain.format import MigrationFileError, checksum, parse_migration_file
-from sqlpush.types import MigrateReport, RiskClass
+from sqlpush.types import MigrateReport, RiskClass, SqlpushError
 
 _VERSIONS_DDL = (
     "CREATE TABLE IF NOT EXISTS public.sqlpush_versions ("
@@ -45,18 +47,33 @@ def _chain_files(chain_dir: str | Path) -> list[Path]:
 
 
 @contextlib.contextmanager
-def _chain_session(engine: Engine) -> Iterator[Connection]:
+def _chain_session(engine: Engine, *, advisory_wait: float = 30.0) -> Iterator[Connection]:
     """Session-scoped advisory lock + versions table, shared by every verb.
 
     Same key derivation as push (fnv1a_32(b"sqlpush") ^ db oid): serializes
     concurrent chain workers and excludes push on the same database. The
-    txn opened by the key query is committed right away — session advisory
-    locks survive COMMIT/ROLLBACK, and an idle-in-transaction session is
-    exposed to idle_in_transaction_session_timeout (executor.py note).
+    wait is BOUNDED, mirroring executor.with_advisory_lock:
+    ``pg_try_advisory_lock`` polled every 0.5 s against a
+    ``time.monotonic()`` deadline; an exhausted budget raises
+    :class:`SqlpushError` — a blocking ``pg_advisory_lock`` would hang
+    forever on a stuck holder. The txn opened by the key/probe queries
+    is committed right away — session advisory locks survive
+    COMMIT/ROLLBACK, and an idle-in-transaction session is exposed to
+    idle_in_transaction_session_timeout (executor.py note).
     """
+    if advisory_wait < 0:
+        raise SqlpushError(f"advisory_wait must be >= 0, got {advisory_wait}")
     with engine.connect() as conn:
         key = advisory_key(conn)
-        conn.execute(text("SELECT pg_advisory_lock(:k)"), {"k": key})
+        deadline = time.monotonic() + advisory_wait
+        locked = conn.execute(text("SELECT pg_try_advisory_lock(:k)"), {"k": key}).scalar()
+        while not locked and time.monotonic() < deadline:
+            time.sleep(0.5)
+            locked = conn.execute(text("SELECT pg_try_advisory_lock(:k)"), {"k": key}).scalar()
+        if not locked:
+            raise SqlpushError(
+                f"another sqlpush worker holds the advisory lock after {advisory_wait}s"
+            )
         conn.commit()
         try:
             conn.execute(text(_VERSIONS_DDL))
@@ -73,14 +90,26 @@ def _chain_session(engine: Engine) -> Iterator[Connection]:
                     conn.commit()
 
 
-def run_migrate(engine: Engine, *, chain_dir: str | Path, allow_destructive: bool) -> MigrateReport:
+def run_migrate(
+    engine: Engine,
+    *,
+    chain_dir: str | Path,
+    allow_destructive: bool,
+    advisory_wait: float = 30.0,
+    lock_timeout: float = 5.0,
+) -> MigrateReport:
+    if lock_timeout < 0:
+        # same contract as push (executor.with_advisory_lock): budgets
+        # are typed floats, never user input, and a negative one must
+        # fail before any file or connection work
+        raise SqlpushError(f"lock_timeout must be >= 0, got {lock_timeout}")
     applied: list[str] = []
     skipped: list[str] = []
     blocked: list[str] = []
     notes: list[str] = []
     partial = False
     chain = _chain_files(chain_dir)
-    with _chain_session(engine) as conn:
+    with _chain_session(engine, advisory_wait=advisory_wait) as conn:
         recorded = {
             row[0]: row[1]
             for row in conn.execute(text("SELECT name, sha256 FROM public.sqlpush_versions"))
@@ -107,6 +136,14 @@ def run_migrate(engine: Engine, *, chain_dir: str | Path, allow_destructive: boo
                 break
             try:
                 with conn.begin():
+                    # txn-scoped: SET LOCAL dies with the per-file txn
+                    # (style: push's transactional segment, executor.py).
+                    # NOTE: PostgreSQL does not accept bind parameters for
+                    # SET (utility statement), so the int is inlined;
+                    # lock_timeout is a typed float parameter, not user
+                    # input. A chain file blocked behind another
+                    # transaction's lock fails fast instead of queuing.
+                    conn.execute(text(f"SET LOCAL lock_timeout = {int(lock_timeout * 1000)}"))
                     # whole-file replay: exec_driver_sql bypasses text()'s
                     # bind-param parsing entirely — ":casts" and ":=" in
                     # hand-edited SQL must reach the server verbatim
@@ -130,14 +167,18 @@ def run_migrate(engine: Engine, *, chain_dir: str | Path, allow_destructive: boo
         )
 
 
-def run_stamp(engine: Engine, *, chain_dir: str | Path) -> MigrateReport:
+def run_stamp(engine: Engine, *, chain_dir: str | Path, force: bool = False) -> MigrateReport:
     """Register every parseable chain file WITHOUT executing any SQL.
 
     Bootstrap seam (spec §5 R7): adopt a DB whose schema already reflects
     the chain. Only the header must parse (fail-loud on THAT) — invalid SQL
-    in a body still registers, because stamp never executes anything. Each
-    registration is an idempotent upsert (``ON CONFLICT (name) DO UPDATE``),
-    so re-stamping refreshes checksums instead of failing.
+    in a body still registers, because stamp never executes anything. A
+    file already recorded with a DIFFERENT checksum is refused — it was
+    edited after apply/stamp, and silently refreshing would wipe the
+    edit-detection integrity — unless ``force`` is set; the first mismatch
+    raises and nothing after it registers (strict order, same as migrate).
+    Unrecorded files, unchanged re-stamps and forced re-stamps upsert
+    idempotently (``ON CONFLICT (name) DO UPDATE``).
 
     Report convention: registered files are listed in ``skipped`` (stamp
     never populates ``applied`` and never sets ``partial_failure``); a
@@ -149,6 +190,11 @@ def run_stamp(engine: Engine, *, chain_dir: str | Path) -> MigrateReport:
     notes: list[str] = []
     chain = _chain_files(chain_dir)
     with _chain_session(engine) as conn:
+        recorded = {
+            row[0]: row[1]
+            for row in conn.execute(text("SELECT name, sha256 FROM public.sqlpush_versions"))
+        }
+        conn.commit()
         for f in chain:
             raw = f.read_text()
             try:
@@ -157,6 +203,11 @@ def run_stamp(engine: Engine, *, chain_dir: str | Path) -> MigrateReport:
                 blocked.append(f.name)
                 notes.append(f"{f.name}: {exc}")
                 break  # orden estricto: nada posterior se registra
+            if f.name in recorded and recorded[f.name] != checksum(raw) and not force:
+                raise SqlpushError(
+                    f"{f.name}: checksum mismatch (file edited after apply?); "
+                    "pass force=True/--force to accept the new content"
+                )
             with conn.begin():
                 conn.execute(
                     text(

{sqlpush-0.4.0 → sqlpush-0.4.2}/src/sqlpush/cli.py

@@ -4,7 +4,8 @@
 Exit codes: diff always 0; check 0 clean / 2 drift / 3 destructive drift;
 push 0 applied / 1 destructive blocked / 2 error (incl. partial failure);
 revision 0 written / 1 error (empty drift refuses); migrate 0 clean /
-1 blocked or partial failure.
+1 blocked or partial failure; stamp 0 registered / 1 blocked or refused
+(an edited file without --force raises a typed error: exit 1).
 """
 
 from __future__ import annotations
@@ -250,12 +251,20 @@ def revision(
 def migrate(
     dsn: str | None = typer.Option(None),
     allow_destructive: bool = typer.Option(False, "--allow-destructive"),
+    advisory_wait: float = typer.Option(30.0, "--advisory-wait"),
+    lock_timeout: float = typer.Option(5.0, "--lock-timeout"),
     out_dir: DirOpt = Path("migrations/versions"),
 ):
     """Replay pending migration files (gates + checksum bookkeeping)."""
     engine = _engine(dsn)
     try:
-        report = api.migrate(engine, chain_dir=out_dir, allow_destructive=allow_destructive)
+        report = api.migrate(
+            engine,
+            chain_dir=out_dir,
+            allow_destructive=allow_destructive,
+            advisory_wait=advisory_wait,
+            lock_timeout=lock_timeout,
+        )
     finally:
         engine.dispose()
     typer.echo(
@@ -272,12 +281,13 @@ def migrate(
 @app.command()
 def stamp(
     dsn: str | None = typer.Option(None),
+    force: bool = typer.Option(False, "--force"),
     out_dir: DirOpt = Path("migrations/versions"),
 ):
     """Adopt an existing DB: register chain files without executing SQL."""
     engine = _engine(dsn)
     try:
-        report = api.stamp(engine, chain_dir=out_dir)
+        report = api.stamp(engine, chain_dir=out_dir, force=force)
     finally:
         engine.dispose()
     typer.echo(

{sqlpush-0.4.0 → sqlpush-0.4.2}/src/sqlpush/core/diff.py

@@ -107,6 +107,12 @@ def _timescale_auto_indexes(conn) -> dict[str, set[str]]:
     ``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.
+
+    Consumed twice in ``_make_include``: DB-only prunes (the reflected
+    auto index with no metadata counterpart) and the S1 both-present
+    sibling (a metadata-declared index with the same qualified name and
+    column sequence compares EQUAL — the default's born-DESC ordering is
+    extension state, not drift).
     """
     installed = conn.execute(
         text("SELECT 1 FROM pg_extension WHERE extname = 'timescaledb'")
@@ -222,6 +228,24 @@ def _make_include_name(schemas: frozenset[str], default_schema: str):
     return include_name
 
 
+def _expr_name(e) -> str | None:
+    """Best-effort column name of an Index expression, order-insensitive.
+
+    Metadata-side expressions may be bare strings (``Index(..., "col")``)
+    or Column objects; reflected-side ones arrive wrapped in
+    ``UnaryExpression`` (the born-DESC/ASC ordering modifier). Unwrap
+    wrapper elements (UnaryExpression/Label carry ``.element``), resolve
+    strings and Columns to their names. Functions fall back to ``.name``
+    — a sufficient equality proxy for the suppression check below.
+    """
+    if isinstance(e, str):
+        return e
+    inner = getattr(e, "element", None)
+    if inner is not None:
+        return _expr_name(inner)
+    return getattr(e, "name", None)
+
+
 def _make_include(
     schemas: frozenset[str],
     default_schema: str,
@@ -241,6 +265,11 @@ def _make_include(
         )
         if schema not in schemas or _is_system_schema(schema):
             return False
+        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 reflected and compare_to is None:
             # DB-only object: skip system tables. NB: alembic also
             # auto-excludes its own version table from autogen; the
@@ -251,16 +280,29 @@ def _make_include(
             # 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}"
+            # (that arrives in the both-present branches below).
             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)
+        if type_ == "index" and not reflected and compare_to is not None:
+            # S1 both-present sibling (atlas cycle-6): alembic gates the
+            # drop+add PAIR for a "changed" index behind exactly ONE
+            # include_object call (metadata index, reflected=False,
+            # compare_to=reflected index). TimescaleDB's default time
+            # index is born DESC (pg_index.indoption DESC bit); a
+            # metadata-declared index with the same name, same owning
+            # hypertable and the SAME column sequence is its metadata
+            # stand-in — the sort-order difference is extension-birth
+            # state, not drift. Column names compared ORDER-SENSITIVELY:
+            # a genuinely different declaration (reorder, extra column)
+            # still reports the pair.
+            owners = ts_auto_indexes.get(qualified_index, frozenset())
+            if qualified_parent in owners:
+                m_cols = [_expr_name(e) for e in obj.expressions]
+                r_cols = [_expr_name(e) for e in compare_to.expressions]
+                if m_cols == r_cols:
+                    return False
         return True
 
     return include_object
@@ -316,6 +358,100 @@ def _dedup_embedded_indexes(ops: list[PlannedOperation]) -> list[PlannedOperatio
     ]
 
 
+def _split_statements(sql: str) -> list[str]:
+    """Split a multi-statement op render on top-level ``;`` only.
+
+    Quote-aware: ``;`` inside single-quoted SQL literals (enum labels
+    can carry them) never splits; ``''`` escapes are consumed in pairs.
+    """
+    parts: list[str] = []
+    buf: list[str] = []
+    in_quote = False
+    i = 0
+    while i < len(sql):
+        ch = sql[i]
+        if ch == "'":
+            if in_quote and i + 1 < len(sql) and sql[i + 1] == "'":
+                buf.append("''")
+                i += 2
+                continue
+            in_quote = not in_quote
+            buf.append(ch)
+        elif ch == ";" and not in_quote:
+            parts.append("".join(buf))
+            buf = []
+        else:
+            buf.append(ch)
+        i += 1
+    if "".join(buf).strip():
+        parts.append("".join(buf))
+    return parts
+
+
+def _dedup_enum_types(ops: list[PlannedOperation]) -> list[PlannedOperation]:
+    """Emit each native enum's ``CREATE/DROP TYPE`` once across the plan (S2).
+
+    SQLAlchemy's offline render embeds a native enum's DDL inside EVERY
+    table op that references it (per-invoke create/drop memos — unlike
+    metadata-level ``create_all``, which memoizes per metadata), so two
+    tables sharing a Python enum each carry a verbatim copy of the
+    ``CREATE TYPE`` in their add_table render; executing both is a
+    guaranteed DuplicateObject (atlas cycle-6 finding S2 — the enum
+    sibling of F1/F2's embedded-index dedup, but statement-level and
+    cross-table).
+
+    Statement-level: only VERBATIM duplicates (whitespace-normalized)
+    are dropped — later byte-identical copies leave their op, the first
+    copy stays embedded in its original add_table render. A metadata
+    that defines one type name two DIFFERENT ways keeps both statements
+    and still fails loudly at apply time: silent first-win would mask a
+    genuine contradiction. Ops whose statements all survive pass
+    through as the ORIGINAL object (identity) — a re-joined copy of
+    unchanged SQL buys nothing.
+    """
+    seen: set[str] = set()
+
+    def _is_type_stmt(norm: str) -> bool:
+        low = norm.lower()
+        return low.startswith(("create type ", "drop type "))
+
+    out: list[PlannedOperation] = []
+    for op in ops:
+        if "type" not in op.sql.lower() or ";" not in op.sql:
+            out.append(op)
+            continue
+        stmts = _split_statements(op.sql)
+        kept: list[str] = []
+        dropped = False
+        for stmt in stmts:
+            norm = " ".join(stmt.split())
+            if _is_type_stmt(norm):
+                if norm in seen:
+                    dropped = True
+                    continue
+                seen.add(norm)
+            if norm:
+                kept.append(stmt)
+        if not kept:
+            # unreachable for table ops (their CREATE/DROP TABLE always
+            # survives); guard anyway — an empty op.sql is worse than
+            # the duplicate it replaced
+            continue
+        if not dropped:
+            out.append(op)
+            continue
+        out.append(
+            PlannedOperation(
+                type=op.type,
+                risk=op.risk,
+                sql=";\n\n".join(stmt.strip() for stmt in kept if stmt.strip()),
+                table=op.table,
+                column=op.column,
+            )
+        )
+    return out
+
+
 def _render_op_sql(op, engine: Engine) -> str:
     buf = io.StringIO()
     offline = MigrationContext.configure(
@@ -379,6 +515,7 @@ class DiffEngine:
         for op in _flatten(script.upgrade_ops.ops):
             ops.extend(self._translate(op, engine, exclude))
         ops = _dedup_embedded_indexes(ops)
+        ops = _dedup_enum_types(ops)
         return Plan(operations=tuple(ops))
 
     def _translate(self, op, engine: Engine, exclude: tuple[str, ...]) -> list[PlannedOperation]:

{sqlpush-0.4.0 → sqlpush-0.4.2}/src/sqlpush/directives/timescale.py

@@ -5,7 +5,7 @@ from sqlalchemy import MetaData, text
 from sqlalchemy.engine import Connection, Engine
 from sqlalchemy.exc import ProgrammingError
 
-from sqlpush.annotations import HYPERTABLE_KEY
+from sqlpush.annotations import HYPERTABLE_KEY, create_hypertable_sql
 from sqlpush.types import PlannedOperation, RiskClass
 
 
@@ -29,12 +29,6 @@ def _is_hypertable(conn: Connection, schema: str, table_name: str) -> bool:
         return False
 
 
-def _lit(value: str) -> str:
-    # single-quoted SQL literal escaping: ' -> '' (defense in depth
-    # against quote break-out via table/column names from user metadata)
-    return value.replace("'", "''")
-
-
 def hypertable_operations(
     metadata: MetaData, engine: Engine | None = None
 ) -> list[PlannedOperation]:
@@ -58,31 +52,14 @@ def hypertable_operations(
     ops: list[PlannedOperation] = []
     for table in pending:
         info = table.info[HYPERTABLE_KEY]
-        # 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:
-            parts.append(f", chunk_time_interval => INTERVAL '{_lit(info.chunk_time_interval)}'")
-        parts.append(", migrate_data => true")
-        # if_not_exists: race insurance between the state check above
-        # and the apply. create_default_indexes=false: timescale's
-        # implicit time-column index is invisible to metadata, so the
-        # default would drift forever (destructive drop_index) on a
-        # fully synced schema; users declare wanted indexes in the
-        # Table instead (metadata is the source of truth).
-        parts.append(", if_not_exists => true, create_default_indexes => false)")
+        # SQL parity with the decorator's after_create listener is by
+        # construction: both render through create_hypertable_sql (the
+        # directive's render adds the statement terminator).
         ops.append(
             PlannedOperation(
                 type="create_hypertable",
                 risk=RiskClass.SAFE,
-                sql="".join(parts) + ";",
+                sql=create_hypertable_sql(table.name, table.schema, info) + ";",
                 table=table.name,
             )
         )

sqlpush-0.4.0/src/sqlpush/annotations.py

@@ -1,37 +0,0 @@
-# src/sqlpush/annotations.py
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-HYPERTABLE_KEY = "sqlpush_hypertable"
-
-
-@dataclass(frozen=True)
-class HypertableInfo:
-    time_column: str
-    chunk_time_interval: str | None = None
-
-
-def hypertable(*, time_column: str, chunk_time_interval: str | None = None):
-    """Record hypertable intent on the model's Table (MetaData level).
-
-    Works with SQLModel, Flask-SQLAlchemy and plain declarative, anything
-    whose class already carries a built ``__table__`` when decorated.
-
-    The generated ``create_hypertable`` runs with
-    ``create_default_indexes => false``: timescale's implicit time-column
-    index is invisible to metadata and would drift forever. Declare it
-    yourself (``Index(..., "<time_column>")`` on the model) if you rely
-    on it for time-range scans.
-    """
-
-    def decorator(cls):
-        table = getattr(cls, "__table__", None)
-        if table is None:
-            raise TypeError(f"{cls.__name__} has no __table__; decorate a mapped class")
-        table.info[HYPERTABLE_KEY] = HypertableInfo(
-            time_column=time_column, chunk_time_interval=chunk_time_interval
-        )
-        return cls
-
-    return decorator