pipelantic-sql 0.6.0__tar.gz

pipelantic_sql-0.6.0/.gitignore

@@ -0,0 +1,21 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+.eggs/
+dist/
+build/
+site/
+.venv/
+venv/
+.env
+
+# Tools
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+.DS_Store
+examples/_file_storage_out/

pipelantic_sql-0.6.0/PKG-INFO

@@ -0,0 +1,56 @@
+Metadata-Version: 2.4
+Name: pipelantic-sql
+Version: 0.6.0
+Summary: PostgreSQL reference SQL execution plugin for Pipelantic.
+Author-email: Odo Matthews <odosmatthews@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.11
+Requires-Dist: pipelantic<0.7,>=0.6.0
+Requires-Dist: psycopg[binary]<4,>=3.1
+Requires-Dist: sqlalchemy<3,>=2.0
+Provides-Extra: sqlite
+Description-Content-Type: text/markdown
+
+# pipelantic-sql
+
+PostgreSQL reference SQL execution plugin for [Pipelantic](https://github.com/eddiethedean/pipelantic).
+
+```bash
+pip install pipelantic-sql
+# or: pip install 'pipelantic[sql]'
+export PIPELANTIC_SQL_URL=postgresql+psycopg://user:pass@localhost:5432/pipelantic
+# SQLite is fine for demos only:
+# export PIPELANTIC_SQL_URL=sqlite+pysqlite:///:memory:
+```
+
+Uses SQLAlchemy Core. Driver dependencies stay out of `pipelantic` core.
+
+## Wiring
+
+```python
+from pipelantic import Profile
+
+Profile(name="sql-prod", sql_engine="sql")
+```
+
+Register `@Transformation.implementation("sql")` handlers that take
+`RelationRef` inputs and return SQL query handles (not fetched rows).
+
+## Capabilities (0.6)
+
+- SQL→SQL fusion without intermediate Python row fetch
+- Durable run-scoped staging tables (not session TEMP)
+- Insert-select / CTAS-style publication
+- Fail-closed planning when required capabilities are missing
+
+**Not included:** `MERGE` / upsert (`sql_merge=False`). Requiring merge fails
+at planning.
+
+## Examples
+
+```bash
+python examples/sql_to_sql.py
+python examples/sql_boundary_hybrid.py
+python examples/sql_transactional_write.py
+python examples/sql_failure_recovery.py
+```

pipelantic_sql-0.6.0/README.md

@@ -0,0 +1,43 @@
+# pipelantic-sql
+
+PostgreSQL reference SQL execution plugin for [Pipelantic](https://github.com/eddiethedean/pipelantic).
+
+```bash
+pip install pipelantic-sql
+# or: pip install 'pipelantic[sql]'
+export PIPELANTIC_SQL_URL=postgresql+psycopg://user:pass@localhost:5432/pipelantic
+# SQLite is fine for demos only:
+# export PIPELANTIC_SQL_URL=sqlite+pysqlite:///:memory:
+```
+
+Uses SQLAlchemy Core. Driver dependencies stay out of `pipelantic` core.
+
+## Wiring
+
+```python
+from pipelantic import Profile
+
+Profile(name="sql-prod", sql_engine="sql")
+```
+
+Register `@Transformation.implementation("sql")` handlers that take
+`RelationRef` inputs and return SQL query handles (not fetched rows).
+
+## Capabilities (0.6)
+
+- SQL→SQL fusion without intermediate Python row fetch
+- Durable run-scoped staging tables (not session TEMP)
+- Insert-select / CTAS-style publication
+- Fail-closed planning when required capabilities are missing
+
+**Not included:** `MERGE` / upsert (`sql_merge=False`). Requiring merge fails
+at planning.
+
+## Examples
+
+```bash
+python examples/sql_to_sql.py
+python examples/sql_boundary_hybrid.py
+python examples/sql_transactional_write.py
+python examples/sql_failure_recovery.py
+```

pipelantic_sql-0.6.0/pyproject.toml

@@ -0,0 +1,26 @@
+[project]
+name = "pipelantic-sql"
+version = "0.6.0"
+description = "PostgreSQL reference SQL execution plugin for Pipelantic."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "Odo Matthews", email = "odosmatthews@gmail.com" }]
+dependencies = [
+    "pipelantic>=0.6.0,<0.7",
+    "sqlalchemy>=2.0,<3",
+    "psycopg[binary]>=3.1,<4",
+]
+
+[project.optional-dependencies]
+sqlite = []
+
+[project.entry-points."pipelantic.sql_plugins"]
+sql = "pipelantic_sql:create_plugin"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/pipelantic_sql"]

pipelantic_sql-0.6.0/src/pipelantic_sql/__init__.py

@@ -0,0 +1,9 @@
+"""pipelantic-sql — PostgreSQL reference SQL execution plugin."""
+
+from __future__ import annotations
+
+__version__ = "0.6.0"
+
+from pipelantic_sql.plugin import PostgresSqlPlugin, create_plugin
+
+__all__ = ["PostgresSqlPlugin", "__version__", "create_plugin"]

pipelantic_sql-0.6.0/src/pipelantic_sql/catalog.py

@@ -0,0 +1,54 @@
+"""Catalog / information_schema inspection (metadata only, no row reads)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from sqlalchemy import text
+from sqlalchemy.engine import Engine
+
+from pipelantic.sql.helpers import require_safe_identifier
+from pipelantic.sql.protocol import RelationRef
+from pipelantic_sql.dialect_postgresql import quote_identifier
+
+
+def inspect_relation(
+    engine: Engine,
+    relation: RelationRef,
+    *,
+    dialect: str,
+) -> dict[str, Any]:
+    schema = relation.namespace
+    table = relation.name
+    require_safe_identifier(table)
+    if dialect == "postgresql":
+        sql = text(
+            """
+            SELECT column_name, data_type, is_nullable
+            FROM information_schema.columns
+            WHERE table_name = :table
+              AND (:schema IS NULL OR table_schema = :schema)
+            ORDER BY ordinal_position
+            """
+        )
+        with engine.connect() as conn:
+            rows = conn.execute(sql, {"table": table, "schema": schema}).mappings()
+            columns = {
+                r["column_name"]: {
+                    "type": r["data_type"],
+                    "nullable": r["is_nullable"] == "YES",
+                }
+                for r in rows
+            }
+    else:
+        with engine.connect() as conn:
+            rows = conn.execute(
+                text(f"PRAGMA table_info({quote_identifier(table, dialect=dialect)})")
+            )
+            columns = {r[1]: {"type": r[2], "nullable": not bool(r[3])} for r in rows}
+    return {
+        "identity": relation.qualified_name,
+        "columns": columns,
+        "source": "catalog",
+        "dialect": dialect,
+    }

pipelantic_sql-0.6.0/src/pipelantic_sql/compiler.py

@@ -0,0 +1,190 @@
+"""Compile portable SQL IR into parameterized dialect SQL."""
+
+from __future__ import annotations
+
+from typing import Any
+from uuid import uuid4
+
+from pipelantic.sql.helpers import require_safe_identifier
+from pipelantic.sql.protocol import (
+    AliasedExpr,
+    AtomicPublicationStrategy,
+    ColumnRef,
+    CompiledSql,
+    ConcatExpr,
+    LiteralExpr,
+    RelationRef,
+    SqlExecutionContext,
+    SqlQuery,
+    SqlWrite,
+    WriteIntentKind,
+)
+from pipelantic_sql.dialect_postgresql import quote_identifier
+
+
+class SqlCompiler:
+    """IR → parameterized SQL text (values never interpolated)."""
+
+    def __init__(self, *, dialect: str, supports_merge: bool) -> None:
+        self.dialect = dialect
+        self.supports_merge = supports_merge
+        self._param_counter = 0
+
+    def quote(self, name: str) -> str:
+        return quote_identifier(name, dialect=self.dialect)
+
+    def qid(self, relation: RelationRef) -> str:
+        parts = []
+        for part in (relation.catalog, relation.namespace, relation.name):
+            if part:
+                parts.append(self.quote(require_safe_identifier(part)))
+        return ".".join(parts)
+
+    def next_param(self, params: dict[str, Any], value: Any) -> str:
+        self._param_counter += 1
+        name = f"p{self._param_counter}"
+        params[name] = value
+        return f":{name}"
+
+    def compile_expr(
+        self, expr: Any, *, params: dict[str, Any], relation_sql: str
+    ) -> str:
+        if isinstance(expr, ColumnRef):
+            col = self.quote(require_safe_identifier(expr.column))
+            if expr.relation:
+                return f"{self.quote(expr.relation)}.{col}"
+            return col
+        if isinstance(expr, str):
+            return self.quote(require_safe_identifier(expr))
+        if isinstance(expr, LiteralExpr):
+            return self.next_param(params, expr.value)
+        if isinstance(expr, ConcatExpr):
+            rendered = [
+                self.compile_expr(p, params=params, relation_sql=relation_sql)
+                for p in expr.parts
+            ]
+            pieces: list[str] = []
+            for i, part in enumerate(rendered):
+                if i:
+                    pieces.append(self.next_param(params, expr.separator))
+                pieces.append(part)
+            body = " || ".join(pieces)
+            if expr.alias:
+                return f"{body} AS {self.quote(expr.alias)}"
+            return body
+        if isinstance(expr, AliasedExpr):
+            inner = self.compile_expr(
+                expr.expr, params=params, relation_sql=relation_sql
+            )
+            return f"{inner} AS {self.quote(expr.alias)}"
+        raise ValueError(f"Unsupported SQL expression: {type(expr)!r}")
+
+    def compile_query(
+        self,
+        query: SqlQuery,
+        *,
+        context: SqlExecutionContext,
+    ) -> CompiledSql:
+        params: dict[str, Any] = {}
+        source_sql = self.qid(query.source)
+        if query.columns:
+            cols = ", ".join(
+                self.compile_expr(c, params=params, relation_sql=source_sql)
+                for c in query.columns
+            )
+        else:
+            cols = "*"
+        distinct = "DISTINCT " if query.distinct else ""
+        sql = f"SELECT {distinct}{cols} FROM {source_sql}"
+        if query.where is not None:
+            sql += " WHERE " + self.compile_expr(
+                query.where, params=params, relation_sql=source_sql
+            )
+        if query.limit is not None:
+            sql += f" LIMIT {int(query.limit)}"
+        return CompiledSql(
+            statement_id=f"stmt:{context.step_name}:{uuid4().hex[:8]}",
+            text=sql,
+            param_names=tuple(params.keys()),
+            redacted_params={k: "<redacted>" for k in params},
+            dialect=self.dialect,
+            logical_nodes=(context.step_name,),
+            metadata={"_bound_params": params},
+        )
+
+    def compile_write(
+        self,
+        write: SqlWrite,
+        *,
+        context: SqlExecutionContext,
+    ) -> CompiledSql:
+        target = self.qid(write.target)
+        if write.intent in {
+            WriteIntentKind.APPEND,
+            WriteIntentKind.INSERT_SELECT,
+        }:
+            if isinstance(write.source, SqlQuery):
+                compiled = self.compile_query(write.source, context=context)
+                sql = f"INSERT INTO {target} {compiled.text}"
+                bound = dict(compiled.metadata.get("_bound_params") or {})
+                return CompiledSql(
+                    statement_id=f"write:{context.step_name}:{uuid4().hex[:8]}",
+                    text=sql,
+                    param_names=tuple(bound.keys()),
+                    redacted_params={k: "<redacted>" for k in bound},
+                    dialect=self.dialect,
+                    logical_nodes=(context.step_name,),
+                    metadata={"_bound_params": bound, "intent": write.intent.value},
+                )
+            if isinstance(write.source, RelationRef):
+                sql = f"INSERT INTO {target} SELECT * FROM {self.qid(write.source)}"
+                return CompiledSql(
+                    statement_id=f"write:{context.step_name}:{uuid4().hex[:8]}",
+                    text=sql,
+                    dialect=self.dialect,
+                    logical_nodes=(context.step_name,),
+                    metadata={"intent": write.intent.value},
+                )
+        if write.intent in {WriteIntentKind.REPLACE, WriteIntentKind.SNAPSHOT}:
+            if write.atomic is AtomicPublicationStrategy.UNSUPPORTED:
+                raise ValueError("Atomic publication unsupported for replace")
+            # Only create staging here. Executor publishes via rename-swap so the
+            # live target is never dropped before the replacement exists.
+            staging = RelationRef(
+                name=f"{write.target.name}__staging_{uuid4().hex[:8]}",
+                namespace=write.target.namespace,
+                catalog=write.target.catalog,
+            )
+            if isinstance(write.source, SqlQuery):
+                compiled = self.compile_query(write.source, context=context)
+                create = f"CREATE TABLE {self.qid(staging)} AS {compiled.text}"
+                bound = dict(compiled.metadata.get("_bound_params") or {})
+            elif isinstance(write.source, RelationRef):
+                create = (
+                    f"CREATE TABLE {self.qid(staging)} AS "
+                    f"SELECT * FROM {self.qid(write.source)}"
+                )
+                bound = {}
+            else:
+                raise ValueError("Replace requires a source query or relation")
+            return CompiledSql(
+                statement_id=f"replace:{context.step_name}:{uuid4().hex[:8]}",
+                text=create,
+                param_names=tuple(bound.keys()),
+                redacted_params={k: "<redacted>" for k in bound},
+                dialect=self.dialect,
+                logical_nodes=(context.step_name,),
+                metadata={
+                    "_bound_params": bound,
+                    "intent": write.intent.value,
+                    "staging": staging.to_dict(),
+                    "target": write.target.to_dict(),
+                    "needs_publish_swap": True,
+                },
+            )
+        if write.intent is WriteIntentKind.MERGE:
+            raise ValueError(
+                "MERGE is not implemented by the 0.6 reference plugin; "
+                "fail closed before mutation"
+            )
+        raise ValueError(f"Unsupported write intent: {write.intent}")

pipelantic_sql-0.6.0/src/pipelantic_sql/dialect_postgresql.py

@@ -0,0 +1,26 @@
+"""Dialect helpers for identifier quoting and dialect detection."""
+
+from __future__ import annotations
+
+import re
+
+from pipelantic.sql.helpers import require_safe_identifier
+
+_IDENT = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+
+def detect_dialect(url: str) -> str:
+    if url.startswith("postgresql"):
+        return "postgresql"
+    return "sqlite"
+
+
+def quote_identifier(name: str, *, dialect: str = "postgresql") -> str:
+    """Quote a validated SQL identifier (double-quotes for PG and SQLite)."""
+    require_safe_identifier(name)
+    _ = dialect  # both reference dialects use ANSI double-quotes
+    return f'"{name}"'
+
+
+def is_safe_ident(name: str) -> bool:
+    return bool(_IDENT.fullmatch(name))

pipelantic_sql-0.6.0/src/pipelantic_sql/executor.py

@@ -0,0 +1,344 @@
+"""Connection / transaction execution for compiled SQL."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping, MutableMapping, Sequence
+from typing import Any
+
+from sqlalchemy import text
+from sqlalchemy.engine import Engine
+from sqlalchemy.exc import DBAPIError, InterfaceError, OperationalError
+
+from pipelantic.sql.helpers import require_safe_identifier
+from pipelantic.sql.protocol import (
+    CompiledSql,
+    RelationRef,
+    SqlExecutionContext,
+    SqlExecutionResult,
+    SqlMetrics,
+    SqlQuery,
+    TransactionOutcome,
+)
+from pipelantic_sql.compiler import SqlCompiler
+from pipelantic_sql.dialect_postgresql import quote_identifier
+
+
+def _classify_failure(exc: BaseException, *, started: bool) -> TransactionOutcome:
+    """Classify transaction failure; ambiguous post-start failures → UNKNOWN."""
+    if isinstance(exc, (InterfaceError, OperationalError)):
+        return TransactionOutcome.UNKNOWN if started else TransactionOutcome.ROLLED_BACK
+    if isinstance(exc, DBAPIError) and getattr(exc, "connection_invalidated", False):
+        return TransactionOutcome.UNKNOWN
+    msg = str(exc).lower()
+    if started and (
+        "commit" in msg
+        or "connection" in msg
+        or "server closed" in msg
+        or "broken pipe" in msg
+    ):
+        return TransactionOutcome.UNKNOWN
+    return TransactionOutcome.ROLLED_BACK
+
+
+class SqlExecutor:
+    """Run compiled statements inside a transaction."""
+
+    def __init__(
+        self,
+        *,
+        engine: Engine,
+        dialect: str,
+        rows_fetched_counter: list[int],
+        bound_params: MutableMapping[str, dict[str, Any]],
+        staging_tables: list[str],
+    ) -> None:
+        self.engine = engine
+        self.dialect = dialect
+        self._rows_fetched = rows_fetched_counter
+        self._bound_params = bound_params
+        self._staging_tables = staging_tables
+
+    def _resolve_bound(
+        self, stmt: CompiledSql, params: Mapping[str, Any]
+    ) -> dict[str, Any]:
+        bound = dict(self._bound_params.pop(stmt.statement_id, {}))
+        bound.update(params)
+        return bound
+
+    def execute(
+        self,
+        compiled: Sequence[CompiledSql],
+        *,
+        params: Mapping[str, Any],
+        context: SqlExecutionContext,
+        fetch: bool = False,
+    ) -> SqlExecutionResult:
+        _ = context
+        metrics = SqlMetrics(statements=0, phases=["execute"])
+        results: list[CompiledSql] = []
+        records: list[Any] | None = None
+        outcome = TransactionOutcome.NOT_STARTED
+        started = False
+        try:
+            with self.engine.begin() as conn:
+                started = True
+                for stmt in compiled:
+                    bound = self._resolve_bound(stmt, params)
+                    public = CompiledSql(
+                        statement_id=stmt.statement_id,
+                        text=stmt.text,
+                        param_names=stmt.param_names,
+                        redacted_params=stmt.redacted_params,
+                        dialect=stmt.dialect,
+                        logical_nodes=stmt.logical_nodes,
+                        metadata={
+                            k: v
+                            for k, v in stmt.metadata.items()
+                            if not str(k).startswith("_")
+                        },
+                    )
+                    results.append(public)
+                    for part in stmt.text.split(";;"):
+                        part = part.strip()
+                        if not part:
+                            continue
+                        result = conn.execute(text(part), bound)
+                        metrics.statements += 1
+                        if fetch:
+                            rows = [dict(row._mapping) for row in result]
+                            self._rows_fetched[0] += len(rows)
+                            metrics.rows_fetched += len(rows)
+                            records = (records or []) + rows
+                        elif result.rowcount is not None and result.rowcount >= 0:
+                            metrics.rows_affected = (metrics.rows_affected or 0) + int(
+                                result.rowcount
+                            )
+                outcome = TransactionOutcome.COMMITTED
+        except Exception as exc:
+            outcome = _classify_failure(exc, started=started)
+            return SqlExecutionResult(
+                outcome=outcome,
+                metrics=metrics,
+                compiled=results,
+                diagnostics=[
+                    {
+                        "code": "PMSQL500",
+                        "severity": "error",
+                        "message": str(exc),
+                    }
+                ],
+            )
+        return SqlExecutionResult(
+            outcome=outcome,
+            metrics=metrics,
+            compiled=results,
+            records=records,
+            backend_ref=f"sqlalchemy:{self.dialect}",
+        )
+
+    def materialize_temp(
+        self,
+        compiler: SqlCompiler,
+        query: SqlQuery,
+        *,
+        temp_name: str,
+        params: Mapping[str, Any],
+        context: SqlExecutionContext,
+        seal: Any,
+    ) -> SqlExecutionResult:
+        """Materialize as a durable run-scoped table (visible across pool checkouts)."""
+        require_safe_identifier(temp_name)
+        compiled = seal(compiler.compile_query(query, context=context))
+        bound = dict(self._bound_params.get(compiled.statement_id) or {})
+        bound.update(params)
+        # Re-register after peek so execute can consume.
+        if bound:
+            self._bound_params[compiled.statement_id] = bound
+        qid = quote_identifier(temp_name, dialect=self.dialect)
+        sql = f"DROP TABLE IF EXISTS {qid};;CREATE TABLE {qid} AS {compiled.text}"
+        stmt = seal(
+            CompiledSql(
+                statement_id=f"temp:{temp_name}:{compiled.statement_id}",
+                text=sql,
+                param_names=tuple(bound.keys()),
+                redacted_params={k: "<redacted>" for k in bound},
+                dialect=self.dialect,
+                logical_nodes=(context.step_name,),
+                metadata={"_bound_params": bound},
+            )
+        )
+        result = self.execute([stmt], params={}, context=context, fetch=False)
+        if result.outcome is TransactionOutcome.COMMITTED:
+            result.relation = RelationRef(name=temp_name)
+            if temp_name not in self._staging_tables:
+                self._staging_tables.append(temp_name)
+        else:
+            result.relation = None
+        result.metrics.fused_steps = 1
+        return result
+
+    def publish_replace(
+        self,
+        *,
+        target: RelationRef,
+        staging: RelationRef,
+        compiler: SqlCompiler,
+        context: SqlExecutionContext,
+    ) -> SqlExecutionResult:
+        """Swap staging into target without dropping the live table first."""
+        _ = context
+        target_sql = compiler.qid(target)
+        staging_sql = compiler.qid(staging)
+        old_name = f"{target.name}__old_{staging.name[-8:]}"
+        require_safe_identifier(old_name)
+        old = RelationRef(
+            name=old_name, namespace=target.namespace, catalog=target.catalog
+        )
+        old_sql = compiler.qid(old)
+        started = False
+        try:
+            with self.engine.begin() as conn:
+                started = True
+                # Detect existing target.
+                exists = False
+                if self.dialect == "postgresql":
+                    row = conn.execute(
+                        text(
+                            "SELECT 1 FROM information_schema.tables "
+                            "WHERE table_name = :name "
+                            "AND (:schema IS NULL OR table_schema = :schema)"
+                        ),
+                        {"name": target.name, "schema": target.namespace or "public"},
+                    ).first()
+                    exists = row is not None
+                else:
+                    row = conn.execute(
+                        text(
+                            "SELECT 1 FROM sqlite_master "
+                            "WHERE type='table' AND name = :name"
+                        ),
+                        {"name": target.name},
+                    ).first()
+                    exists = row is not None
+                conn.execute(text(f"DROP TABLE IF EXISTS {old_sql}"))
+                if exists:
+                    conn.execute(
+                        text(
+                            f"ALTER TABLE {target_sql} RENAME TO "
+                            f"{quote_identifier(old_name, dialect=self.dialect)}"
+                        )
+                    )
+                conn.execute(
+                    text(
+                        f"ALTER TABLE {staging_sql} RENAME TO "
+                        f"{quote_identifier(target.name, dialect=self.dialect)}"
+                    )
+                )
+                if exists:
+                    conn.execute(text(f"DROP TABLE IF EXISTS {old_sql}"))
+            return SqlExecutionResult(
+                outcome=TransactionOutcome.COMMITTED,
+                relation=target,
+                metrics=SqlMetrics(statements=1, phases=["publish"]),
+                backend_ref=f"sqlalchemy:{self.dialect}",
+            )
+        except Exception as exc:
+            return SqlExecutionResult(
+                outcome=_classify_failure(exc, started=started),
+                diagnostics=[
+                    {"code": "PMSQL520", "severity": "error", "message": str(exc)}
+                ],
+            )
+
+    def load_records(
+        self,
+        records: Sequence[Any],
+        *,
+        target: RelationRef,
+        context: SqlExecutionContext,
+        compiler: SqlCompiler,
+    ) -> SqlExecutionResult:
+        _ = context
+        rows = [
+            r.model_dump() if hasattr(r, "model_dump") else dict(r) for r in records
+        ]
+        if not rows:
+            return SqlExecutionResult(
+                outcome=TransactionOutcome.COMMITTED,
+                relation=target,
+                metrics=SqlMetrics(rows_affected=0, phases=["load"]),
+            )
+        cols = list(rows[0].keys())
+        for c in cols:
+            require_safe_identifier(c)
+        col_sql = ", ".join(compiler.quote(c) for c in cols)
+        placeholders = ", ".join(f":{c}" for c in cols)
+        target_sql = compiler.qid(target)
+        create_cols = ", ".join(f"{compiler.quote(c)} TEXT" for c in cols)
+        create = f"CREATE TABLE IF NOT EXISTS {target_sql} ({create_cols})"
+        insert = f"INSERT INTO {target_sql} ({col_sql}) VALUES ({placeholders})"
+        started = False
+        try:
+            with self.engine.begin() as conn:
+                started = True
+                conn.execute(text(create))
+                for row in rows:
+                    conn.execute(text(insert), row)
+            return SqlExecutionResult(
+                outcome=TransactionOutcome.COMMITTED,
+                relation=target,
+                metrics=SqlMetrics(
+                    rows_affected=len(rows),
+                    phases=["load"],
+                    statements=1 + len(rows),
+                ),
+                backend_ref=f"sqlalchemy:{self.dialect}",
+            )
+        except Exception as exc:
+            return SqlExecutionResult(
+                outcome=_classify_failure(exc, started=started),
+                diagnostics=[
+                    {"code": "PMSQL510", "severity": "error", "message": str(exc)}
+                ],
+            )
+
+    def fetch_records(
+        self,
+        compiler: SqlCompiler,
+        relation: RelationRef | SqlQuery,
+        *,
+        params: Mapping[str, Any],
+        context: SqlExecutionContext,
+        contract_type: type[Any] | None = None,
+        seal: Any = None,
+    ) -> SqlExecutionResult:
+        if isinstance(relation, SqlQuery):
+            compiled = compiler.compile_query(relation, context=context)
+            if seal is not None:
+                compiled = seal(compiled)
+        else:
+            compiled = CompiledSql(
+                statement_id=f"fetch:{relation.qualified_name}",
+                text=f"SELECT * FROM {compiler.qid(relation)}",
+                dialect=self.dialect,
+                logical_nodes=(context.step_name,),
+            )
+        result = self.execute([compiled], params=params, context=context, fetch=True)
+        if contract_type is not None and result.records:
+            result.records = [contract_type.model_validate(r) for r in result.records]
+        return result
+
+    def cleanup_staging(self) -> None:
+        if not self._staging_tables:
+            return
+        try:
+            with self.engine.begin() as conn:
+                for name in list(self._staging_tables):
+                    try:
+                        require_safe_identifier(name)
+                        qid = quote_identifier(name, dialect=self.dialect)
+                        conn.execute(text(f"DROP TABLE IF EXISTS {qid}"))
+                    except Exception:
+                        continue
+        finally:
+            self._staging_tables.clear()

pipelantic_sql-0.6.0/src/pipelantic_sql/plugin.py

@@ -0,0 +1,247 @@
+"""SQLAlchemy-backed PostgreSQL (reference) SQL plugin."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping, Sequence
+from dataclasses import replace
+from typing import Any
+
+from sqlalchemy import create_engine
+from sqlalchemy.engine import Engine
+
+from pipelantic.capabilities import PluginCapabilities
+from pipelantic.sql.helpers import require_safe_identifier
+from pipelantic.sql.protocol import (
+    SQL_PROTOCOL_VERSION,
+    CompiledSql,
+    RelationRef,
+    SqlExecutionContext,
+    SqlExecutionResult,
+    SqlPluginInfo,
+    SqlQuery,
+    SqlWrite,
+    TransactionOutcome,
+    WriteIntentKind,
+)
+from pipelantic_sql.catalog import inspect_relation as catalog_inspect
+from pipelantic_sql.compiler import SqlCompiler
+from pipelantic_sql.dialect_postgresql import detect_dialect, quote_identifier
+from pipelantic_sql.executor import SqlExecutor
+
+__version__ = "0.6.0"
+
+
+def create_plugin() -> PostgresSqlPlugin:
+    """Entry-point factory."""
+    return PostgresSqlPlugin()
+
+
+class PostgresSqlPlugin:
+    """Reference SQL plugin (PostgreSQL-shaped; SQLAlchemy Core)."""
+
+    def __init__(self, *, url: str | None = None) -> None:
+        self._url = url or os.environ.get(
+            "PIPELANTIC_SQL_URL", "sqlite+pysqlite:///:memory:"
+        )
+        self._engine: Engine | None = None
+        self._rows_fetched = [0]
+        self._bound_params: dict[str, dict[str, Any]] = {}
+        self._staging_tables: list[str] = []
+        dialect = detect_dialect(self._url)
+        extras = (
+            frozenset({"postgresql", "sqlalchemy"})
+            if dialect == "postgresql"
+            else frozenset({"sqlite", "sqlalchemy"})
+        )
+        # MERGE is not implemented in 0.6 — never advertise it.
+        caps = PluginCapabilities(
+            engine="sql",
+            async_execution=False,
+            dataframe=False,
+            sql=True,
+            transactions=True,
+            cancellation=False,
+            schema_inspection=True,
+            sql_merge=False,
+            sql_cte=True,
+            sql_returning=dialect == "postgresql",
+            sql_transactional_ddl=dialect == "postgresql",
+            sql_atomic_rename=True,
+            sql_catalog_inspect=True,
+            sql_trusted_fragments=False,
+            eager=False,
+            lazy=False,
+            extras=extras,
+        )
+        self._info = SqlPluginInfo(
+            name="pipelantic-sql",
+            engine="sql",
+            dialect=dialect,
+            version=__version__,
+            protocol_version=SQL_PROTOCOL_VERSION,
+            capabilities=caps,
+        )
+        self._compiler = SqlCompiler(dialect=dialect, supports_merge=False)
+
+    @property
+    def info(self) -> SqlPluginInfo:
+        return self._info
+
+    def capabilities(self) -> PluginCapabilities:
+        assert self._info.capabilities is not None
+        return self._info.capabilities
+
+    def rows_fetched_total(self) -> int:
+        return self._rows_fetched[0]
+
+    def _get_engine(self) -> Engine:
+        if self._engine is None:
+            self._engine = create_engine(self._url, future=True)
+        return self._engine
+
+    def _executor(self) -> SqlExecutor:
+        return SqlExecutor(
+            engine=self._get_engine(),
+            dialect=self.info.dialect,
+            rows_fetched_counter=self._rows_fetched,
+            bound_params=self._bound_params,
+            staging_tables=self._staging_tables,
+        )
+
+    def _seal(self, compiled: CompiledSql) -> CompiledSql:
+        """Move live bound values into a private map; strip from public metadata."""
+        meta = dict(compiled.metadata)
+        bound = dict(meta.pop("_bound_params", {}) or {})
+        if bound:
+            self._bound_params[compiled.statement_id] = bound
+        return replace(compiled, metadata=meta)
+
+    def quote_identifier(self, name: str) -> str:
+        return quote_identifier(name, dialect=self.info.dialect)
+
+    def relation_from_binding(
+        self,
+        *,
+        binding: str,
+        location: str | None,
+        metadata: Mapping[str, Any] | None = None,
+    ) -> RelationRef:
+        _ = metadata
+        if location:
+            rel = RelationRef.parse(location)
+            for part in (rel.catalog, rel.namespace, rel.name):
+                if part is not None:
+                    require_safe_identifier(part)
+            return rel
+        return RelationRef(name=require_safe_identifier(binding))
+
+    def compile_query(
+        self,
+        query: SqlQuery,
+        *,
+        context: SqlExecutionContext,
+    ) -> CompiledSql:
+        return self._seal(self._compiler.compile_query(query, context=context))
+
+    def compile_write(
+        self,
+        write: SqlWrite,
+        *,
+        context: SqlExecutionContext,
+    ) -> CompiledSql:
+        return self._seal(self._compiler.compile_write(write, context=context))
+
+    def execute(
+        self,
+        compiled: Sequence[CompiledSql],
+        *,
+        params: Mapping[str, Any],
+        context: SqlExecutionContext,
+        fetch: bool = False,
+    ) -> SqlExecutionResult:
+        return self._executor().execute(
+            compiled, params=params, context=context, fetch=fetch
+        )
+
+    def execute_write(
+        self,
+        write: SqlWrite,
+        *,
+        params: Mapping[str, Any],
+        context: SqlExecutionContext,
+    ) -> SqlExecutionResult:
+        compiled = self.compile_write(write, context=context)
+        result = self.execute([compiled], params=params, context=context, fetch=False)
+        if result.outcome is not TransactionOutcome.COMMITTED:
+            return result
+        if write.intent in {WriteIntentKind.REPLACE, WriteIntentKind.SNAPSHOT}:
+            staging_data = compiled.metadata.get("staging") or {}
+            staging = RelationRef.from_dict(dict(staging_data))
+            swap = self._executor().publish_replace(
+                target=write.target,
+                staging=staging,
+                compiler=self._compiler,
+                context=context,
+            )
+            swap.compiled = list(result.compiled) + list(swap.compiled)
+            return swap
+        return result
+
+    def materialize_temp(
+        self,
+        query: SqlQuery,
+        *,
+        temp_name: str,
+        params: Mapping[str, Any],
+        context: SqlExecutionContext,
+    ) -> SqlExecutionResult:
+        return self._executor().materialize_temp(
+            self._compiler,
+            query,
+            temp_name=temp_name,
+            params=params,
+            context=context,
+            seal=self._seal,
+        )
+
+    def load_records(
+        self,
+        records: Sequence[Any],
+        *,
+        target: RelationRef,
+        context: SqlExecutionContext,
+    ) -> SqlExecutionResult:
+        return self._executor().load_records(
+            records, target=target, context=context, compiler=self._compiler
+        )
+
+    def fetch_records(
+        self,
+        relation: RelationRef | SqlQuery,
+        *,
+        params: Mapping[str, Any],
+        context: SqlExecutionContext,
+        contract_type: type[Any] | None = None,
+    ) -> SqlExecutionResult:
+        return self._executor().fetch_records(
+            self._compiler,
+            relation,
+            params=params,
+            context=context,
+            contract_type=contract_type,
+            seal=self._seal,
+        )
+
+    def inspect_relation(
+        self,
+        relation: RelationRef,
+        *,
+        context: SqlExecutionContext,
+    ) -> dict[str, Any]:
+        _ = context
+        return catalog_inspect(self._get_engine(), relation, dialect=self.info.dialect)
+
+    def cleanup_staging(self) -> None:
+        """Drop run-scoped durable staging tables."""
+        self._executor().cleanup_staging()

pipelantic_sql-0.6.0/src/pipelantic_sql/writes.py

@@ -0,0 +1,19 @@
+"""Write-intent helpers for the reference SQL plugin."""
+
+from __future__ import annotations
+
+from pipelantic.sql.protocol import WriteIntentKind
+
+SUPPORTED_WRITE_INTENTS = frozenset(
+    {
+        WriteIntentKind.APPEND,
+        WriteIntentKind.INSERT_SELECT,
+        WriteIntentKind.REPLACE,
+        WriteIntentKind.SNAPSHOT,
+        WriteIntentKind.MERGE,
+    }
+)
+
+
+def requires_atomic_publication(intent: WriteIntentKind) -> bool:
+    return intent in {WriteIntentKind.REPLACE, WriteIntentKind.SNAPSHOT}