plain.postgres 0.84.2__tar.gz → 0.85.0__tar.gz

plain_postgres-0.85.0/CLAUDE.md

@@ -0,0 +1,11 @@
+# Developing plain-postgres
+
+## PostgreSQL
+
+Minimum supported version is **PostgreSQL 16** (enforced by preflight check). Use PG 16+ features freely.
+
+When implementing database features, fetch the official PostgreSQL docs to verify behavior — don't assume SQL semantics from memory. Check both the minimum version docs and the latest for newer features worth adopting: https://www.postgresql.org/docs/
+
+## psycopg3
+
+The database driver is psycopg3 (`import psycopg`). Prefer its native APIs over hand-rolled abstractions.

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: plain.postgres
-Version: 0.84.2
+Version: 0.85.0
 Summary: Model your data and store it in a database.
 Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
 License-Expression: BSD-3-Clause
@@ -382,6 +382,63 @@ for row in HugeTable.query.iterator(chunk_size=2000):
     process(row)
 ```
 
+## Transactions
+
+By default, each query runs in its own implicit transaction and is committed immediately (autocommit mode). When you need multiple queries to succeed or fail together — like creating a user and their profile — wrap them in an explicit transaction.
+
+### Atomic blocks
+
+Wrap multiple queries in a transaction with `transaction.atomic()`:
+
+```python
+from plain.postgres import transaction
+
+with transaction.atomic():
+    user = User(email="test@example.com")
+    user.save()
+    Profile(user=user).save()
+    # Both saves commit together, or both roll back on error
+```
+
+Nesting `atomic()` creates savepoints:
+
+```python
+with transaction.atomic():
+    user.save()
+    try:
+        with transaction.atomic():
+            risky_operation()  # If this fails...
+    except SomeError:
+        pass  # ...only the inner block rolls back
+    safe_operation()  # This still runs in the outer transaction
+```
+
+### Read-only connections
+
+Enforce read-only mode on the current database connection using `read_only()`. Any write (INSERT, UPDATE, DELETE, DDL) raises `psycopg.errors.ReadOnlySqlTransaction`:
+
+```python
+from plain.postgres.connections import read_only
+
+with read_only():
+    users = User.query.all()       # reads work
+    User.query.create(name="x")   # raises psycopg.errors.ReadOnlySqlTransaction
+```
+
+This works with both autocommit queries and explicit `atomic()` blocks.
+
+For sticky read-only mode (e.g., a shell session), use `set_read_only()` on the connection directly:
+
+```python
+from plain.postgres.db import get_connection
+
+conn = get_connection()
+conn.set_read_only(True)   # all subsequent queries are read-only
+conn.set_read_only(False)  # back to normal
+```
+
+Read-only mode must be set outside a transaction — calling it inside `atomic()` raises `TransactionManagementError`.
+
 ## Migrations
 
 Migrations track changes to your models and update the database schema accordingly. They are Python files stored in your app's `migrations/` directory.

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,19 @@
 # plain-postgres changelog
 
+## [0.85.0](https://github.com/dropseed/plain/releases/plain-postgres@0.85.0) (2026-03-22)
+
+### What's changed
+
+- Added read-only database connection support via `read_only()` context manager and `connection.set_read_only()` — enforces `SET default_transaction_read_only = ON` so any write attempt raises a database error ([69d23b04fde9](https://github.com/dropseed/plain/commit/69d23b04fde9))
+- Removed PEP-249 exception mirror — `IntegrityError`, `OperationalError`, `ProgrammingError`, etc. are no longer re-exported from `plain.postgres`. Use `psycopg` exceptions directly (e.g. `psycopg.IntegrityError`) ([d4b170e60a2c](https://github.com/dropseed/plain/commit/d4b170e60a2c))
+- Removed `DatabaseErrorWrapper` context manager — psycopg's native connection state handling replaces it ([015b04ce38e9](https://github.com/dropseed/plain/commit/015b04ce38e9))
+- Added transaction and read-only connection documentation to README
+
+### Upgrade instructions
+
+- Replace any `from plain.postgres import IntegrityError` (or `OperationalError`, `ProgrammingError`, etc.) with `import psycopg` and use `psycopg.IntegrityError` directly.
+- Replace any usage of `plain.postgres.db.DatabaseErrorWrapper` with standard `try/except` on psycopg exceptions.
+
 ## [0.84.2](https://github.com/dropseed/plain/releases/plain-postgres@0.84.2) (2026-03-20)
 
 ### What's changed

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/plain/postgres/README.md

@@ -370,6 +370,63 @@ for row in HugeTable.query.iterator(chunk_size=2000):
     process(row)
 ```
 
+## Transactions
+
+By default, each query runs in its own implicit transaction and is committed immediately (autocommit mode). When you need multiple queries to succeed or fail together — like creating a user and their profile — wrap them in an explicit transaction.
+
+### Atomic blocks
+
+Wrap multiple queries in a transaction with `transaction.atomic()`:
+
+```python
+from plain.postgres import transaction
+
+with transaction.atomic():
+    user = User(email="test@example.com")
+    user.save()
+    Profile(user=user).save()
+    # Both saves commit together, or both roll back on error
+```
+
+Nesting `atomic()` creates savepoints:
+
+```python
+with transaction.atomic():
+    user.save()
+    try:
+        with transaction.atomic():
+            risky_operation()  # If this fails...
+    except SomeError:
+        pass  # ...only the inner block rolls back
+    safe_operation()  # This still runs in the outer transaction
+```
+
+### Read-only connections
+
+Enforce read-only mode on the current database connection using `read_only()`. Any write (INSERT, UPDATE, DELETE, DDL) raises `psycopg.errors.ReadOnlySqlTransaction`:
+
+```python
+from plain.postgres.connections import read_only
+
+with read_only():
+    users = User.query.all()       # reads work
+    User.query.create(name="x")   # raises psycopg.errors.ReadOnlySqlTransaction
+```
+
+This works with both autocommit queries and explicit `atomic()` blocks.
+
+For sticky read-only mode (e.g., a shell session), use `set_read_only()` on the connection directly:
+
+```python
+from plain.postgres.db import get_connection
+
+conn = get_connection()
+conn.set_read_only(True)   # all subsequent queries are read-only
+conn.set_read_only(False)  # back to normal
+```
+
+Read-only mode must be set outside a transaction — calling it inside `atomic()` raises `TransactionManagementError`.
+
 ## Migrations
 
 Migrations track changes to your models and update the database schema accordingly. They are Python files stored in your app's `migrations/` directory.

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/plain/postgres/__init__.py

@@ -6,7 +6,7 @@ from . import (
 # Imports that would create circular imports if sorted
 from .base import Model
 from .constraints import CheckConstraint, UniqueConstraint
-from .db import IntegrityError, get_connection
+from .db import get_connection
 from .deletion import CASCADE, DO_NOTHING, PROTECT, RESTRICT, SET, SET_DEFAULT, SET_NULL
 from .enums import IntegerChoices, TextChoices
 from .fields import (
@@ -111,7 +111,6 @@ __all__ = [
     "ReverseManyToMany",
     # From db
     "get_connection",
-    "IntegrityError",
     # From registry
     "register_model",
     "models_registry",

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/plain/postgres/base.py

@@ -10,15 +10,14 @@ if TYPE_CHECKING:
     from plain.postgres.meta import Meta
     from plain.postgres.options import Options
 
+import psycopg
+
 import plain.runtime
 from plain.exceptions import NON_FIELD_ERRORS, ValidationError
 from plain.postgres import models_registry, transaction, types
 from plain.postgres.constants import LOOKUP_SEP
 from plain.postgres.constraints import CheckConstraint, UniqueConstraint
-from plain.postgres.db import (
-    PLAIN_VERSION_PICKLE_KEY,
-    DatabaseError,
-)
+from plain.postgres.db import PLAIN_VERSION_PICKLE_KEY
 from plain.postgres.deletion import Collector
 from plain.postgres.dialect import MAX_NAME_LENGTH
 from plain.postgres.exceptions import (
@@ -496,9 +495,11 @@ class Model(metaclass=ModelBase):
                 base_qs, id_val, values, update_fields, forced_update
             )
             if force_update and not updated:
-                raise DatabaseError("Forced update did not affect any rows.")
+                raise psycopg.DatabaseError("Forced update did not affect any rows.")
             if update_fields and not updated:
-                raise DatabaseError("Save with update_fields did not affect any rows.")
+                raise psycopg.DatabaseError(
+                    "Save with update_fields did not affect any rows."
+                )
         if not updated:
             fields = meta.local_concrete_fields
             if not id_set:

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/plain/postgres/cli/db.py

@@ -6,11 +6,12 @@ import time
 from collections import defaultdict
 
 import click
+import psycopg
 
 from plain.cli import register_cli
 
 from ..backups.cli import cli as backups_cli
-from ..db import OperationalError, get_connection
+from ..db import get_connection
 from ..dialect import quote_name
 from ..migrations.recorder import MIGRATION_TABLE_NAME
 
@@ -126,7 +127,7 @@ def wait() -> None:
 
         try:
             get_connection().ensure_connection()
-        except OperationalError:
+        except psycopg.OperationalError:
             waiting_for = True
 
         if waiting_for:

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/plain/postgres/connection.py

@@ -28,9 +28,6 @@ from psycopg.types.string import TextLoader
 from plain.exceptions import ImproperlyConfigured
 from plain.logs import get_framework_logger
 from plain.postgres import utils
-from plain.postgres.db import (
-    DatabaseErrorWrapper,
-)
 from plain.postgres.dialect import MAX_NAME_LENGTH, quote_name
 from plain.postgres.indexes import Index
 from plain.postgres.schema import DatabaseSchemaEditor
@@ -203,7 +200,6 @@ class DatabaseConnection:
         # Connection termination related attributes.
         self.close_at: float | None = None
         self.closed_in_transaction: bool = False
-        self.errors_occurred: bool = False
         self.health_check_enabled: bool = False
         self.health_check_done: bool = False
 
@@ -383,8 +379,30 @@ class DatabaseConnection:
     def _set_autocommit(self, autocommit: bool) -> None:
         """Backend-specific implementation to enable or disable autocommit."""
         assert self.connection is not None
-        with self.wrap_database_errors:
-            self.connection.autocommit = autocommit
+        self.connection.autocommit = autocommit
+
+    def set_read_only(self, read_only: bool) -> None:
+        """Set read-only mode on this connection.
+
+        When enabled, all subsequent transactions will be read-only —
+        any INSERT/UPDATE/DELETE/DDL will raise a database error.
+        This applies to both explicit transactions and autocommit queries.
+        Persists until changed or the connection is closed.
+
+        Must be called outside a transaction — the setting only takes
+        effect on the next transaction that starts.
+        """
+        if self.in_atomic_block:
+            raise TransactionManagementError(
+                "set_read_only() cannot be called inside a transaction. "
+                "Call it before entering an atomic block."
+            )
+        self.ensure_connection()
+        assert self.connection is not None
+        if read_only:
+            self.connection.execute("SET default_transaction_read_only = on")
+        else:
+            self.connection.execute("SET default_transaction_read_only = off")
 
     def check_constraints(self, table_names: list[str] | None = None) -> None:
         """
@@ -449,7 +467,6 @@ class DatabaseConnection:
         max_age = self.settings_dict["CONN_MAX_AGE"]
         self.close_at = None if max_age is None else time.monotonic() + max_age
         self.closed_in_transaction = False
-        self.errors_occurred = False
         # New connections are healthy.
         self.health_check_done = True
         # Establish the connection
@@ -463,8 +480,7 @@ class DatabaseConnection:
     def ensure_connection(self) -> None:
         """Guarantee that a connection to the database is established."""
         if self.connection is None:
-            with self.wrap_database_errors:
-                self.connect()
+            self.connect()
 
     # ##### PEP-249 connection method wrappers #####
 
@@ -481,23 +497,21 @@ class DatabaseConnection:
     def _cursor(self) -> utils.CursorWrapper:
         self.close_if_health_check_failed()
         self.ensure_connection()
-        with self.wrap_database_errors:
-            return self._prepare_cursor(self.create_cursor())
+        return self._prepare_cursor(self.create_cursor())
 
     def _commit(self) -> None:
         if self.connection is not None:
-            with debug_transaction(self, "COMMIT"), self.wrap_database_errors:
+            with debug_transaction(self, "COMMIT"):
                 return self.connection.commit()
 
     def _rollback(self) -> None:
         if self.connection is not None:
-            with debug_transaction(self, "ROLLBACK"), self.wrap_database_errors:
+            with debug_transaction(self, "ROLLBACK"):
                 return self.connection.rollback()
 
     def _close(self) -> None:
         if self.connection is not None:
-            with self.wrap_database_errors:
-                return self.connection.close()
+            return self.connection.close()
 
     # ##### Generic wrappers for PEP-249 connection methods #####
 
@@ -509,16 +523,12 @@ class DatabaseConnection:
         """Commit a transaction and reset the dirty flag."""
         self.validate_no_atomic_block()
         self._commit()
-        # A successful commit means that the database connection works.
-        self.errors_occurred = False
         self.run_commit_hooks_on_set_autocommit_on = True
 
     def rollback(self) -> None:
         """Roll back a transaction and reset the dirty flag."""
         self.validate_no_atomic_block()
         self._rollback()
-        # A successful rollback means that the database connection works.
-        self.errors_occurred = False
         self.needs_rollback = False
         self.run_on_commit = []
 
@@ -684,8 +694,8 @@ class DatabaseConnection:
 
     def close_if_unusable_or_obsolete(self) -> None:
         """
-        Close the current connection if unrecoverable errors have occurred
-        or if it outlived its maximum age.
+        Close the current connection if it's broken, improperly restored,
+        or has outlived its maximum age.
         """
         if self.connection is not None:
             self.health_check_done = False
@@ -695,15 +705,12 @@ class DatabaseConnection:
                 self.close()
                 return
 
-            # If an exception other than DataError or IntegrityError occurred
-            # since the last commit / rollback, check if the connection works.
-            if self.errors_occurred:
-                if self.is_usable():
-                    self.errors_occurred = False
-                    self.health_check_done = True
-                else:
-                    self.close()
-                    return
+            # If psycopg detected the connection is dead (e.g. server
+            # terminated the backend), close our wrapper so the next
+            # request gets a fresh connection.
+            if self.connection.closed:
+                self.close()
+                return
 
             if self.close_at is not None and time.monotonic() >= self.close_at:
                 self.close()
@@ -711,14 +718,6 @@ class DatabaseConnection:
 
     # ##### Miscellaneous #####
 
-    @cached_property
-    def wrap_database_errors(self) -> DatabaseErrorWrapper:
-        """
-        Context manager and decorator that re-throws backend-specific database
-        exceptions using Plain's common wrappers.
-        """
-        return DatabaseErrorWrapper(self)
-
     def make_cursor(self, cursor: Any) -> utils.CursorWrapper:
         """Create a cursor without debug logging."""
         return utils.CursorWrapper(cursor, self)

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/plain/postgres/connections.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+from collections.abc import Generator
+from contextlib import contextmanager
 from contextvars import ContextVar
 from typing import TYPE_CHECKING, Any, TypedDict
 
@@ -75,3 +77,22 @@ def get_connection() -> DatabaseConnection:
 def has_connection() -> bool:
     """Check if a database connection exists in the current context."""
     return _db_conn.get() is not None
+
+
+@contextmanager
+def read_only() -> Generator[None]:
+    """Set the current database connection to read-only for the duration of this block.
+
+    Any INSERT/UPDATE/DELETE/DDL will raise a database error. This applies
+    to all queries in the block — both explicit transactions and implicit
+    autocommit queries.
+    """
+    conn = get_connection()
+    conn.set_read_only(True)
+    try:
+        yield
+    finally:
+        try:
+            conn.set_read_only(False)
+        except Exception:
+            pass

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/plain/postgres/db.py

@@ -5,18 +5,6 @@ from typing import Any
 from plain import signals
 
 from .connections import get_connection, has_connection
-from .exceptions import (
-    DatabaseError,
-    DatabaseErrorWrapper,
-    DataError,
-    Error,
-    IntegrityError,
-    InterfaceError,
-    InternalError,
-    NotSupportedError,
-    OperationalError,
-    ProgrammingError,
-)
 
 PLAIN_VERSION_PICKLE_KEY = "_plain_version"
 
@@ -45,15 +33,5 @@ __all__ = [
     "get_connection",
     "has_connection",
     "PLAIN_VERSION_PICKLE_KEY",
-    "Error",
-    "InterfaceError",
-    "DatabaseError",
-    "DataError",
-    "OperationalError",
-    "IntegrityError",
-    "InternalError",
-    "ProgrammingError",
-    "NotSupportedError",
-    "DatabaseErrorWrapper",
     "close_old_connections",
 ]

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/plain/postgres/deletion.py

@@ -7,11 +7,12 @@ from itertools import chain
 from operator import attrgetter, or_
 from typing import TYPE_CHECKING, Any
 
+import psycopg
+
 from plain.postgres import (
     query_utils,
     transaction,
 )
-from plain.postgres.db import IntegrityError
 from plain.postgres.meta import Meta
 from plain.postgres.query import QuerySet
 from plain.postgres.sql import DeleteQuery, UpdateQuery
@@ -28,16 +29,16 @@ if TYPE_CHECKING:
 _LAZY_ON_DELETE: set[Callable[..., Any]] = set()
 
 
-class ProtectedError(IntegrityError):
+class ProtectedError(psycopg.IntegrityError):
     def __init__(self, msg: str, protected_objects: Iterable[Any]) -> None:
         self.protected_objects = protected_objects
-        super().__init__(msg, protected_objects)
+        super().__init__(msg)
 
 
-class RestrictedError(IntegrityError):
+class RestrictedError(psycopg.IntegrityError):
     def __init__(self, msg: str, restricted_objects: Iterable[Any]) -> None:
         self.restricted_objects = restricted_objects
-        super().__init__(msg, restricted_objects)
+        super().__init__(msg)
 
 
 def CASCADE(collector: Collector, field: RelatedField, sub_objs: Any) -> None:

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/plain/postgres/dialect.py

@@ -13,11 +13,11 @@ from collections.abc import Callable, Iterable
 from functools import lru_cache, partial
 from typing import TYPE_CHECKING, Any
 
+import psycopg
 from psycopg.types import numeric
 from psycopg.types.json import Jsonb
 
 from plain.postgres.constants import OnConflict
-from plain.postgres.db import NotSupportedError
 from plain.postgres.utils import split_tzname_delta
 from plain.utils import timezone
 from plain.utils.regex_helper import _lazy_re_compile
@@ -583,7 +583,7 @@ def window_frame_range_start_end(
     start_, end_ = window_frame_rows_start_end(start, end)
     # PostgreSQL only supports UNBOUNDED with PRECEDING/FOLLOWING
     if (start and start < 0) or (end and end > 0):
-        raise NotSupportedError(
+        raise psycopg.NotSupportedError(
             "PostgreSQL only supports UNBOUNDED together with PRECEDING and FOLLOWING."
         )
     return start_, end_

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/plain/postgres/exceptions.py

@@ -1,14 +1,6 @@
 from __future__ import annotations
 
-from collections.abc import Callable
-from typing import TYPE_CHECKING, Any, TypeVar, cast
-
-import psycopg
-
-if TYPE_CHECKING:
-    from plain.postgres.connection import DatabaseConnection
-
-F = TypeVar("F", bound=Callable[..., Any])
+from typing import Any, cast
 
 # MARK: Database Query Exceptions
 
@@ -119,99 +111,3 @@ class MultipleObjectsReturnedDescriptor:
 
     def __set__(self, instance: Any, value: Any) -> None:
         raise AttributeError("Cannot set MultipleObjectsReturned")
-
-
-# MARK: Database Exceptions (PEP-249)
-
-
-class Error(Exception):
-    pass
-
-
-class InterfaceError(Error):
-    pass
-
-
-class DatabaseError(Error):
-    pass
-
-
-class DataError(DatabaseError):
-    pass
-
-
-class OperationalError(DatabaseError):
-    pass
-
-
-class IntegrityError(DatabaseError):
-    pass
-
-
-class InternalError(DatabaseError):
-    pass
-
-
-class ProgrammingError(DatabaseError):
-    pass
-
-
-class NotSupportedError(DatabaseError):
-    pass
-
-
-class DatabaseErrorWrapper:
-    """
-    Context manager and decorator that reraises backend-specific database
-    exceptions using Plain's common wrappers.
-    """
-
-    def __init__(self, wrapper: DatabaseConnection) -> None:
-        """
-        wrapper is a database wrapper.
-
-        It must have a Database attribute defining PEP-249 exceptions.
-        """
-        self.wrapper = wrapper
-
-    def __enter__(self) -> None:
-        pass
-
-    def __exit__(
-        self,
-        exc_type: type[BaseException] | None,
-        exc_value: BaseException | None,
-        traceback: Any,
-    ) -> None:
-        if exc_type is None:
-            return
-        for plain_exc_type in (
-            DataError,
-            OperationalError,
-            IntegrityError,
-            InternalError,
-            ProgrammingError,
-            NotSupportedError,
-            DatabaseError,
-            InterfaceError,
-            Error,
-        ):
-            db_exc_type = getattr(psycopg, plain_exc_type.__name__)
-            if issubclass(exc_type, db_exc_type):
-                plain_exc_value = (
-                    plain_exc_type(*exc_value.args) if exc_value else plain_exc_type()
-                )
-                # Only set the 'errors_occurred' flag for errors that may make
-                # the connection unusable.
-                if plain_exc_type not in (DataError, IntegrityError):
-                    self.wrapper.errors_occurred = True
-                raise plain_exc_value.with_traceback(traceback) from exc_value
-
-    def __call__(self, func: F) -> F:
-        # Note that we are intentionally not using @wraps here for performance
-        # reasons. Refs #21109.
-        def inner(*args: Any, **kwargs: Any) -> Any:
-            with self:
-                return func(*args, **kwargs)
-
-        return cast(F, inner)

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/plain/postgres/expressions.py

@@ -11,9 +11,10 @@ from types import NoneType
 from typing import TYPE_CHECKING, Any, Protocol, Self, runtime_checkable
 from uuid import UUID
 
+import psycopg
+
 from plain.postgres import fields
 from plain.postgres.constants import LOOKUP_SEP
-from plain.postgres.db import NotSupportedError
 from plain.postgres.dialect import (
     CURRENT_ROW,
     FOLLOWING,
@@ -877,7 +878,7 @@ class ResolvedOuterRef(F):
     def resolve_expression(self, *args: Any, **kwargs: Any) -> Any:
         col = super().resolve_expression(*args, **kwargs)
         if col.contains_over_clause:
-            raise NotSupportedError(
+            raise psycopg.NotSupportedError(
                 f"Referencing outer query window expression is not supported: "
                 f"{self.name}."
             )

{plain_postgres-0.84.2 → plain_postgres-0.85.0}/plain/postgres/migrations/exceptions.py

@@ -2,7 +2,7 @@ from __future__ import annotations
 
 from typing import Any
 
-from plain.postgres.db import DatabaseError
+import psycopg
 
 
 class AmbiguityError(Exception):
@@ -50,5 +50,5 @@ class NodeNotFoundError(LookupError):
         return f"NodeNotFoundError({self.node!r})"
 
 
-class MigrationSchemaMissing(DatabaseError):
+class MigrationSchemaMissing(psycopg.DatabaseError):
     pass