rivetsql-postgres 0.1.0__tar.gz

rivetsql_postgres-0.1.0/.gitignore

@@ -0,0 +1,25 @@
+.DS_Store
+.env
+.env.*
+*.pem
+*.key
+secrets/
+target/
+build/
+dist/
+out/
+.next/
+node_modules/
+__pycache__/
+*.pyc
+.pytest_cache/
+.hypothesis/
+.cargo/
+*.class
+bin/
+obj/
+.ralph-logs/
+mcp.json
+docs/reference/
+docs/_build/
+*.zip

rivetsql_postgres-0.1.0/PKG-INFO

@@ -0,0 +1,18 @@
+Metadata-Version: 2.4
+Name: rivetsql-postgres
+Version: 0.1.0
+Summary: PostgreSQL plugin for Rivet SQL
+Project-URL: Homepage, https://github.com/rivetsql/rivet
+Project-URL: Repository, https://github.com/rivetsql/rivet
+Author: Rivet Contributors
+License-Expression: MIT
+Keywords: data-pipeline,postgres,rivet,sql
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Database
+Requires-Python: >=3.11
+Requires-Dist: psycopg[binary,pool]>=3.1
+Requires-Dist: rivetsql-core>=0.1.0

rivetsql_postgres-0.1.0/__init__.py

@@ -0,0 +1,42 @@
+"""rivet_postgres — PostgreSQL plugin for Rivet."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from rivet_core.plugins import PluginRegistry
+
+
+def PostgresPlugin(registry: PluginRegistry) -> None:
+    """Register all rivet_postgres components into the plugin registry.
+
+    Core components (catalog, engine, source, sink, cross-joint) are always
+    registered. Cross-catalog adapters are registered best-effort since they
+    depend on optional packages.
+    """
+    from rivet_postgres.catalog import PostgresCatalogPlugin
+    from rivet_postgres.cross_joint import PostgresCrossJointAdapter
+    from rivet_postgres.engine import PostgresComputeEnginePlugin
+    from rivet_postgres.sink import PostgresSink
+    from rivet_postgres.source import PostgresSource
+
+    registry.register_catalog_plugin(PostgresCatalogPlugin())
+    registry.register_engine_plugin(PostgresComputeEnginePlugin())
+    registry.register_source(PostgresSource())
+    registry.register_sink(PostgresSink())
+    registry.register_cross_joint_adapter(PostgresCrossJointAdapter())
+
+    # Adapters depend on optional packages — register best-effort
+    try:
+        from rivet_postgres.adapters.duckdb import PostgresDuckDBAdapter
+
+        registry.register_adapter(PostgresDuckDBAdapter())
+    except ImportError:
+        pass
+    try:
+        from rivet_postgres.adapters.pyspark import PostgresPySparkAdapter
+
+        registry.register_adapter(PostgresPySparkAdapter())
+    except ImportError:
+        pass

rivetsql_postgres-0.1.0/adapters/__init__.py

@@ -0,0 +1 @@
+"""PostgreSQL engine adapters for external compute engines."""

rivetsql_postgres-0.1.0/adapters/duckdb.py

@@ -0,0 +1,279 @@
+"""PostgresDuckDBAdapter: catalog-plugin-contributed adapter for DuckDB ← postgres.
+
+Registers with target_engine="duckdb", catalog_type="postgres", source_plugin="rivet_postgres".
+This adapter takes priority over any engine-plugin adapter for the same pair per Core adapter
+precedence (catalog_plugin > engine_plugin).
+
+Uses DuckDB's postgres community extension with ATTACH to establish direct
+PostgreSQL access from DuckDB queries.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import pyarrow
+
+from rivet_core.errors import ExecutionError, RivetError, plugin_error
+from rivet_core.models import Column, Material, Schema
+from rivet_core.optimizer import AdapterPushdownResult, Cast, PushdownPlan, ResidualPlan
+from rivet_core.plugins import ComputeEngineAdapter
+from rivet_core.strategies import MaterializedRef
+
+if TYPE_CHECKING:
+    import duckdb
+
+    from rivet_core.sql_parser import Predicate
+
+_EMPTY_RESIDUAL = ResidualPlan(predicates=[], limit=None, casts=[])
+
+
+def _apply_pushdown(
+    base_sql: str,
+    pushdown: PushdownPlan | None,
+) -> tuple[str, ResidualPlan]:
+    """Apply pushdown operations to a SQL query string (DuckDB dialect)."""
+    if pushdown is None:
+        return base_sql, _EMPTY_RESIDUAL
+
+    sql = base_sql
+    residual_predicates: list[Predicate] = list(pushdown.predicates.residual)
+    residual_casts: list[Cast] = list(pushdown.casts.residual)
+    residual_limit: int | None = pushdown.limit.residual_limit
+
+    if pushdown.projections.pushed_columns is not None:
+        try:
+            cols = ", ".join(pushdown.projections.pushed_columns)
+            sql = sql.replace("SELECT *", f"SELECT {cols}", 1)
+        except Exception:
+            pass
+
+    if pushdown.predicates.pushed:
+        where_parts: list[str] = []
+        for pred in pushdown.predicates.pushed:
+            try:
+                where_parts.append(pred.expression)
+            except Exception:
+                residual_predicates.append(pred)
+        if where_parts:
+            where_clause = " AND ".join(where_parts)
+            sql = f"SELECT * FROM ({sql}) AS __pd WHERE {where_clause}"
+
+    if pushdown.limit.pushed_limit is not None:
+        try:
+            sql = f"{sql} LIMIT {pushdown.limit.pushed_limit}"
+        except Exception:
+            residual_limit = pushdown.limit.pushed_limit
+
+    for cast in pushdown.casts.pushed:
+        try:
+            sql = sql.replace(cast.column, f"CAST({cast.column} AS {cast.to_type})")
+        except Exception:
+            residual_casts.append(cast)
+
+    return sql, ResidualPlan(predicates=residual_predicates, limit=residual_limit, casts=residual_casts)
+
+
+def _ensure_duckdb_extension(conn: duckdb.DuckDBPyConnection, ext: str, install_from: str | None = None) -> None:
+    """Check-then-load a DuckDB extension."""
+    try:
+        row = conn.execute(
+            "SELECT installed, loaded FROM duckdb_extensions() WHERE extension_name = ?",
+            [ext],
+        ).fetchone()
+        installed = row[0] if row is not None else False
+        loaded = row[1] if row is not None else False
+        if loaded:
+            return
+        if not installed:
+            install_sql = f"INSTALL {ext} FROM {install_from}" if install_from else f"INSTALL {ext}"
+            conn.execute(install_sql)
+        conn.execute(f"LOAD {ext}")
+    except ExecutionError:
+        raise
+    except Exception as exc:
+        raise ExecutionError(
+            plugin_error(
+                "RVT-502",
+                f"Failed to load DuckDB extension '{ext}': {exc}",
+                plugin_name="rivet_postgres",
+                plugin_type="adapter",
+                remediation=(
+                    f"Run: INSTALL {ext}; LOAD {ext}; "
+                    "or set the DuckDB extension directory for offline environments."
+                ),
+                extension=ext,
+            )
+        ) from exc
+
+
+def _build_dsn(catalog_options: dict[str, Any]) -> str:
+    """Build a PostgreSQL connection string from catalog options."""
+    host = catalog_options["host"]
+    port = catalog_options.get("port", 5432)
+    database = catalog_options["database"]
+    user = catalog_options.get("user", "")
+    password = catalog_options.get("password", "")
+    parts = [f"host={host}", f"port={port}", f"dbname={database}"]
+    if user:
+        parts.append(f"user={user}")
+    if password:
+        parts.append(f"password={password}")
+    return " ".join(parts)
+
+
+def _attach_alias(catalog_name: str) -> str:
+    """Derive a DuckDB ATTACH alias from the catalog name."""
+    return f"pg_{catalog_name}"
+
+
+class _PostgresDuckDBMaterializedRef(MaterializedRef):
+    """Deferred ref that reads PostgreSQL data via DuckDB postgres extension on to_arrow()."""
+
+    def __init__(self, catalog_options: dict[str, Any], catalog_name: str, sql: str | None, table: str | None) -> None:
+        self._catalog_options = catalog_options
+        self._catalog_name = catalog_name
+        self._sql = sql
+        self._table = table
+        self._cached: pyarrow.Table | None = None
+
+    def _execute(self) -> pyarrow.Table:
+        if self._cached is not None:
+            return self._cached
+        import duckdb
+
+        conn = duckdb.connect(":memory:")
+        try:
+            _ensure_duckdb_extension(conn, "postgres", install_from="community")
+            dsn = _build_dsn(self._catalog_options)
+            alias = _attach_alias(self._catalog_name)
+            conn.execute(f"ATTACH '{dsn}' AS {alias} (TYPE postgres, READ_ONLY)")
+
+            if self._sql:
+                result = conn.execute(self._sql).arrow()
+            else:
+                pg_schema = self._catalog_options.get("schema", "public")
+                table_ref = f"{alias}.{pg_schema}.{self._table}"
+                result = conn.execute(f"SELECT * FROM {table_ref}").arrow()
+
+            self._cached = result
+            return result
+        except ExecutionError:
+            raise
+        except Exception as exc:
+            raise ExecutionError(
+                RivetError(
+                    code="RVT-504",
+                    message=f"DuckDB postgres extension failed: {exc}",
+                    context={"host": self._catalog_options.get("host"), "database": self._catalog_options.get("database")},
+                    remediation="Check PostgreSQL connectivity, credentials, and that the DuckDB postgres extension is available.",
+                )
+            ) from exc
+        finally:
+            conn.close()
+
+    def to_arrow(self) -> pyarrow.Table:
+        return self._execute()
+
+    @property
+    def schema(self) -> Schema:
+        table = self._execute()
+        return Schema(columns=[Column(name=f.name, type=str(f.type), nullable=f.nullable) for f in table.schema])
+
+    @property
+    def row_count(self) -> int:
+        return self._execute().num_rows  # type: ignore[no-any-return]
+
+    @property
+    def size_bytes(self) -> int | None:
+        return None
+
+    @property
+    def storage_type(self) -> str:
+        return "postgres"
+
+
+class PostgresDuckDBAdapter(ComputeEngineAdapter):
+    """DuckDB adapter for PostgreSQL catalog type, shipped by rivet_postgres.
+
+    Uses DuckDB's postgres community extension with ATTACH for direct
+    PostgreSQL access from DuckDB queries.
+    """
+
+    target_engine_type = "duckdb"
+    catalog_type = "postgres"
+    capabilities: list[str] = [
+        "projection_pushdown",
+        "predicate_pushdown",
+        "limit_pushdown",
+        "cast_pushdown",
+        "join",
+        "aggregation",
+    ]
+    source = "catalog_plugin"
+    source_plugin = "rivet_postgres"
+
+    def read_dispatch(self, engine: Any, catalog: Any, joint: Any, pushdown: PushdownPlan | None = None) -> AdapterPushdownResult:
+        if joint.sql:
+            base_sql = joint.sql
+        else:
+            pg_schema = catalog.options.get("schema", "public")
+            alias = _attach_alias(catalog.name)
+            base_sql = f"SELECT * FROM {alias}.{pg_schema}.{joint.table}"
+
+        sql, residual = _apply_pushdown(base_sql, pushdown)
+
+        material = Material(
+            name=joint.name,
+            catalog=catalog.name,
+            materialized_ref=_PostgresDuckDBMaterializedRef(
+                catalog_options=catalog.options,
+                catalog_name=catalog.name,
+                sql=sql,
+                table=joint.table,
+            ),
+            state="deferred",
+        )
+        return AdapterPushdownResult(material=material, residual=residual)
+
+    def write_dispatch(self, engine: Any, catalog: Any, joint: Any, material: Any) -> Any:
+        import duckdb
+
+        conn = duckdb.connect(":memory:")
+        try:
+            _ensure_duckdb_extension(conn, "postgres", install_from="community")
+            dsn = _build_dsn(catalog.options)
+            alias = _attach_alias(catalog.name)
+            conn.execute(f"ATTACH '{dsn}' AS {alias} (TYPE postgres)")
+
+            arrow_table = material.to_arrow()
+            conn.register("__write_data", arrow_table)
+
+            pg_schema = catalog.options.get("schema", "public")
+            table_name = joint.table
+            table_ref = f"{alias}.{pg_schema}.{table_name}"
+            strategy = joint.write_strategy or "replace"
+
+            if strategy == "replace":
+                conn.execute(f"DROP TABLE IF EXISTS {table_ref}")
+                conn.execute(f"CREATE TABLE {table_ref} AS SELECT * FROM __write_data")
+            elif strategy == "append":
+                conn.execute(f"INSERT INTO {table_ref} SELECT * FROM __write_data")
+            elif strategy == "truncate_insert":
+                conn.execute(f"DELETE FROM {table_ref}")
+                conn.execute(f"INSERT INTO {table_ref} SELECT * FROM __write_data")
+            else:
+                conn.execute(f"INSERT INTO {table_ref} SELECT * FROM __write_data")
+        except ExecutionError:
+            raise
+        except Exception as exc:
+            raise ExecutionError(
+                RivetError(
+                    code="RVT-504",
+                    message=f"DuckDB postgres extension write failed: {exc}",
+                    context={"host": catalog.options.get("host"), "database": catalog.options.get("database")},
+                    remediation="Check PostgreSQL connectivity, credentials, and write permissions.",
+                )
+            ) from exc
+        finally:
+            conn.close()

rivetsql_postgres-0.1.0/adapters/pyspark.py

@@ -0,0 +1,305 @@
+"""PostgresPySparkAdapter: JDBC read/write for PostgreSQL catalogs via PySpark.
+
+Simple writes (append, replace) use Spark JDBC. Complex writes (truncate_insert,
+merge, delete_insert, incremental_append, scd2) use a psycopg3 side-channel that
+materializes to Arrow and writes directly to PostgreSQL.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import TYPE_CHECKING, Any
+
+import pyarrow
+
+from rivet_core.errors import ExecutionError, RivetError
+from rivet_core.models import Column, Material, Schema
+from rivet_core.optimizer import AdapterPushdownResult, Cast, PushdownPlan, ResidualPlan
+from rivet_core.plugins import ComputeEngineAdapter
+from rivet_core.strategies import MaterializedRef
+
+if TYPE_CHECKING:
+    from rivet_core.sql_parser import Predicate
+
+ALL_6_CAPABILITIES = [
+    "projection_pushdown",
+    "predicate_pushdown",
+    "limit_pushdown",
+    "cast_pushdown",
+    "join",
+    "aggregation",
+]
+
+_JDBC_DRIVER = "org.postgresql.Driver"
+_JDBC_MAVEN = "org.postgresql:postgresql:42.7.3"
+_SIDE_CHANNEL_STRATEGIES = frozenset({"truncate_insert", "merge", "delete_insert", "incremental_append", "scd2"})
+
+_EMPTY_RESIDUAL = ResidualPlan(predicates=[], limit=None, casts=[])
+
+
+def _apply_pyspark_pushdown(
+    df: Any,
+    pushdown: PushdownPlan | None,
+) -> tuple[Any, ResidualPlan]:
+    """Apply pushdown operations to a PySpark DataFrame.
+
+    Returns (modified_df, residual) where residual contains any operations
+    that could not be applied.
+    """
+    if pushdown is None:
+        return df, _EMPTY_RESIDUAL
+
+    residual_predicates: list[Predicate] = list(pushdown.predicates.residual)
+    residual_casts: list[Cast] = list(pushdown.casts.residual)
+    residual_limit: int | None = pushdown.limit.residual_limit
+
+    if pushdown.projections.pushed_columns is not None:
+        try:
+            df = df.select(*pushdown.projections.pushed_columns)
+        except Exception:
+            pass
+
+    for pred in pushdown.predicates.pushed:
+        try:
+            df = df.filter(pred.expression)
+        except Exception:
+            residual_predicates.append(pred)
+
+    if pushdown.limit.pushed_limit is not None:
+        try:
+            df = df.limit(pushdown.limit.pushed_limit)
+        except Exception:
+            residual_limit = pushdown.limit.pushed_limit
+
+    if pushdown.casts.pushed:
+        from pyspark.sql import functions as F
+
+        for cast in pushdown.casts.pushed:
+            try:
+                df = df.withColumn(cast.column, F.col(cast.column).cast(cast.to_type))
+            except Exception:
+                residual_casts.append(cast)
+
+    return df, ResidualPlan(
+        predicates=residual_predicates,
+        limit=residual_limit,
+        casts=residual_casts,
+    )
+
+
+class _SparkDataFrameMaterializedRef(MaterializedRef):
+    """MaterializedRef backed by a Spark DataFrame. Materializes to Arrow on to_arrow()."""
+
+    def __init__(self, df: Any) -> None:
+        self._df = df
+
+    def to_arrow(self) -> pyarrow.Table:
+        if hasattr(self._df, "toArrow"):
+            result = self._df.toArrow()
+            if isinstance(result, pyarrow.RecordBatchReader):
+                return result.read_all()
+            return result
+        return pyarrow.Table.from_pandas(self._df.toPandas())
+
+    @property
+    def schema(self) -> Schema:
+        return Schema(
+            columns=[
+                Column(name=field.name, type=str(field.dataType), nullable=field.nullable)
+                for field in self._df.schema.fields
+            ]
+        )
+
+    @property
+    def row_count(self) -> int:
+        return self._df.count()  # type: ignore[no-any-return]
+
+    @property
+    def size_bytes(self) -> int | None:
+        return None
+
+    @property
+    def storage_type(self) -> str:
+        return "spark_dataframe"
+
+
+def _check_jdbc_driver(session: Any) -> None:
+    """Fail with RVT-505 if the PostgreSQL JDBC driver JAR is missing."""
+    try:
+        session._jvm.java.lang.Class.forName(_JDBC_DRIVER)
+    except Exception:
+        raise ExecutionError(  # noqa: B904
+            RivetError(
+                code="RVT-505",
+                message="PostgreSQL JDBC driver JAR not found on Spark classpath.",
+                context={"driver": _JDBC_DRIVER, "adapter": "PostgresPySparkAdapter"},
+                remediation=(
+                    f"Add the PostgreSQL JDBC driver to Spark via "
+                    f"'spark.jars.packages' option: '{_JDBC_MAVEN}'."
+                ),
+            )
+        )
+
+
+def _build_jdbc_url(options: dict[str, Any]) -> str:
+    """Build a JDBC URL from postgres catalog options."""
+    host = options["host"]
+    port = options.get("port", 5432)
+    database = options["database"]
+    ssl_mode = options.get("ssl_mode", "prefer")
+    return f"jdbc:postgresql://{host}:{port}/{database}?sslmode={ssl_mode}"
+
+
+def _build_jdbc_properties(options: dict[str, Any]) -> dict[str, str]:
+    """Build JDBC connection properties from catalog options."""
+    props: dict[str, str] = {"driver": _JDBC_DRIVER}
+    if options.get("user"):
+        props["user"] = options["user"]
+    if options.get("password"):
+        props["password"] = options["password"]
+    return props
+
+
+class PostgresPySparkAdapter(ComputeEngineAdapter):
+    """Adapter enabling PySpark engine to read/write PostgreSQL catalogs via JDBC.
+
+    Registered as catalog_plugin-contributed so it takes precedence over any
+    engine_plugin adapter for the same (pyspark, postgres) pair.
+    """
+
+    target_engine_type = "pyspark"
+    catalog_type = "postgres"
+    capabilities = ALL_6_CAPABILITIES
+    source = "catalog_plugin"
+    source_plugin = "rivet_postgres"
+
+    def read_dispatch(self, engine: Any, catalog: Any, joint: Any, pushdown: PushdownPlan | None = None) -> AdapterPushdownResult:
+        """Read from PostgreSQL via Spark JDBC with optional parallel partitioned reads."""
+        session = engine.get_session()
+        _check_jdbc_driver(session)
+
+        url = _build_jdbc_url(catalog.options)
+        props = _build_jdbc_properties(catalog.options)
+
+        # Determine what to read: wrap SQL as subquery or use table reference
+        sql = getattr(joint, "sql", None)
+        table = getattr(joint, "table", None)
+        if sql:
+            dbtable = f"({sql}) AS _rivet_subquery"
+        elif table:
+            schema = catalog.options.get("schema", "public")
+            dbtable = f"{schema}.{table}"
+        else:
+            schema = catalog.options.get("schema", "public")
+            dbtable = f"{schema}.{joint.name}"
+
+        # Check for parallel partitioned read options on the joint
+        partition_column = getattr(joint, "jdbc_partition_column", None)
+        lower_bound = getattr(joint, "jdbc_lower_bound", None)
+        upper_bound = getattr(joint, "jdbc_upper_bound", None)
+        num_partitions = getattr(joint, "jdbc_num_partitions", None)
+
+        try:
+            if partition_column and num_partitions:
+                df = (
+                    session.read.jdbc(
+                        url=url,
+                        table=dbtable,
+                        column=partition_column,
+                        lowerBound=int(lower_bound) if lower_bound is not None else 0,
+                        upperBound=int(upper_bound) if upper_bound is not None else 1000000,
+                        numPartitions=int(num_partitions),
+                        properties=props,
+                    )
+                )
+            else:
+                df = session.read.jdbc(url=url, table=dbtable, properties=props)
+        except Exception as exc:
+            raise ExecutionError(
+                RivetError(
+                    code="RVT-501",
+                    message=f"PostgreSQL JDBC read failed: {exc}",
+                    context={"host": catalog.options.get("host"), "database": catalog.options.get("database")},
+                    remediation="Check PostgreSQL credentials, host, and network connectivity.",
+                )
+            ) from exc
+
+        df, residual = _apply_pyspark_pushdown(df, pushdown)
+
+        ref = _SparkDataFrameMaterializedRef(df)
+        material = Material(
+            name=joint.name,
+            catalog=catalog.name,
+            materialized_ref=ref,
+            state="deferred",
+        )
+        return AdapterPushdownResult(material=material, residual=residual)
+
+    def write_dispatch(self, engine: Any, catalog: Any, joint: Any, material: Any) -> Any:
+        """Write to PostgreSQL via Spark JDBC (append, replace) or psycopg3 side-channel (complex)."""
+        strategy = getattr(joint, "write_strategy", None) or "replace"
+
+        if strategy in _SIDE_CHANNEL_STRATEGIES:
+            return _psycopg3_side_channel(catalog, joint, material, strategy)
+
+        session = engine.get_session()
+        _check_jdbc_driver(session)
+
+        url = _build_jdbc_url(catalog.options)
+        props = _build_jdbc_properties(catalog.options)
+
+        # Resolve target table name
+        table = getattr(joint, "table", None) or joint.name
+        schema = catalog.options.get("schema", "public")
+        dbtable = f"{schema}.{table}"
+
+        # Map strategy to Spark JDBC write mode
+        mode = "append" if strategy == "append" else "overwrite"
+
+        # Materialize to Spark DataFrame
+        arrow_table = material.materialized_ref.to_arrow()
+        df = session.createDataFrame(arrow_table.to_pandas())
+
+        try:
+            df.write.jdbc(url=url, table=dbtable, mode=mode, properties=props)
+        except Exception as exc:
+            raise ExecutionError(
+                RivetError(
+                    code="RVT-501",
+                    message=f"PostgreSQL JDBC write failed: {exc}",
+                    context={"host": catalog.options.get("host"), "database": catalog.options.get("database")},
+                    remediation="Check PostgreSQL credentials, host, and write permissions.",
+                )
+            ) from exc
+
+
+# --- psycopg3 side-channel for complex write strategies ---
+
+
+def _psycopg3_side_channel(catalog: Any, joint: Any, material: Any, strategy: str) -> None:
+    """Execute complex write strategies via psycopg3 directly, bypassing Spark JDBC."""
+    from rivet_postgres.sink import _build_conninfo, _execute_strategy
+
+    arrow_table = material.materialized_ref.to_arrow()
+    conninfo = _build_conninfo(catalog.options)
+    table = getattr(joint, "table", None) or joint.name
+    schema = catalog.options.get("schema", "public")
+    qualified_table = f"{schema}.{table}"
+
+    try:
+        asyncio.run(_execute_strategy(conninfo, qualified_table, arrow_table, strategy, joint))
+    except ExecutionError:
+        raise
+    except Exception as exc:
+        raise ExecutionError(
+            RivetError(
+                code="RVT-501",
+                message=f"PostgreSQL psycopg3 side-channel write failed: {exc}",
+                context={
+                    "host": catalog.options.get("host"),
+                    "database": catalog.options.get("database"),
+                    "strategy": strategy,
+                },
+                remediation="Check PostgreSQL credentials, host, and write permissions.",
+            )
+        ) from exc