sqlpush 0.4.2__tar.gz → 0.5.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sqlpush
-Version: 0.4.2
+Version: 0.5.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
@@ -133,8 +133,11 @@ repeated `--schema` / `--exclude` options.
 | `push` | applied | destructive blocked | error (incl. partial failure) | |
 
 `push --safe-only` runs only safe operations and skips the rest
-informationally (exit `0`). A failed `CREATE INDEX CONCURRENTLY` marks the
-run as partial failure (exit `2`) instead of silently half-applying.
+informationally (exit `0`). Indexes on existing tables build
+`CONCURRENTLY` by default (opt out with `--no-concurrently`); a failed
+`CREATE INDEX CONCURRENTLY` marks the run as partial failure (exit `2`)
+instead of silently half-applying, and leaves an INVALID index — drop it
+(`DROP INDEX CONCURRENTLY`) and re-push.
 
 ## FastAPI / SQLModel: replace `create_all`
 
@@ -169,9 +172,11 @@ flowchart LR
   internals included) before reflection even starts.
 - **Classifier** maps each operation to a risk class; unknown operations
   are `risky`, never silently safe.
-- **Executor** splits the plan: `CONCURRENTLY` statements run one-per-
-  transaction on autocommit, everything else applies in a single atomic
-  transaction with a bounded `lock_timeout`.
+- **Executor** splits the plan: existing-table indexes render
+  `CREATE INDEX CONCURRENTLY` and run one-per-transaction on autocommit
+  (`--no-concurrently` opts out; indexes on tables the same plan creates
+  stay in the atomic transaction), everything else applies in a single
+  atomic transaction with a bounded `lock_timeout`.
 - **Typed errors**: only `SqlpushError` / `ConnectFailed` /
   `MetadataImportError` escape the API, never raw driver exceptions.
 
@@ -201,12 +206,11 @@ deprecated)? There is a [migration guide](docs/migrating-from-migra.md).
 - The advisory-lock key derives from the database OID: two DSN spellings
   of the same database contend for the same lock.
 - `--json` output is a versioned contract (`"version": 1`) meant for
-  tooling; additive changes only within a version.
+  tooling; additive changes only within a version (operations now carry
+  a `concurrent` boolean).
 
 ## Roadmap (0.1.x)
 
-- `CREATE INDEX CONCURRENTLY` by default for indexes on existing tables
-- asyncpg DSN translation in `ensure_schema(AsyncEngine)`
 - jsonschema-validated `--json` output
 
 ## License

{sqlpush-0.4.2 → sqlpush-0.5.0}/README.md

@@ -104,8 +104,11 @@ repeated `--schema` / `--exclude` options.
 | `push` | applied | destructive blocked | error (incl. partial failure) | |
 
 `push --safe-only` runs only safe operations and skips the rest
-informationally (exit `0`). A failed `CREATE INDEX CONCURRENTLY` marks the
-run as partial failure (exit `2`) instead of silently half-applying.
+informationally (exit `0`). Indexes on existing tables build
+`CONCURRENTLY` by default (opt out with `--no-concurrently`); a failed
+`CREATE INDEX CONCURRENTLY` marks the run as partial failure (exit `2`)
+instead of silently half-applying, and leaves an INVALID index — drop it
+(`DROP INDEX CONCURRENTLY`) and re-push.
 
 ## FastAPI / SQLModel: replace `create_all`
 
@@ -140,9 +143,11 @@ flowchart LR
   internals included) before reflection even starts.
 - **Classifier** maps each operation to a risk class; unknown operations
   are `risky`, never silently safe.
-- **Executor** splits the plan: `CONCURRENTLY` statements run one-per-
-  transaction on autocommit, everything else applies in a single atomic
-  transaction with a bounded `lock_timeout`.
+- **Executor** splits the plan: existing-table indexes render
+  `CREATE INDEX CONCURRENTLY` and run one-per-transaction on autocommit
+  (`--no-concurrently` opts out; indexes on tables the same plan creates
+  stay in the atomic transaction), everything else applies in a single
+  atomic transaction with a bounded `lock_timeout`.
 - **Typed errors**: only `SqlpushError` / `ConnectFailed` /
   `MetadataImportError` escape the API, never raw driver exceptions.
 
@@ -172,12 +177,11 @@ deprecated)? There is a [migration guide](docs/migrating-from-migra.md).
 - The advisory-lock key derives from the database OID: two DSN spellings
   of the same database contend for the same lock.
 - `--json` output is a versioned contract (`"version": 1`) meant for
-  tooling; additive changes only within a version.
+  tooling; additive changes only within a version (operations now carry
+  a `concurrent` boolean).
 
 ## Roadmap (0.1.x)
 
-- `CREATE INDEX CONCURRENTLY` by default for indexes on existing tables
-- asyncpg DSN translation in `ensure_schema(AsyncEngine)`
 - jsonschema-validated `--json` output
 
 ## License

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

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

@@ -1,6 +1,6 @@
 [project]
 name = "sqlpush"
-version = "0.4.2"
+version = "0.5.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.4.2 → sqlpush-0.5.0}/src/sqlpush/api.py

@@ -48,8 +48,10 @@ def _raise_typed(exc: SQLAlchemyError) -> NoReturn:
     raise SqlpushError(f"database error: {exc}") from exc
 
 
-def _build_plan(metadata: MetaData, engine: Engine, schemas, exclude) -> Plan:
-    p = _engine.plan(metadata, engine, schemas=schemas, exclude=exclude)
+def _build_plan(
+    metadata: MetaData, engine: Engine, schemas, exclude, concurrently: bool = True
+) -> Plan:
+    p = _engine.plan(metadata, engine, schemas=schemas, exclude=exclude, concurrently=concurrently)
     return Plan(operations=p.operations + tuple(hypertable_operations(metadata, engine)))
 
 
@@ -65,13 +67,13 @@ class _PlannerWithDirectives(DiffEngine):
     def __init__(self, engine: DiffEngine) -> None:
         self._engine = engine
 
-    def plan(self, metadata, engine, *, schemas=None, exclude=()) -> Plan:
-        return _build_plan(metadata, engine, schemas, exclude)
+    def plan(self, metadata, engine, *, schemas=None, exclude=(), concurrently=True) -> Plan:
+        return _build_plan(metadata, engine, schemas, exclude, concurrently)
 
 
-def plan(metadata, engine, *, schemas=None, exclude=()) -> Plan:
+def plan(metadata, engine, *, schemas=None, exclude=(), concurrently: bool = True) -> Plan:
     try:
-        return _build_plan(metadata, engine, schemas, exclude)
+        return _build_plan(metadata, engine, schemas, exclude, concurrently)
     except SQLAlchemyError as exc:
         _raise_typed(exc)
 
@@ -84,9 +86,11 @@ def push(
     allow_destructive=False,
     lock=True,
     lock_timeout=5.0,
+    statement_timeout=None,
     advisory_wait=30.0,
     schemas=None,
     exclude=(),
+    concurrently=True,
 ) -> Report:
     try:
         if lock:
@@ -100,14 +104,21 @@ def push(
                 reverify=_PlannerWithDirectives(_engine),
                 schemas=schemas,
                 exclude=exclude,
+                # THREADING (pinned): the lock winner re-plans via
+                # reverify.plan(...) — both knobs must reach it and the
+                # final apply_plan, or the winner renders differently
+                # than requested
+                concurrently=concurrently,
+                statement_timeout=statement_timeout,
             )
-        p = _build_plan(metadata, engine, schemas, exclude)
+        p = _build_plan(metadata, engine, schemas, exclude, concurrently)
         return apply_plan(
             engine,
             p,
             allow_destructive=allow_destructive,
             safe_only=safe_only,
             lock_timeout=lock_timeout,
+            statement_timeout=statement_timeout,
         )
     except SQLAlchemyError as exc:
         _raise_typed(exc)
@@ -126,14 +137,23 @@ def check(metadata, engine, *, schemas=None, exclude=()) -> CheckResult:
 
 
 def revision(
-    metadata, ref_engine, *, out_dir="migrations/versions", message=None, schemas=None, exclude=()
+    metadata,
+    ref_engine,
+    *,
+    out_dir="migrations/versions",
+    message=None,
+    schemas=None,
+    exclude=(),
+    concurrently=True,
 ) -> Path:
     """Generate the next annotated-SQL migration file from models-vs-ref drift.
 
     The reference DB must sit at the chain head (caller-provided — sqlpush
     stays docker-free). Empty drift refuses loudly: no empty files.
+    ``concurrently`` follows :func:`plan` (default True: existing-table
+    indexes render CONCURRENTLY in the generated file).
     """
-    p = plan(metadata, ref_engine, schemas=schemas, exclude=exclude)
+    p = plan(metadata, ref_engine, schemas=schemas, exclude=exclude, concurrently=concurrently)
     if not p.operations:
         raise SqlpushError("no drift between models and reference DB — nothing to revise")
     risk = max((op.risk for op in p.operations), key=lambda r: RISK_RANK[r])
@@ -175,6 +195,7 @@ def migrate(
     allow_destructive=False,
     advisory_wait=30.0,
     lock_timeout=5.0,
+    statement_timeout=None,
 ) -> MigrateReport:
     """Replay annotated-SQL chain files with gates + same-txn bookkeeping.
 
@@ -182,7 +203,10 @@ def migrate(
     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
+    immediately — same contract as ``push``). ``statement_timeout``
+    (seconds, ``None`` = set nothing) bounds each statement's runtime —
+    ``SET LOCAL`` in per-file transactions, session-level on the
+    CONCURRENTLY autocommit connection. See
     ``chain.migrate.run_migrate`` for the execution contract.
     """
     engine, dispose = _sync_engine_from(target)
@@ -193,6 +217,7 @@ def migrate(
             allow_destructive=allow_destructive,
             advisory_wait=advisory_wait,
             lock_timeout=lock_timeout,
+            statement_timeout=statement_timeout,
         )
     except SQLAlchemyError as exc:
         # MigrationFileError/SqlpushError (typed) pass through untouched

{sqlpush-0.4.2 → sqlpush-0.5.0}/src/sqlpush/apply/executor.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 
 import contextlib
 import time
+from collections.abc import Iterator
 from typing import TYPE_CHECKING
 
 from sqlalchemy import text
@@ -26,7 +27,37 @@ if TYPE_CHECKING:
 
 
 def _is_concurrent(op: PlannedOperation) -> bool:
-    return "CONCURRENTLY" in op.sql.upper()
+    # Union (A5): the `concurrent` flag is authoritative for generated
+    # plans (set by the diff's injection); the SQL substring keeps
+    # hand-built Plans splitting to the autocommit segment.
+    return op.concurrent or "CONCURRENTLY" in op.sql.upper()
+
+
+@contextlib.contextmanager
+def _session_gucs(conn, **gucs: str | int) -> Iterator[None]:
+    """Session-level ``SET``/``RESET`` with pooled-connection hygiene.
+
+    The autocommit (CONCURRENTLY) segment cannot use ``SET LOCAL`` —
+    there is no surrounding transaction — so its GUCs are session-level,
+    and a session ``SET`` survives segment end (0.4.2 lesson). RESET runs
+    per GUC in ``finally``; a reset failure is suppressed (it must never
+    mask the segment's own outcome) and the connection is invalidated so
+    the pool discards it instead of handing the next borrower a session
+    still carrying the shrunken budget.
+    """
+    try:
+        for name, value in gucs.items():
+            # names come from sqlpush code, values are ints inlined in
+            # the same style as the txn segment's SET LOCAL (PostgreSQL
+            # does not accept bind parameters for SET)
+            conn.execute(text(f"SET {name} = '{value}'"))
+        yield
+    finally:
+        for name in gucs:
+            try:
+                conn.execute(text(f"RESET {name}"))
+            except Exception:  # noqa: BLE001  # never mask the segment's outcome
+                conn.invalidate()
 
 
 def apply_plan(
@@ -36,8 +67,11 @@ def apply_plan(
     allow_destructive: bool = False,
     safe_only: bool = False,
     lock_timeout: float = 5.0,
+    statement_timeout: float | None = None,
 ) -> Report:
     start = time.monotonic()
+    if statement_timeout is not None and statement_timeout < 0:
+        raise SqlpushError(f"statement_timeout must be >= 0, got {statement_timeout}")
 
     blocked = tuple(op for op in plan.operations if op.risk is RiskClass.DESTRUCTIVE)
     if blocked and not allow_destructive:
@@ -69,13 +103,21 @@ def apply_plan(
     concurrent = [op for op in runnable if _is_concurrent(op)]
     if concurrent:
         with engine.connect().execution_options(isolation_level="AUTOCOMMIT") as conn:
-            for op in concurrent:
-                try:
-                    conn.execute(text(op.sql))
-                    applied.append(AppliedOperation(op.type, "applied"))
-                except Exception:  # noqa: BLE001  # concurrent ops record any DB failure and continue
-                    applied.append(AppliedOperation(op.type, "failed"))
-                    partial_failure = True
+            # A7: the concurrent segment gets the SAME lock budget as the
+            # txn segment (session-level: autocommit has no surrounding
+            # transaction for SET LOCAL), plus the optional statement
+            # budget; both RESET before the connection returns to the pool
+            session_gucs: dict[str, int] = {"lock_timeout": int(lock_timeout * 1000)}
+            if statement_timeout is not None:
+                session_gucs["statement_timeout"] = int(statement_timeout * 1000)
+            with _session_gucs(conn, **session_gucs):
+                for op in concurrent:
+                    try:
+                        conn.execute(text(op.sql))
+                        applied.append(AppliedOperation(op.type, "applied"))
+                    except Exception:  # noqa: BLE001  # concurrent ops record any DB failure and continue
+                        applied.append(AppliedOperation(op.type, "failed"))
+                        partial_failure = True
 
     # --- transactional segment: atomic ----------------------------------
     plain = [op for op in runnable if not _is_concurrent(op)]
@@ -83,9 +125,13 @@ def apply_plan(
         try:
             with engine.begin() as conn:
                 # 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.
+                # (utility statement), so the int is inlined; both timeouts
+                # are typed float parameters, not user input.
                 conn.execute(text(f"SET LOCAL lock_timeout = {int(lock_timeout * 1000)}"))
+                if statement_timeout is not None:
+                    conn.execute(
+                        text(f"SET LOCAL statement_timeout = {int(statement_timeout * 1000)}")
+                    )
                 for op in plain:
                     conn.execute(text(op.sql))
             applied.extend(AppliedOperation(op.type, "applied") for op in plain)
@@ -146,6 +192,8 @@ def with_advisory_lock(
     reverify: DiffEngine | None = None,
     schemas: Sequence[str] | None = None,
     exclude: Sequence[str] = (),
+    concurrently: bool = True,
+    statement_timeout: float | None = None,
 ) -> Report:
     """Winner migrates; losers block (bounded), then re-verify.
 
@@ -153,7 +201,9 @@ def with_advisory_lock(
     ``time.monotonic()`` deadline; once the lock is acquired the winner
     path re-plans (covering the case where the previous winner died
     mid-push). Raises :class:`SqlpushError` if the wait budget is
-    exhausted.
+    exhausted. ``concurrently`` and ``statement_timeout`` thread into
+    BOTH the winner's re-plan and its apply — the re-plan must render
+    exactly what the caller asked for.
     """
     if reverify is None:
         raise SqlpushError(
@@ -179,7 +229,13 @@ def with_advisory_lock(
         # (killed mid-push = lock silently released)
         conn.rollback()
         try:
-            plan = reverify.plan(metadata, engine, schemas=schemas, exclude=exclude)
+            plan = reverify.plan(
+                metadata,
+                engine,
+                schemas=schemas,
+                exclude=exclude,
+                concurrently=concurrently,
+            )
             if not plan.drift:
                 return Report()
             return apply_plan(
@@ -188,6 +244,7 @@ def with_advisory_lock(
                 allow_destructive=allow_destructive,
                 safe_only=safe_only,
                 lock_timeout=timeout,
+                statement_timeout=statement_timeout,
             )
         finally:
             # best-effort unlock: a secondary failure here (e.g. the

sqlpush-0.5.0/src/sqlpush/chain/migrate.py

@@ -0,0 +1,404 @@
+"""migrate/stamp: chain replay + bootstrap with gates and bookkeeping.
+
+migrate execution contract (spec 2026-09-02 §5, 0.5.0 hybrid): a file
+whose text contains no CONCURRENTLY replays its WHOLE TEXT in ONE
+``exec_driver_sql()`` call inside a per-file transaction — nothing is
+tokenized, so dollar-quoted bodies (and their internal ``--`` lines)
+are safe; that is the 0.4.2 fast path, byte-identical. A file that
+DOES contain CONCURRENTLY replays per-op on the op-label delimiters
+(``mf.ops``): the plain segment runs FIRST in one transaction (chain
+files can create→index within one file — a table made by a plain op
+must exist before a concurrent index on it; push's concurrent-first
+order does NOT apply here), then concurrent ops run per-op on a
+dedicated autocommit connection, and only after all of them succeed
+is the versions row written. Known cost (chain spec §7): hand-edits
+bypass the label mechanism — a label-less body containing
+CONCURRENTLY routes the whole body to the autocommit lane (executed
+statement-by-statement: the server runs a multi-statement string as
+one implicit transaction, which CONCURRENTLY refuses), and lines
+starting ``--`` are stripped from per-op parsing (they exist inside
+dollar-quoted bodies at the author's risk). Concurrent-free files
+are immune: they take the raw fast path. The crash window (plain
+committed, concurrent applied, no row yet) re-runs loud on existing
+objects — the documented chain-side cost of per-op replay.
+
+Fail-loud ordering: any blocked file (parse error, checksum mismatch,
+destructive gate, SQL failure) stops the chain — nothing later runs (R4).
+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 re
+import time
+from collections.abc import Iterator
+from pathlib import Path
+
+from sqlalchemy import text
+from sqlalchemy.engine import Connection, Engine
+
+from sqlpush.apply.executor import _session_gucs, advisory_key
+from sqlpush.chain.format import MigrationFileError, checksum, parse_migration_file
+from sqlpush.types import MigrateReport, RiskClass, SqlpushError
+
+_VERSIONS_DDL = (
+    "CREATE TABLE IF NOT EXISTS public.sqlpush_versions ("
+    "name TEXT PRIMARY KEY, sha256 TEXT NOT NULL, "
+    "applied_at timestamptz NOT NULL DEFAULT now())"
+)
+
+
+def _chain_files(chain_dir: str | Path) -> list[Path]:
+    chain_path = Path(chain_dir)
+    if not chain_path.is_dir():
+        # a typo'd --dir silently no-op'ing is the footgun; an empty-but-
+        # EXISTING dir is a legitimate idle run (versions table still ensured)
+        raise MigrationFileError(f"chain dir not found: {chain_path}")
+    return sorted(chain_path.glob("*.sql"))
+
+
+def _set_local_gucs(
+    conn: Connection, *, lock_timeout: float, statement_timeout: float | None
+) -> None:
+    # txn-scoped: SET LOCAL dies with the surrounding transaction (style:
+    # push's transactional segment, executor.py). NOTE: PostgreSQL does
+    # not accept bind parameters for SET (utility statement), so ints
+    # are inlined; both timeouts are typed float parameters, 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)}"))
+    if statement_timeout is not None:
+        conn.execute(text(f"SET LOCAL statement_timeout = {int(statement_timeout * 1000)}"))
+
+
+def _record_version(conn: Connection, name: str, sha: str) -> None:
+    conn.execute(
+        text("INSERT INTO public.sqlpush_versions (name, sha256) VALUES (:n, :s)"),
+        {"n": name, "s": sha},
+    )
+
+
+_DOLLAR_TAG_RE = re.compile(r"\$[A-Za-z_][A-Za-z0-9_]*\$|\$\$")
+
+
+def _split_statements(sql: str) -> list[str]:
+    """Split a concurrent-lane op into single statements.
+
+    Physical constraint (live-verified): the server executes a
+    multi-statement simple-protocol string inside ONE implicit
+    transaction block, even on an autocommit connection — so
+    ``CREATE INDEX CONCURRENTLY`` cannot ride a multi-statement
+    ``exec_driver_sql`` call; the autocommit lane needs one statement
+    per execute. Split on top-level ``;`` only, treating single-quoted
+    strings (``''`` doubling), double-quoted identifiers, dollar-quoted
+    bodies (``$tag$...$tag$``) and ``--`` / ``/* */`` comments as
+    opaque (psql-equivalent boundaries). Generated ops are single
+    statements — the splitter is a no-op for them; only hand-edited
+    label-less bodies exercise it (chain spec §7: at the author's
+    risk). The plain segment and the fast path NEVER split.
+    """
+    statements: list[str] = []
+    buf: list[str] = []
+    i, n = 0, len(sql)
+    while i < n:
+        ch = sql[i]
+        nxt = sql[i + 1] if i + 1 < n else ""
+        if ch == "-" and nxt == "-":  # line comment
+            j = sql.find("\n", i)
+            j = n if j == -1 else j + 1
+            buf.append(sql[i:j])
+            i = j
+        elif ch == "/" and nxt == "*":  # block comment
+            j = sql.find("*/", i + 2)
+            j = n if j == -1 else j + 2
+            buf.append(sql[i:j])
+            i = j
+        elif ch == "'":  # string literal, '' doubling
+            j = i + 1
+            while j < n:
+                if sql[j] == "'" and not (j + 1 < n and sql[j + 1] == "'"):
+                    break
+                j += 2 if sql[j] == "'" else 1
+            j = min(j + 1, n)
+            buf.append(sql[i:j])
+            i = j
+        elif ch == '"':  # quoted identifier
+            j = sql.find('"', i + 1)
+            j = n if j == -1 else j + 1
+            buf.append(sql[i:j])
+            i = j
+        elif ch == "$":
+            m = _DOLLAR_TAG_RE.match(sql, i)
+            if m:  # dollar-quoted body: opaque through the closing tag
+                end = sql.find(m.group(0), m.end())
+                j = n if end == -1 else end + len(m.group(0))
+                buf.append(sql[i:j])
+                i = j
+            else:
+                buf.append(ch)
+                i += 1
+        elif ch == ";":
+            stmt = "".join(buf).strip()
+            if stmt:
+                statements.append(stmt)
+            buf = []
+            i += 1
+        else:
+            buf.append(ch)
+            i += 1
+    tail = "".join(buf).strip()
+    if tail:
+        statements.append(tail)
+    return statements
+
+
+@contextlib.contextmanager
+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
+    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)
+        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))
+            conn.commit()
+            yield conn
+        finally:
+            # best-effort unlock (executor pattern): a secondary failure here
+            # must never mask the primary outcome; the session lock dies with
+            # the connection even if this fails
+            if not conn.closed:
+                with contextlib.suppress(Exception):
+                    conn.rollback()
+                    conn.execute(text("SELECT pg_advisory_unlock(:k)"), {"k": key})
+                    conn.commit()
+
+
+def run_migrate(
+    engine: Engine,
+    *,
+    chain_dir: str | Path,
+    allow_destructive: bool,
+    advisory_wait: float = 30.0,
+    lock_timeout: float = 5.0,
+    statement_timeout: float | None = None,
+) -> 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}")
+    if statement_timeout is not None and statement_timeout < 0:
+        raise SqlpushError(f"statement_timeout must be >= 0, got {statement_timeout}")
+    applied: list[str] = []
+    skipped: list[str] = []
+    blocked: list[str] = []
+    notes: list[str] = []
+    partial = False
+    chain = _chain_files(chain_dir)
+    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"))
+        }
+        conn.commit()
+        # B11: ONE lazily-created autocommit connection for the whole
+        # walk, GUC-pinned for its entire lifetime. ExitStack ordering:
+        # _session_gucs' finally (per-GUC RESET, suppress + invalidate
+        # on reset failure) unwinds BEFORE the connection close (LIFO).
+        concurrent_stack = contextlib.ExitStack()
+        concurrent_conn: Connection | None = None
+        try:
+            for f in chain:
+                raw = f.read_text()
+                try:
+                    mf = parse_migration_file(raw, name=f.name)
+                except MigrationFileError as exc:
+                    blocked.append(f.name)
+                    notes.append(f"{f.name}: {exc}")
+                    break  # orden estricto: nada posterior corre
+                if f.name in recorded:
+                    if recorded[f.name] != checksum(raw):
+                        blocked.append(f.name)
+                        notes.append(f"{f.name}: checksum mismatch (edited after apply?)")
+                        break
+                    skipped.append(f.name)
+                    continue
+                if mf.risk is RiskClass.DESTRUCTIVE and not allow_destructive:
+                    blocked.append(f.name)
+                    notes.append(f"{f.name}: DESTRUCTIVE requires --allow-destructive")
+                    break
+                if "CONCURRENTLY" not in raw.upper():
+                    # fast path — byte-identical to 0.4.2: whole text,
+                    # one txn, one exec_driver_sql call (":casts" and
+                    # ":=" reach the server verbatim; dollar-quoted
+                    # bodies and their internal `--` lines are safe —
+                    # the parser's line-stripping quirks never execute
+                    # on this path). Checksum row rides the SAME txn.
+                    try:
+                        with conn.begin():
+                            _set_local_gucs(
+                                conn,
+                                lock_timeout=lock_timeout,
+                                statement_timeout=statement_timeout,
+                            )
+                            conn.exec_driver_sql(raw)
+                            _record_version(conn, f.name, checksum(raw))
+                        applied.append(f.name)
+                    except Exception as exc:  # noqa: BLE001 — report, no mask
+                        blocked.append(f.name)
+                        notes.append(f"{f.name}: {exc}")
+                        partial = True
+                        break
+                    continue
+                # mixed path — per-op replay on the op-label delimiters.
+                # PLAIN SEGMENT FIRST (create→index dependencies inside
+                # one file); concurrent ops afterwards, per-op on the
+                # dedicated autocommit connection; versions row LAST.
+                plain = [sql for _, sql in mf.ops if "CONCURRENTLY" not in sql.upper()]
+                conc = [sql for _, sql in mf.ops if "CONCURRENTLY" in sql.upper()]
+                plain_committed = False
+                try:
+                    if plain:
+                        with conn.begin():
+                            _set_local_gucs(
+                                conn,
+                                lock_timeout=lock_timeout,
+                                statement_timeout=statement_timeout,
+                            )
+                            for sql in plain:
+                                conn.exec_driver_sql(sql)
+                        plain_committed = True
+                    for sql in conc:
+                        if concurrent_conn is None:
+                            concurrent_conn = engine.connect().execution_options(
+                                isolation_level="AUTOCOMMIT"
+                            )
+                            concurrent_stack.callback(concurrent_conn.close)
+                            session_gucs: dict[str, int] = {
+                                "lock_timeout": int(lock_timeout * 1000)
+                            }
+                            if statement_timeout is not None:
+                                session_gucs["statement_timeout"] = int(statement_timeout * 1000)
+                            concurrent_stack.enter_context(
+                                _session_gucs(concurrent_conn, **session_gucs)
+                            )
+                        # statement-per-execute: a multi-statement string
+                        # is one implicit server txn (CONCURRENTLY refuses
+                        # it) — generated ops are single statements, so
+                        # this split only fires for hand-edited bodies
+                        for stmt in _split_statements(sql):
+                            concurrent_conn.exec_driver_sql(stmt)
+                    # never record before the concurrent ops succeed: a
+                    # row for a file whose concurrent op then failed would
+                    # be silent divergence. The crash window this leaves
+                    # (plain committed + concurrent applied + no row)
+                    # re-runs loud on existing objects — documented cost.
+                    with conn.begin():
+                        _record_version(conn, f.name, checksum(raw))
+                    applied.append(f.name)
+                except Exception as exc:  # noqa: BLE001 — report, no mask
+                    blocked.append(f.name)
+                    notes.append(f"{f.name}: {exc}")
+                    if plain_committed:
+                        # honest report: the plain segment of THIS file is
+                        # already committed (same class as push's partial
+                        # failure) and no versions row was recorded
+                        notes.append(
+                            f"{f.name}: plain segment already committed; no versions row recorded"
+                        )
+                    partial = True
+                    break
+        finally:
+            concurrent_stack.close()
+        return MigrateReport(
+            applied=tuple(applied),
+            skipped=tuple(skipped),
+            blocked=tuple(blocked),
+            partial_failure=partial,
+            notes=tuple(notes),
+        )
+
+
+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. 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
+    header that fails to parse goes to ``blocked`` + ``notes`` and stops
+    the walk (strict order, same as migrate).
+    """
+    skipped: list[str] = []
+    blocked: list[str] = []
+    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:
+                parse_migration_file(raw, name=f.name)
+            except MigrationFileError as exc:
+                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(
+                        "INSERT INTO public.sqlpush_versions (name, sha256) VALUES (:n, :s) "
+                        "ON CONFLICT (name) DO UPDATE SET sha256 = EXCLUDED.sha256"
+                    ),
+                    {"n": f.name, "s": checksum(raw)},
+                )
+            skipped.append(f.name)
+        return MigrateReport(
+            applied=(),
+            skipped=tuple(skipped),
+            blocked=tuple(blocked),
+            partial_failure=False,
+            notes=tuple(notes),
+        )

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

@@ -148,6 +148,8 @@ def push(
     no_lock: bool = typer.Option(False, "--no-lock"),
     lock_timeout: float = typer.Option(5.0, "--lock-timeout"),
     advisory_wait: float = typer.Option(30.0, "--advisory-wait"),
+    no_concurrently: bool = typer.Option(False, "--no-concurrently"),
+    statement_timeout: float | None = typer.Option(None, "--statement-timeout"),
     verbose: bool = typer.Option(False, "--verbose"),
     quiet: bool = typer.Option(False, "--quiet"),
     schema: SchemaOpt = None,
@@ -165,6 +167,8 @@ def push(
                 lock=not no_lock,
                 lock_timeout=lock_timeout,
                 advisory_wait=advisory_wait,
+                concurrently=not no_concurrently,
+                statement_timeout=statement_timeout,
                 schemas=schema,
                 exclude=exclude or (),
             )
@@ -223,6 +227,7 @@ def revision(
     ref_dsn: str = typer.Option(..., "--ref-dsn"),
     message: str | None = typer.Option(None, "--message", "-m"),
     out_dir: DirOpt = Path("migrations/versions"),
+    no_concurrently: bool = typer.Option(False, "--no-concurrently"),
     schema: SchemaOpt = None,
     exclude: ExcludeOpt = None,
 ):
@@ -238,6 +243,7 @@ def revision(
             engine,
             out_dir=out_dir,
             message=message,
+            concurrently=not no_concurrently,
             schemas=schema,
             exclude=exclude or (),
         )
@@ -253,6 +259,7 @@ def migrate(
     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"),
+    statement_timeout: float | None = typer.Option(None, "--statement-timeout"),
     out_dir: DirOpt = Path("migrations/versions"),
 ):
     """Replay pending migration files (gates + checksum bookkeeping)."""
@@ -264,6 +271,7 @@ def migrate(
             allow_destructive=allow_destructive,
             advisory_wait=advisory_wait,
             lock_timeout=lock_timeout,
+            statement_timeout=statement_timeout,
         )
     finally:
         engine.dispose()

sqlpush-0.5.0/src/sqlpush/core/classify.py

@@ -0,0 +1,28 @@
+# src/sqlpush/core/classify.py
+from __future__ import annotations
+
+from sqlpush.types import RiskClass
+
+SAFE = frozenset({"add_table", "add_column", "add_constraint", "create_hypertable"})
+DESTRUCTIVE = frozenset({"drop_column", "drop_table", "drop_index", "drop_constraint"})
+
+
+def classify(op_type: str) -> RiskClass:
+    """add_index stays RISKY in BOTH renderings. The plain form takes a
+    SHARE lock that blocks writes for the whole build. CONCURRENTLY
+    (0.5 default for existing-table indexes) trades that write-block
+    for a different risk profile: the build is concurrent and
+    non-transactional (no rollback — a failure leaves no index behind
+    to retry with, but an aborted build can leave an INVALID index),
+    so the op is still flagged, never silently safe. Standalone
+    rendering note: 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)."""
+    if op_type in DESTRUCTIVE:
+        return RiskClass.DESTRUCTIVE
+    if op_type in SAFE:
+        return RiskClass.SAFE
+    # modify_*, add_index, raw_sql, and anything unknown
+    return RiskClass.RISKY

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

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
+import dataclasses
 import fnmatch
 import io
+import re
 from collections.abc import Sequence
 
 from alembic.autogenerate import produce_migrations
@@ -464,6 +466,43 @@ def _render_op_sql(op, engine: Engine) -> str:
     return buf.getvalue().strip().rstrip(";")
 
 
+# A1: match the CREATE [UNIQUE] INDEX head of an op's (single-statement)
+# SQL. Anchored with no MULTILINE and sub'd with count=1: only the op's
+# own leading statement is touched. The lookahead makes it idempotent —
+# a second pass over an already-injected render finds CONCURRENTLY right
+# after the consumed whitespace and declines. IF NOT EXISTS lands after
+# the inserted keyword, which is the correct PostgreSQL order.
+_CONCURRENTLY_RE = re.compile(
+    r"^(CREATE\s+(?:UNIQUE\s+)?INDEX)\s+(?!CONCURRENTLY\s)", re.IGNORECASE
+)
+
+
+def _render_concurrent(ops: list[PlannedOperation]) -> list[PlannedOperation]:
+    """Render standalone ``add_index`` ops on EXISTING tables CONCURRENTLY.
+
+    Plain ``CREATE INDEX`` takes a SHARE lock that blocks all writes on
+    the table for the whole build; ``CREATE INDEX CONCURRENTLY`` is the
+    production-safe form for tables that already carry traffic. Indexes
+    on tables CREATED in the same plan stay plain: a brand-new table has
+    no concurrent writers to protect, and CONCURRENTLY cannot run inside
+    the plan's transactional create. The new-table guard keys on bare
+    table names (``op.table``), which is conservative-correct: a false
+    "new" (cross-schema bare-name collision) yields a plain
+    ``CREATE INDEX`` — always executable — while the dangerous direction
+    (injecting on a new table) cannot happen.
+    """
+    new_tables = {op.table for op in ops if op.type == "add_table"}
+    out: list[PlannedOperation] = []
+    for op in ops:
+        if op.type == "add_index" and op.table not in new_tables:
+            sql = _CONCURRENTLY_RE.sub(r"\1 CONCURRENTLY ", op.sql, count=1)
+            if sql != op.sql:
+                out.append(dataclasses.replace(op, sql=sql, concurrent=True))
+                continue
+        out.append(op)
+    return out
+
+
 class DiffEngine:
     def plan(
         self,
@@ -472,6 +511,7 @@ class DiffEngine:
         *,
         schemas: Sequence[str] | None = None,
         exclude: Sequence[str] = (),
+        concurrently: bool = True,
     ) -> Plan:
         exclude = tuple(exclude)
         # Typed `str | None` by SQLAlchemy; a dialect without a default
@@ -516,6 +556,15 @@ class DiffEngine:
             ops.extend(self._translate(op, engine, exclude))
         ops = _dedup_embedded_indexes(ops)
         ops = _dedup_enum_types(ops)
+        # ORDERING INVARIANT: CONCURRENTLY injection must run AFTER both
+        # dedups, as the final pipeline stage. _dedup_embedded_indexes
+        # matches standalone renders against the add_table render by
+        # byte containment — injecting first would rewrite only the
+        # standalone copy, break the byte-identity, and let the pair
+        # execute twice. By construction the dedup never sees a
+        # CONCURRENTLY render.
+        if concurrently:
+            ops = _render_concurrent(ops)
         return Plan(operations=tuple(ops))
 
     def _translate(self, op, engine: Engine, exclude: tuple[str, ...]) -> list[PlannedOperation]:

{sqlpush-0.4.2 → sqlpush-0.5.0}/src/sqlpush/types.py

@@ -19,6 +19,11 @@ class PlannedOperation:
     sql: str
     table: str | None = None
     column: str | None = None
+    # True when the op's SQL was rendered with CONCURRENTLY (the
+    # executor's authoritative routing signal for generated plans;
+    # hand-built plans keep the SQL-substring fallback). Defaults False
+    # so every pre-existing construction site is unchanged.
+    concurrent: bool = False
 
 
 @dataclass(frozen=True)
@@ -44,6 +49,7 @@ class Plan:
                     "table": op.table,
                     "column": op.column,
                     "sql": op.sql,
+                    "concurrent": op.concurrent,
                 }
                 for op in self.operations
             ],

sqlpush-0.4.2/src/sqlpush/chain/migrate.py

@@ -1,226 +0,0 @@
-"""migrate/stamp: chain replay + bootstrap with gates and bookkeeping.
-
-migrate execution contract (spec 2026-09-02 §5): each file's WHOLE TEXT is
-replayed in ONE ``exec_driver_sql()`` call inside a per-file transaction —
-the parsed ``ops`` are for gating/display only, NEVER reconstructed for
-execution (psycopg3 accepts multi-statement strings; nothing is tokenized,
-so dollar-quoted bodies are safe). The checksum row is inserted INSIDE the
-same transaction as the file's SQL — bookkeeping in a separate txn would
-let a crash between apply and registry re-apply the file forever
-(crash-loop over existing objects).
-
-Fail-loud ordering: any blocked file (parse error, checksum mismatch,
-destructive gate, SQL failure) stops the chain — nothing later runs (R4).
-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
-
-from sqlalchemy import text
-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, SqlpushError
-
-_VERSIONS_DDL = (
-    "CREATE TABLE IF NOT EXISTS public.sqlpush_versions ("
-    "name TEXT PRIMARY KEY, sha256 TEXT NOT NULL, "
-    "applied_at timestamptz NOT NULL DEFAULT now())"
-)
-
-
-def _chain_files(chain_dir: str | Path) -> list[Path]:
-    chain_path = Path(chain_dir)
-    if not chain_path.is_dir():
-        # a typo'd --dir silently no-op'ing is the footgun; an empty-but-
-        # EXISTING dir is a legitimate idle run (versions table still ensured)
-        raise MigrationFileError(f"chain dir not found: {chain_path}")
-    return sorted(chain_path.glob("*.sql"))
-
-
-@contextlib.contextmanager
-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
-    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)
-        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))
-            conn.commit()
-            yield conn
-        finally:
-            # best-effort unlock (executor pattern): a secondary failure here
-            # must never mask the primary outcome; the session lock dies with
-            # the connection even if this fails
-            if not conn.closed:
-                with contextlib.suppress(Exception):
-                    conn.rollback()
-                    conn.execute(text("SELECT pg_advisory_unlock(:k)"), {"k": key})
-                    conn.commit()
-
-
-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, advisory_wait=advisory_wait) 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:
-                mf = parse_migration_file(raw, name=f.name)
-            except MigrationFileError as exc:
-                blocked.append(f.name)
-                notes.append(f"{f.name}: {exc}")
-                break  # orden estricto: nada posterior corre
-            if f.name in recorded:
-                if recorded[f.name] != checksum(raw):
-                    blocked.append(f.name)
-                    notes.append(f"{f.name}: checksum mismatch (edited after apply?)")
-                    break
-                skipped.append(f.name)
-                continue
-            if mf.risk is RiskClass.DESTRUCTIVE and not allow_destructive:
-                blocked.append(f.name)
-                notes.append(f"{f.name}: DESTRUCTIVE requires --allow-destructive")
-                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
-                    conn.exec_driver_sql(raw)
-                    conn.execute(
-                        text("INSERT INTO public.sqlpush_versions (name, sha256) VALUES (:n, :s)"),
-                        {"n": f.name, "s": checksum(raw)},
-                    )
-                applied.append(f.name)
-            except Exception as exc:  # noqa: BLE001 — report, no mask
-                blocked.append(f.name)
-                notes.append(f"{f.name}: {exc}")
-                partial = True
-                break
-        return MigrateReport(
-            applied=tuple(applied),
-            skipped=tuple(skipped),
-            blocked=tuple(blocked),
-            partial_failure=partial,
-            notes=tuple(notes),
-        )
-
-
-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. 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
-    header that fails to parse goes to ``blocked`` + ``notes`` and stops
-    the walk (strict order, same as migrate).
-    """
-    skipped: list[str] = []
-    blocked: list[str] = []
-    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:
-                parse_migration_file(raw, name=f.name)
-            except MigrationFileError as exc:
-                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(
-                        "INSERT INTO public.sqlpush_versions (name, sha256) VALUES (:n, :s) "
-                        "ON CONFLICT (name) DO UPDATE SET sha256 = EXCLUDED.sha256"
-                    ),
-                    {"n": f.name, "s": checksum(raw)},
-                )
-            skipped.append(f.name)
-        return MigrateReport(
-            applied=(),
-            skipped=tuple(skipped),
-            blocked=tuple(blocked),
-            partial_failure=False,
-            notes=tuple(notes),
-        )

sqlpush-0.4.2/src/sqlpush/core/classify.py

@@ -1,23 +0,0 @@
-# src/sqlpush/core/classify.py
-from __future__ import annotations
-
-from sqlpush.types import RiskClass
-
-SAFE = frozenset({"add_table", "add_column", "add_constraint", "create_hypertable"})
-DESTRUCTIVE = frozenset({"drop_column", "drop_table", "drop_index", "drop_constraint"})
-
-
-def classify(op_type: str) -> RiskClass:
-    """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:
-        return RiskClass.SAFE
-    # modify_*, add_index, raw_sql, and anything unknown
-    return RiskClass.RISKY