plain.postgres 0.108.0__tar.gz → 0.108.1__tar.gz

{plain_postgres-0.108.0 → plain_postgres-0.108.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.108.0
+Version: 0.108.1
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause

{plain_postgres-0.108.0 → plain_postgres-0.108.1}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,16 @@
 # plain-postgres changelog
 
+## [0.108.1](https://github.com/dropseed/plain/releases/plain-postgres@0.108.1) (2026-06-09)
+
+### What's changed
+
+- `ensure_connection()` now detects a pooled connection the server has closed while it was held (Postgres restart, failover, idle timeout) and discards it before establishing a fresh one — logging a "Discarding dead database connection" warning — instead of repeatedly failing on the dead connection. Inside an atomic block the dead connection is intentionally left in place so the transaction's normal error handling runs, rather than silently continuing the rest of the block outside its transaction. ([9e82cb4454](https://github.com/dropseed/plain/commit/9e82cb4454))
+- Query span instrumentation no longer pays for expensive attributes when the span is sampled out: the per-query Python stack walk (for `code.*` attributes) and the `DEBUG`-mode stringification of query parameters now only happen when the span is actually recording. The cheap connection attributes are still passed at span creation so attribute-aware samplers can see them in `should_sample()`. ([af736043b0](https://github.com/dropseed/plain/commit/af736043b0))
+
+### Upgrade instructions
+
+- No changes required.
+
 ## [0.108.0](https://github.com/dropseed/plain/releases/plain-postgres@0.108.0) (2026-06-09)
 
 ### What's changed

{plain_postgres-0.108.0 → plain_postgres-0.108.1}/plain/postgres/connection.py

@@ -170,7 +170,19 @@ class DatabaseConnection:
         self.set_autocommit(True)
 
     def ensure_connection(self) -> None:
-        """Guarantee that a connection to the database is established."""
+        """Guarantee that a live connection to the database is established."""
+        if (
+            self.connection is not None
+            and self.connection.closed
+            and not self.in_atomic_block
+        ):
+            # The server closed this connection while we held it (restart,
+            # failover, idle timeout) — psycopg marks it closed once an
+            # operation fails on it. Mid-atomic, swapping it would silently
+            # run the rest of the block outside its transaction — leave the
+            # dead connection for Atomic.__exit__'s error recovery instead.
+            logger.warning("Discarding dead database connection")
+            self.close()
         if self.connection is None:
             self.connect()
 

{plain_postgres-0.108.0 → plain_postgres-0.108.1}/plain/postgres/otel.py

@@ -305,7 +305,10 @@ def db_span(
     # Single settings_dict read — the property delegates to source.config.
     cfg = db.settings_dict
 
-    # Build attribute set following semantic conventions
+    # Cheap attributes are passed at span creation so attribute-aware
+    # samplers can see them in should_sample(). Expensive ones (the
+    # per-query stack walk, DEBUG params) are added after, only when the
+    # span actually records.
     attrs: dict[str, Any] = {
         DB_SYSTEM_NAME: DB_SYSTEM,
         DB_NAMESPACE: cfg.get("DATABASE"),
@@ -314,8 +317,6 @@ def db_span(
         DB_OPERATION_NAME: operation,
     }
 
-    attrs.update(_get_code_attributes())
-
     # Add collection name if detected
     if collection_name:
         attrs[DB_COLLECTION_NAME] = collection_name
@@ -335,31 +336,41 @@ def db_span(
             attrs[SERVER_PORT] = port_int
             attrs[NETWORK_PEER_PORT] = port_int
 
-    # Add query parameters as attributes when DEBUG is True
-    if settings.DEBUG and params is not None:
-        # Convert params to appropriate format based on type
-        if isinstance(params, dict):
-            # Dictionary params (e.g., for named placeholders)
-            for key, value in params.items():
-                attrs[f"{DB_QUERY_PARAMETER_TEMPLATE}.{key}"] = str(value)
-        elif isinstance(params, list | tuple):
-            # Sequential params (e.g., for %s or ? placeholders)
-            for i, value in enumerate(params):
-                attrs[f"{DB_QUERY_PARAMETER_TEMPLATE}.{i + 1}"] = str(value)
-        else:
-            # Single param (rare but possible)
-            attrs[f"{DB_QUERY_PARAMETER_TEMPLATE}.1"] = str(params)
-
     with tracer.start_as_current_span(
         span_name, kind=SpanKind.CLIENT, attributes=attrs
     ) as span:
+        if span.is_recording():
+            expensive_attrs = _get_code_attributes()
+
+            # Add query parameters as attributes when DEBUG is True
+            if settings.DEBUG and params is not None:
+                # Convert params to appropriate format based on type
+                if isinstance(params, dict):
+                    # Dictionary params (e.g., for named placeholders)
+                    for key, value in params.items():
+                        expensive_attrs[f"{DB_QUERY_PARAMETER_TEMPLATE}.{key}"] = str(
+                            value
+                        )
+                elif isinstance(params, list | tuple):
+                    # Sequential params (e.g., for %s or ? placeholders)
+                    for i, value in enumerate(params):
+                        expensive_attrs[f"{DB_QUERY_PARAMETER_TEMPLATE}.{i + 1}"] = str(
+                            value
+                        )
+                else:
+                    # Single param (rare but possible)
+                    expensive_attrs[f"{DB_QUERY_PARAMETER_TEMPLATE}.1"] = str(params)
+
+            span.set_attributes(expensive_attrs)
+
         start = time.perf_counter()
         try:
             yield span
         except Exception as exc:
             # record_exception + set_status(ERROR) handled by
             # start_as_current_span when the exception propagates out.
-            span.set_attribute(ERROR_TYPE, format_exception_type(exc))
+            if span.is_recording():
+                span.set_attribute(ERROR_TYPE, format_exception_type(exc))
             raise
         duration_s = time.perf_counter() - start
 

{plain_postgres-0.108.0 → plain_postgres-0.108.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "plain.postgres"
-version = "0.108.0"
+version = "0.108.1"
 description = "Model your data and store it in a database."
 authors = [{ name = "Dave Gaeddert", email = "dave.gaeddert@dropseed.dev" }]
 readme = "README.md"

plain_postgres-0.108.1/tests/conftest.py

@@ -0,0 +1,26 @@
+from __future__ import annotations
+
+import pytest
+
+from plain.postgres.connection import DatabaseConnection
+from plain.postgres.db import _db_conn
+
+
+@pytest.fixture
+def _unblock_cursor() -> None:
+    """Restore the real cursor method (blocked by the autouse _db_disabled fixture)."""
+    DatabaseConnection.cursor = getattr(DatabaseConnection, "_enabled_cursor")
+
+
+@pytest.fixture
+def _clean_connection():
+    """Ensure the ContextVar starts empty and clean up any connection afterward."""
+    token = _db_conn.set(None)
+    yield
+    conn = _db_conn.get()
+    if conn is not None:
+        try:
+            conn.close()
+        except Exception:
+            pass
+    _db_conn.reset(token)

{plain_postgres-0.108.0 → plain_postgres-0.108.1}/tests/internal/test_connection_pool.py

@@ -18,20 +18,6 @@ from plain.postgres.sources import runtime_pool_source
 from plain.runtime import settings
 
 
-@pytest.fixture
-def _clean_connection():
-    """Ensure the ContextVar starts empty and clean up any connection afterward."""
-    token = _db_conn.set(None)
-    yield
-    conn = _db_conn.get()
-    if conn is not None:
-        try:
-            conn.close()
-        except Exception:
-            pass
-    _db_conn.reset(token)
-
-
 class TestPoolCheckoutReturn:
     @pytest.mark.usefixtures("_unblock_cursor", "_clean_connection")
     def test_checkout_and_return(self, setup_db):

plain_postgres-0.108.1/tests/internal/test_connection_self_heal.py

@@ -0,0 +1,131 @@
+"""Tests for self-healing after a server-side connection close.
+
+When Postgres closes a connection we're holding (restart, failover, idle
+timeout), psycopg only notices on the next I/O — the operation fails and the
+connection is marked closed. `ensure_connection()` must then discard the dead
+connection and acquire a fresh one, instead of reusing the dead object on
+every subsequent call.
+
+The exception is inside an atomic block: swapping there would silently run
+the rest of the block outside its transaction, so the dead connection stays
+put and `Atomic.__exit__`'s error recovery drops it instead.
+"""
+
+from __future__ import annotations
+
+import psycopg
+import pytest
+
+from plain.postgres import transaction
+from plain.postgres.db import get_connection
+from plain.postgres.sources import runtime_pool_source
+
+
+def _terminate_backend(pid: int) -> None:
+    """Kill a backend from a separate pool connection."""
+    terminator = runtime_pool_source.acquire()
+    try:
+        with terminator.cursor() as cursor:
+            cursor.execute("SELECT pg_terminate_backend(%s)", (pid,))
+    finally:
+        runtime_pool_source.release(terminator)
+
+
+def _backend_pid(conn) -> int:
+    with conn.cursor() as cursor:
+        cursor.execute("SELECT pg_backend_pid()")
+        row = cursor.fetchone()
+        assert row is not None
+        return row[0]
+
+
+class TestDeadConnectionSelfHeal:
+    @pytest.mark.usefixtures("_unblock_cursor", "_clean_connection")
+    def test_closed_connection_replaced_on_next_use(self, setup_db):
+        """A wrapper holding a closed psycopg connection acquires a fresh one."""
+        conn = get_connection()
+        with conn.cursor() as cursor:
+            cursor.execute("SELECT 1")
+
+        # Simulate the aftermath of a server-side close: the wrapper still
+        # holds a psycopg connection whose pgconn status is BAD.
+        assert conn.connection is not None
+        conn.connection.close()
+        assert conn.connection.closed
+
+        with conn.cursor() as cursor:
+            cursor.execute("SELECT 1")
+            assert cursor.fetchone() == (1,)
+        assert conn.connection is not None
+        assert not conn.connection.closed
+
+    @pytest.mark.usefixtures("_unblock_cursor", "_clean_connection")
+    def test_terminated_backend_errors_once_then_heals(self, setup_db):
+        """A server-side kill fails the in-flight query, then self-heals."""
+        conn = get_connection()
+        pid = _backend_pid(conn)
+
+        _terminate_backend(pid)
+
+        # psycopg only detects the dead socket on I/O — the first use fails
+        # and marks the connection closed.
+        with pytest.raises(psycopg.OperationalError):
+            with conn.cursor() as cursor:
+                cursor.execute("SELECT 1")
+        assert conn.connection is not None
+        assert conn.connection.closed
+
+        # The next use discards the dead connection and acquires a fresh one.
+        with conn.cursor() as cursor:
+            cursor.execute("SELECT 1")
+            assert cursor.fetchone() == (1,)
+        assert _backend_pid(conn) != pid
+
+    @pytest.mark.usefixtures("_unblock_cursor", "_clean_connection")
+    def test_dead_connection_not_swapped_mid_atomic(self, setup_db):
+        """Mid-atomic, the dead connection stays put — a silent swap would run
+        the rest of the block outside its transaction. Atomic.__exit__'s error
+        recovery drops it, and the next use heals."""
+        conn = get_connection()
+
+        def killed_mid_atomic() -> None:
+            with transaction.atomic():
+                pid = _backend_pid(conn)
+                _terminate_backend(pid)
+                with conn.cursor() as cursor:
+                    cursor.execute("SELECT 1")
+
+        with pytest.raises(psycopg.OperationalError):
+            killed_mid_atomic()
+
+        # Atomic.__exit__ dropped the dead connection during rollback recovery.
+        assert conn.connection is None
+
+        with conn.cursor() as cursor:
+            cursor.execute("SELECT 1")
+            assert cursor.fetchone() == (1,)
+
+    @pytest.mark.usefixtures("_unblock_cursor", "_clean_connection")
+    def test_dead_connection_in_nested_atomic(self, setup_db):
+        """Nested atomics: the inner savepoint rollback fails on the dead
+        connection and marks needs_rollback; the outer rollback then fails
+        too and drops the connection. The next use heals."""
+        conn = get_connection()
+
+        def killed_in_nested_atomic() -> None:
+            with transaction.atomic():
+                with transaction.atomic():
+                    pid = _backend_pid(conn)
+                    _terminate_backend(pid)
+                    with conn.cursor() as cursor:
+                        cursor.execute("SELECT 1")
+
+        with pytest.raises(psycopg.OperationalError):
+            killed_in_nested_atomic()
+
+        # The outer Atomic.__exit__ dropped the dead connection.
+        assert conn.connection is None
+
+        with conn.cursor() as cursor:
+            cursor.execute("SELECT 1")
+            assert cursor.fetchone() == (1,)

{plain_postgres-0.108.0 → plain_postgres-0.108.1}/tests/internal/test_otel_metrics.py

@@ -15,8 +15,10 @@ from opentelemetry.sdk.metrics.export import InMemoryMetricReader
 from opentelemetry.sdk.trace.export.in_memory_span_exporter import (
     InMemorySpanExporter,
 )
+from opentelemetry.trace import NoOpTracer
 from psycopg_pool import PoolTimeout
 
+from plain.postgres import otel as postgres_otel
 from plain.postgres.db import get_connection
 from plain.postgres.otel import register_pool_observables
 from plain.postgres.sources import runtime_pool_source
@@ -60,6 +62,33 @@ class TestQuerySpanAttributes:
         assert "server.port" in attrs
         assert attrs["server.port"] == attrs.get("network.peer.port")
 
+    def test_not_recording_skips_stack_walk(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # Cheap attributes still build unconditionally (attribute-aware
+        # samplers see them at span creation), but the per-query stack walk
+        # must only happen when the span actually records.
+        stack_walks: list[int] = []
+
+        def counting_code_attributes() -> dict[str, Any]:
+            stack_walks.append(1)
+            return {}
+
+        monkeypatch.setattr(
+            postgres_otel, "_get_code_attributes", counting_code_attributes
+        )
+        monkeypatch.setattr(postgres_otel, "tracer", NoOpTracer())
+
+        class StubDb:
+            settings_dict: dict[str, Any] = {}
+
+        with postgres_otel.db_span(StubDb(), "SELECT 1") as span:  # ty: ignore[invalid-argument-type]
+            pass
+
+        assert span is not None
+        assert not span.is_recording()
+        assert not stack_walks
+
 
 class TestReturnedRowsMetric:
     @pytest.mark.usefixtures("db")

plain_postgres-0.108.0/tests/conftest.py

@@ -1,11 +0,0 @@
-from __future__ import annotations
-
-import pytest
-
-from plain.postgres.connection import DatabaseConnection
-
-
-@pytest.fixture
-def _unblock_cursor() -> None:
-    """Restore the real cursor method (blocked by the autouse _db_disabled fixture)."""
-    DatabaseConnection.cursor = getattr(DatabaseConnection, "_enabled_cursor")