sqlpush 0.4.2__py3-none-any.whl → 0.5.1__py3-none-any.whl

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/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/chain/migrate.py

@@ -1,13 +1,26 @@
 """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).
+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).
@@ -19,6 +32,7 @@ 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
@@ -26,7 +40,7 @@ from pathlib import Path
 from sqlalchemy import text
 from sqlalchemy.engine import Connection, Engine
 
-from sqlpush.apply.executor import advisory_key
+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
 
@@ -46,6 +60,101 @@ def _chain_files(chain_dir: str | Path) -> list[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.
@@ -97,12 +206,15 @@ def run_migrate(
     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] = []
@@ -115,49 +227,115 @@ def run_migrate(
             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):
+        # 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}: checksum mismatch (edited after apply?)")
+                    notes.append(f"{f.name}: DESTRUCTIVE requires --allow-destructive")
                     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
+                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),

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/core/classify.py

@@ -8,13 +8,18 @@ DESTRUCTIVE = frozenset({"drop_column", "drop_table", "drop_index", "drop_constr
 
 
 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."""
+    """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:

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/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.5.1.dist-info/METADATA

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: sqlpush
+Version: 0.5.1
+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,sqlmodel,fastapi,alembic,postgresql,timescaledb,prisma,schema,migrations,database,drift,cli
+Author: Juan Miguel Contreras
+Author-email: Juan Miguel Contreras <19253629+juanmicl@users.noreply.github.com>
+License-Expression: MIT
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Dist: alembic>=1.18,<2
+Requires-Dist: psycopg[binary]>=3.2
+Requires-Dist: sqlalchemy>=2.0
+Requires-Dist: typer>=0.12
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/juanmicl/sqlpush
+Project-URL: Repository, https://github.com/juanmicl/sqlpush
+Project-URL: Issues, https://github.com/juanmicl/sqlpush/issues
+Project-URL: Changelog, https://github.com/juanmicl/sqlpush/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# sqlpush
+
+[![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)
+
+**Prisma `db push` for SQLAlchemy.** Your models are the migration.
+sqlpush diffs them (SQLAlchemy, SQLModel, anything built on `MetaData`)
+against the live PostgreSQL / TimescaleDB database, classifies every
+operation by risk (safe / risky / destructive), and applies the plan
+atomically. No migration files to write, no `upgrade` step to forget.
+Drift checks exit with codes your CI can gate on.
+
+```console
+sqlpush diff "myapp.models:metadata"      # see the SQL, ordered by risk
+sqlpush check "myapp.models:metadata"     # CI gate: exit 0/2/3
+sqlpush push "myapp.models:metadata"      # apply (destructive gated)
+```
+
+If you've run `Base.metadata.create_all()` in production and known it
+was wrong, sqlpush is for you.
+
+## Install
+
+```console
+pip install sqlpush
+```
+
+Or from source:
+
+```console
+git clone https://github.com/juanmicl/sqlpush && cd sqlpush && uv sync
+```
+
+Python 3.10 or newer. PostgreSQL only.
+
+## Why
+
+Declarative models are already the source of truth. Migration files
+re-encode what the models say, drift from them, and pile up forever.
+sqlpush closes the loop the way Prisma's `db push` does for its schema
+language, but for the SQLAlchemy ecosystem (SQLModel included):
+
+- **No migration files required.** The diff *is* the migration: computed fresh
+  from models vs. live database on every run, via alembic's autogenerate
+  engine used as a library. Files exist as a second workflow when you want
+  them (see below).
+- **Risk-aware by default.** Every operation is classified `safe` /
+  `risky` / `destructive`. Destructive ops (drops) are **blocked until
+  `--allow-destructive`**: nothing executes at all while any is present.
+- **Drift detection built for CI.** `check` plans once and reports
+  through its exit code, no output parsing; `--json` emits a stable
+  versioned contract.
+- **Safe under concurrency.** An advisory lock coordinates workers: one
+  pusher at a time, losers wait bounded
+  and re-verify, so deploy pipelines can race without corrupting anything.
+- **Hypertables without hand-written SQL.** Decorate a model with
+  `@hypertable` and the `create_hypertable` directive is planned
+  state-aware: idempotent pushes, clean checks, no false drift.
+
+If you know alembic: sqlpush is its autogenerate engine, productized
+into apply and check verbs, with no revision scripts to maintain.
+
+PostgreSQL only, by design.
+
+## The 30-second tour
+
+Point sqlpush at your metadata (`module:attribute`) and a database
+(`--dsn` or `$DATABASE_URL`):
+
+```console
+$ export DATABASE_URL="postgresql+psycopg://user:pass@host:5432/db"
+
+$ sqlpush diff "myapp.models:metadata"
+-- safe
+CREATE TABLE hero (
+    id SERIAL NOT NULL,
+    name VARCHAR(50) NOT NULL,
+    PRIMARY KEY (id)
+);
+
+-- risky
+CREATE INDEX ix_hero_name ON hero (name);
+```
+
+Push it (the destructive gate is on by default):
+
+```console
+$ sqlpush push "myapp.models:metadata"
+1 destructive operation(s) blocked; re-run with --allow-destructive
+$ echo $?
+1
+
+$ sqlpush push "myapp.models:metadata" --allow-destructive
+$ echo $?
+0
+```
+
+In CI, check drift and fail loudly (see exit codes below). Limit scope with
+repeated `--schema` / `--exclude` options.
+
+## FastAPI: retire `create_all()`
+
+Most FastAPI + SQLModel apps ship the lifespan the tutorials teach:
+
+```python
+@asynccontextmanager
+async def lifespan(app):
+    async with engine.begin() as conn:
+        await conn.run_sync(SQLModel.metadata.create_all)
+    yield
+```
+
+`create_all` creates tables that are missing. That is all it ever
+does. Add a column to a model and the database never hears about it;
+an index on an existing table, a type change, a drop: nothing.
+Production drifts from the models in silence, so every real change
+still rides the alembic treadmill: autogenerate, review, upgrade, and
+two histories to keep in agreement forever.
+
+The sqlpush lifespan is one line:
+
+```python
+from contextlib import asynccontextmanager
+from sqlpush import aensure_schema
+
+
+@asynccontextmanager
+async def lifespan(app):
+    await aensure_schema(SQLModel.metadata, engine, mode="check")
+    yield
+```
+
+`mode="check"` verifies the models against the database at startup and
+raises when they disagree: the app refuses to boot against a schema it
+does not match, which beats failing on the first query at 3am. The
+schema change itself comes from wherever you put it: `sqlpush push` in
+the deploy pipeline (destructive ops gated), or
+`aensure_schema(..., mode="push")` when you want the API to apply it.
+
+asyncpg URLs work too: a DSN or `AsyncEngine` spelling
+`postgresql+asyncpg` is translated to the psycopg driver automatically,
+and asyncpg is never required in the sqlpush process.
+
+Push in the deploy pipeline, check at boot.
+
+## An inherited database
+
+The first `check` against a database with history often reports drift:
+hand-built indexes, audit tables, a column someone added by hand. If
+any of the drift looks destructive, `check` exits `3` and `push`
+blocks. That is the tool refusing to silently drop your legacy
+objects. Two escape hatches: `--exclude` accepts objects you choose to
+keep (fnmatch patterns, repeatable), and `--allow-destructive` accepts
+the drops when you really do want them.
+
+## When you want files: the chain
+
+Most changes never need a file. When one does, sqlpush has a second
+workflow built on the same diff engine: the chain. `revision` writes
+the next numbered SQL file from your models against a reference DB,
+`migrate` replays pending files with gates and checksums, and `stamp`
+adopts an existing database without executing anything.
+
+The files are plain SQL you can review, edit before first apply, and
+run under `psql`. Schema change and data backfill ship as one file.
+The [chain guide](docs/the-chain.md) covers the format, the gates and
+the workflows.
+
+## Exit codes
+
+| verb | 0 | 1 | 2 | 3 |
+| --- | --- | --- | --- | --- |
+| `diff` | always | | | |
+| `check` | clean | | drift | destructive drift |
+| `push` | applied | destructive blocked | error (incl. partial failure) | |
+| `revision` | file written | error (empty drift refuses) | | |
+| `migrate` | clean | blocked or partial failure | | |
+| `stamp` | registered | blocked or refused | | |
+
+Failures print a typed error on stderr, never a traceback.
+
+`push --safe-only` runs only safe operations and skips the rest
+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. `stamp` refuses a file whose
+checksum no longer matches the registry; `--force` accepts the new
+content.
+
+The knobs, per verb:
+
+| verb | flags |
+| --- | --- |
+| `push` | `--allow-destructive` `--safe-only` `--no-lock` `--lock-timeout` `--advisory-wait` `--no-concurrently` `--statement-timeout` |
+| `revision` | `--ref-dsn` (required) `-m/--message` `--no-concurrently` `--dir` |
+| `migrate` | `--allow-destructive` `--advisory-wait` `--lock-timeout` `--statement-timeout` `--dir` |
+| `stamp` | `--force` `--dir` |
+
+Every verb except `revision` takes `--dsn` (or `$DATABASE_URL`).
+`revision` requires `--ref-dsn`, with no env fallback: the reference
+DB is a different database from the push target. `diff`, `check`,
+`push` and `revision` also take repeatable `--schema` / `--exclude`.
+Timeouts are seconds; a `lock_timeout` bounds how long a statement
+waits on a lock before failing, `statement_timeout` bounds each
+statement's runtime, and an exhausted `advisory-wait` raises instead
+of hanging on a stuck lock holder.
+
+## How it works
+
+```mermaid
+flowchart LR
+    models["SQLAlchemy MetaData"] --> diff["diff<br>alembic autogenerate, scoped"]
+    db[("live PostgreSQL")] --> diff
+    diff --> risk["risk classification<br>safe / risky / destructive"]
+    risk --> plan["plan"]
+    plan --> render["render"]
+    render --> apply["apply<br>atomic txn · CONCURRENTLY split · advisory lock"]
+    apply --> report["report"]
+```
+
+- **Diff engine** scopes reflection to your target schemas and prunes
+  system catalogs (TimescaleDB 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: concurrent index builds run one per
+  transaction on autocommit, 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.
+
+Scoping: `--schema` restricts the diff to named schemas (default: the
+session's real `search_path`). Extension-owned schemas never enter
+scope automatically, and schemas you pass explicitly are never
+filtered. The chain's registry table (`public.sqlpush_versions`)
+always lives in `public` and is pruned from every diff, so `check`
+after `migrate` is clean. `alembic_version` gets the same treatment.
+
+## Comparison
+
+An honest view of the neighborhood (stars as of 2026-08):
+
+| | migration files | source of truth | risk gate | CI drift exit codes | TimescaleDB |
+| --- | --- | --- | --- | --- | --- |
+| **sqlpush** | optional: push needs none; the chain has reviewable, checksummed files | SQLAlchemy `MetaData` | classified safe/risky/destructive, destructive blocked by default | `check` 0/2/3 | `@hypertable` directives |
+| [alembic](https://github.com/sqlalchemy/alembic) (4.4k★) | yes | migration scripts (autogenerate assists) | no | no | no |
+| [atlas](https://github.com/ariga/atlas) (8.7k★) | optional (HCL) | HCL / SQL (ORMs via providers) | lint policies | yes | no |
+| [prisma `db push`](https://www.prisma.io/docs/orm/reference/prisma-cli-reference) (47k★) | none | Prisma schema (Node/TS) | no | no | no |
+| [migra](https://github.com/djrobstep/migra) (3.1k★) | diff only | SQL | n/a | partial | no (*deprecated*) |
+
+sqlpush is narrower than atlas and younger than alembic, deliberately.
+It is one tool for one job: keep a PostgreSQL schema in lockstep with
+SQLAlchemy models, safely enough to run from CI.
+
+Guides: [the chain](docs/the-chain.md) (file format, gates, backfills),
+[migrating from alembic](docs/migrating-from-alembic.md), and
+[migrating from migra](docs/migrating-from-migra.md) (deprecated).
+Changes land in the [CHANGELOG](CHANGELOG.md).
+
+## Design notes
+
+- `import sqlpush` stays light: the public API loads lazily, so the
+  annotations module carries none of alembic/typer/psycopg.
+- 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 (operations now carry
+  a `concurrent` boolean).

sqlpush-0.5.1.dist-info/RECORD

@@ -0,0 +1,20 @@
+sqlpush/__init__.py,sha256=Px0jJFHbwwM1-UHtDwD3xQlRifEMW4StSXQs5DD9z6w,1697
+sqlpush/annotations.py,sha256=xe5EoYPvraLJy-WvMkFK_zOIKquB3-VsrAzy6HE_hiA,4652
+sqlpush/api.py,sha256=JTIDn-O50j9ytVTMRXJVu6eZcGbCX_v-03zqJ23laig,11235
+sqlpush/apply/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlpush/apply/executor.py,sha256=qHvfxB1sWQAQ0oMPDGuEr-HRaJwOYoVSB_s-7x-CZTc,10087
+sqlpush/chain/__init__.py,sha256=AJ96P3I63mX6-uMuK0paCpKtaRexufnCqjUuElbyAsM,293
+sqlpush/chain/format.py,sha256=uj0iMQfFWa9HpKhrokfJu_5B_FesiD4qCZxAGDJ3bfQ,4938
+sqlpush/chain/migrate.py,sha256=P2grgrg8dkLJCBhL6CzNwa4xG8-VuFLqgN7XuvjFhwQ,18575
+sqlpush/cli.py,sha256=7bjfh_YcFs4yIJtTS44YWr2YWQwGNuccHirkdorJXm4,11099
+sqlpush/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlpush/core/classify.py,sha256=xjBFIPAV8lxMsZZRiOQ1Yxlpgz4r-ZpCtnNXA4KAw0o,1290
+sqlpush/core/diff.py,sha256=OkH0fLl9NLOyWFnefknvBK8SWeN6bnJz4kQJfK3-wFA,26552
+sqlpush/core/render.py,sha256=9SNEyHOGmMxKUfIjvo3x0MNVQ6N2o2fl3noWT1EWO3M,609
+sqlpush/directives/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+sqlpush/directives/timescale.py,sha256=W_Cd_stdhKZlzlMum7Bdzq99VfXOulYxq0B-sukz-xE,2645
+sqlpush/types.py,sha256=hXetdVqMzYcBQi0M_x3qmCIOa3QzhuwxYNJkZRWz4qM,3280
+sqlpush-0.5.1.dist-info/WHEEL,sha256=y6e-a5KI2W-qDAJKfh9Xr81bin8NgUdfWgz3VSXXpe4,80
+sqlpush-0.5.1.dist-info/entry_points.txt,sha256=VYha3PJSvklRgpcDAZYJdE66EXM79MSKQf0z8igyAOI,46
+sqlpush-0.5.1.dist-info/METADATA,sha256=ZxtbwPr8QWKh40NMrRpn87B_uGoMUleqYHYC-UzIZUM,12518
+sqlpush-0.5.1.dist-info/RECORD,,

sqlpush-0.4.2.dist-info/METADATA

@@ -1,214 +0,0 @@
-Metadata-Version: 2.4
-Name: sqlpush
-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
-Author-email: Juan Miguel Contreras <19253629+juanmicl@users.noreply.github.com>
-License-Expression: MIT
-Classifier: Development Status :: 4 - Beta
-Classifier: Environment :: Console
-Classifier: Intended Audience :: Developers
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Database
-Classifier: Topic :: Software Development :: Quality Assurance
-Requires-Dist: alembic>=1.18,<2
-Requires-Dist: psycopg[binary]>=3.2
-Requires-Dist: sqlalchemy>=2.0
-Requires-Dist: typer>=0.12
-Requires-Python: >=3.10
-Project-URL: Homepage, https://github.com/juanmicl/sqlpush
-Project-URL: Repository, https://github.com/juanmicl/sqlpush
-Project-URL: Issues, https://github.com/juanmicl/sqlpush/issues
-Project-URL: Changelog, https://github.com/juanmicl/sqlpush/blob/main/CHANGELOG.md
-Description-Content-Type: text/markdown
-
-# sqlpush
-
-[![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)
-
-**Prisma `db push` for SQLAlchemy.** Apply your models (SQLAlchemy,
-SQLModel, anything built on `MetaData`) to a live PostgreSQL / TimescaleDB
-database directly, no migration files. sqlpush
-diffs your models against the real schema, classifies every operation by
-risk (safe / risky / destructive), and applies the plan atomically. Drift
-checks exit with codes your CI can gate on.
-
-```console
-sqlpush diff "myapp.models:metadata"      # see the SQL, ordered by risk
-sqlpush check "myapp.models:metadata"     # CI gate: exit 0/2/3
-sqlpush push "myapp.models:metadata"      # apply (destructive gated)
-```
-
-If you've ever run `Base.metadata.create_all()` in production and known it
-was wrong, then sighed at the migration-script treadmill when you reached
-for alembic: sqlpush is for you.
-
-## Why
-
-Declarative models are already the source of truth. Migration files
-re-encode what the models say, drift from them, and pile up forever.
-sqlpush closes the loop the way Prisma's `db push` does for its schema
-language, but for the SQLAlchemy ecosystem (SQLModel included):
-
-- **No migration files, ever.** The diff *is* the migration: computed fresh
-  from models vs. live database on every run, via alembic's autogenerate
-  engine used as a library.
-- **Risk-aware by default.** Every operation is classified `safe` /
-  `risky` / `destructive`. Destructive ops (drops) are **blocked until
-  `--allow-destructive`**: nothing executes at all while any is present.
-- **Drift detection built for CI.** `check` plans once and exits `0` clean /
-  `2` drift / `3` destructive drift, scriptable without parsing output.
-  `--json` emits a stable versioned contract.
-- **Safe under concurrency.** An advisory lock (keyed to the database, not
-  the DSN) coordinates workers: one pusher at a time, losers wait bounded
-  and re-verify, so deploy pipelines can race without corrupting anything.
-- **Hypertables without hand-written SQL.** Decorate a model with
-  `@hypertable` and the `create_hypertable` directive is planned
-  state-aware: idempotent pushes, clean checks, no false drift.
-
-PostgreSQL only, by design.
-
-## Install
-
-```console
-pip install sqlpush
-```
-
-Or from source:
-
-```console
-git clone https://github.com/juanmicl/sqlpush && cd sqlpush && uv sync
-```
-
-## The 30-second tour
-
-Point sqlpush at your metadata (`module:attribute`) and a database
-(`--dsn` or `$DATABASE_URL`):
-
-```console
-$ export DATABASE_URL="postgresql+psycopg://user:pass@host:5432/db"
-
-$ sqlpush diff "myapp.models:metadata"
--- safe
-
-CREATE TABLE hero (
-    id SERIAL NOT NULL PRIMARY KEY,
-    name VARCHAR(50) NOT NULL
-);
-
--- risky
-
-CREATE INDEX ix_hero_name ON hero (name);
-```
-
-Push it (the destructive gate is on by default):
-
-```console
-$ sqlpush push "myapp.models:metadata"
-1 destructive operation(s) blocked; re-run with --allow-destructive
-$ echo $?
-1
-
-$ sqlpush push "myapp.models:metadata" --allow-destructive
-$ echo $?
-0
-```
-
-In CI, check drift and fail loudly (see exit codes below). Limit scope with
-repeated `--schema` / `--exclude` options.
-
-## Exit codes
-
-| verb | 0 | 1 | 2 | 3 |
-| --- | --- | --- | --- | --- |
-| `diff` | always | | | |
-| `check` | clean | | drift | destructive drift |
-| `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.
-
-## FastAPI / SQLModel: replace `create_all`
-
-```python
-from contextlib import asynccontextmanager
-from sqlpush import aensure_schema
-
-
-@asynccontextmanager
-async def lifespan(app):
-    await aensure_schema(SQLModel.metadata, engine, mode="check")
-    yield
-```
-
-Push in the deploy pipeline, check at startup.
-
-## How it works
-
-```mermaid
-flowchart LR
-    models["SQLAlchemy MetaData"] --> diff["diff<br>alembic autogenerate, scoped"]
-    db[("live PostgreSQL")] --> diff
-    diff --> risk["risk classification<br>safe / risky / destructive"]
-    risk --> plan["plan"]
-    plan --> render["render"]
-    render --> apply["apply<br>atomic txn · CONCURRENTLY split · advisory lock"]
-    apply --> report["report"]
-```
-
-- **Diff engine** scopes reflection to your target schemas (default: the
-  session's real `search_path`) and prunes system catalogs (TimescaleDB
-  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`.
-- **Typed errors**: only `SqlpushError` / `ConnectFailed` /
-  `MetadataImportError` escape the API, never raw driver exceptions.
-
-## Comparison
-
-An honest view of the neighborhood (stars as of 2026-08):
-
-| | migration files | source of truth | risk gate | CI drift exit codes | TimescaleDB |
-| --- | --- | --- | --- | --- | --- |
-| **sqlpush** | none (the diff is the migration) | SQLAlchemy `MetaData` | classified safe/risky/destructive, destructive blocked by default | `check` 0/2/3 | `@hypertable` directives |
-| [alembic](https://github.com/sqlalchemy/alembic) (4.4k★) | yes | migration scripts (autogenerate assists) | no | no | no |
-| [atlas](https://github.com/ariga/atlas) (8.7k★) | optional (HCL) | HCL / SQL (ORMs via providers) | lint policies | yes | no |
-| [prisma `db push`](https://www.prisma.io/docs/orm/reference/prisma-cli-reference) (47k★) | none | Prisma schema (Node/TS) | no | no | no |
-| [migra](https://github.com/djrobstep/migra) (3.1k★) | diff only | SQL | n/a | partial | no (*deprecated*) |
-
-sqlpush is narrower than atlas and younger than alembic, deliberately.
-It is one tool for one job: keep a PostgreSQL schema in lockstep with
-SQLAlchemy models, safely enough to run from CI.
-
-Coming from [migra](https://github.com/djrobstep/migra) (now
-deprecated)? There is a [migration guide](docs/migrating-from-migra.md).
-
-## Design notes
-
-- `import sqlpush` stays light: the public API loads lazily, so the
-  annotations module carries none of alembic/typer/psycopg.
-- 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.
-
-## 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
-
-[MIT](LICENSE) · © 2026 Juan Miguel Contreras

sqlpush-0.4.2.dist-info/RECORD

@@ -1,20 +0,0 @@
-sqlpush/__init__.py,sha256=Px0jJFHbwwM1-UHtDwD3xQlRifEMW4StSXQs5DD9z6w,1697
-sqlpush/annotations.py,sha256=xe5EoYPvraLJy-WvMkFK_zOIKquB3-VsrAzy6HE_hiA,4652
-sqlpush/api.py,sha256=7fHsy1AHd2ffca-wtQDowfpt70P7c6L0_s720k8gRcU,10166
-sqlpush/apply/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sqlpush/apply/executor.py,sha256=-HgmscUO6M_xQ5HPBQhJkUo6XwEPPqBig7_G9aWQJAU,7242
-sqlpush/chain/__init__.py,sha256=AJ96P3I63mX6-uMuK0paCpKtaRexufnCqjUuElbyAsM,293
-sqlpush/chain/format.py,sha256=uj0iMQfFWa9HpKhrokfJu_5B_FesiD4qCZxAGDJ3bfQ,4938
-sqlpush/chain/migrate.py,sha256=P7I07Zv3xRmRYgFTTLAqkrUdbjsGOGNQZG2j-eP5Hgk,10055
-sqlpush/cli.py,sha256=7TBKMxmvkpwSH6gyqs2fDQ5Tyec1yMOLGJCUJb-2Af0,10599
-sqlpush/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sqlpush/core/classify.py,sha256=-HNPQ1Kfnr0MMYLoP26_VC14JjcQHravrbT7lPGqlIU,927
-sqlpush/core/diff.py,sha256=q0f7NtiKQ8N33UbI40ttxgiNbsAsBpqa0XJ15oTLSBY,24147
-sqlpush/core/render.py,sha256=9SNEyHOGmMxKUfIjvo3x0MNVQ6N2o2fl3noWT1EWO3M,609
-sqlpush/directives/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-sqlpush/directives/timescale.py,sha256=W_Cd_stdhKZlzlMum7Bdzq99VfXOulYxq0B-sukz-xE,2645
-sqlpush/types.py,sha256=IMA1HRLIumat7tpt8Yscv-9g2U5U_--xxnfcf_pfkyo,2938
-sqlpush-0.4.2.dist-info/WHEEL,sha256=y6e-a5KI2W-qDAJKfh9Xr81bin8NgUdfWgz3VSXXpe4,80
-sqlpush-0.4.2.dist-info/entry_points.txt,sha256=VYha3PJSvklRgpcDAZYJdE66EXM79MSKQf0z8igyAOI,46
-sqlpush-0.4.2.dist-info/METADATA,sha256=KwaHMTxd1Upr_Mf2GbulnbnY3MY58NfBLNBacSNQjWE,8373
-sqlpush-0.4.2.dist-info/RECORD,,