plain.postgres 0.97.0__tar.gz → 0.98.0__tar.gz

plain_postgres-0.97.0/plain/postgres/README.md → plain_postgres-0.98.0/PKG-INFO

@@ -1,9 +1,25 @@
+Metadata-Version: 2.4
+Name: plain.postgres
+Version: 0.98.0
+Summary: Model your data and store it in a database.
+Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
+License-Expression: BSD-3-Clause
+License-File: LICENSE
+Requires-Python: >=3.13
+Requires-Dist: plain<1.0.0,>=0.134.0
+Requires-Dist: psycopg-pool>=3.2
+Requires-Dist: psycopg>=3.2
+Requires-Dist: sqlparse>=0.3.1
+Description-Content-Type: text/markdown
+
 # plain.postgres
 
 **Model your data and store it in a database.**
 
 - [Overview](#overview)
 - [Database connection](#database-connection)
+    - [Middleware](#middleware)
+    - [Bypassing a connection pooler for management operations](#bypassing-a-connection-pooler-for-management-operations)
 - [Querying](#querying)
 - [Schema management](#schema-management)
     - [Syncing](#syncing)
@@ -99,6 +115,24 @@ To explicitly disable the database (e.g. during Docker builds where no database
 PLAIN_POSTGRES_URL=none
 ```
 
+### Middleware
+
+Connections are checked out lazily on first use and returned to the pool when the HTTP request finishes. That's handled by [`DatabaseConnectionMiddleware`](./middleware.py#DatabaseConnectionMiddleware) — add it to `MIDDLEWARE` once you install `plain.postgres`:
+
+```python
+# app/settings.py
+MIDDLEWARE = [
+    "plain.postgres.DatabaseConnectionMiddleware",
+    # ...other middleware
+]
+```
+
+Place it near the top so downstream middleware can use the database inside `before_request` / `after_response` and still have the connection returned cleanly at the end.
+
+For `StreamingResponse` / `AsyncStreamingResponse`, the connection is returned after the body is fully drained (not when the view returns), so generators that lazily query the database — for example `Model.query.iterator()` or raw cursor loops — keep their cursor alive until the last chunk is sent.
+
+Without the middleware, connections keep living on their thread until something explicitly calls `plain.postgres.db.return_database_connection()` (or the process exits). That's fine for short-lived scripts but wastes a connection per thread in long-running servers.
+
 ### Bypassing a connection pooler for management operations
 
 Transaction-mode poolers (PlanetScale, Supabase's pooler, Neon's pooler, standalone pgbouncer in transaction mode) can't run DDL, long transactions, or `pg_dump`. To work around this, set a second URL that management commands use to reach Postgres directly:
@@ -128,14 +162,6 @@ with use_management_connection():
 
 You _can_ point the two URLs at different Postgres roles — e.g. a least-privilege DML role for runtime and a DDL-capable role for management. Plain does not currently automate the grant/ownership plumbing that split requires (default privileges for newly-created tables, ownership reassignment, preflight checks that the runtime role can see the schema). If you adopt that pattern, you're responsible for wiring those up yourself.
 
-**PostgreSQL is the only supported database.** You need to install a PostgreSQL driver separately — [psycopg](https://www.psycopg.org/) is recommended:
-
-```bash
-uv add psycopg[binary]  # Pre-built wheels, easiest for local development
-# or
-uv add psycopg[c]       # Compiled against your system's libpq, recommended for production
-```
-
 ## Querying
 
 Models come with a powerful query API through their [`QuerySet`](./query.py#QuerySet) interface:
@@ -443,32 +469,34 @@ with transaction.atomic():
     safe_operation()  # This still runs in the outer transaction
 ```
 
-### Read-only connections
+### Read-only transactions
 
-Enforce read-only mode on the current database connection using `read_only()`. Any write (INSERT, UPDATE, DELETE, DDL) raises `psycopg.errors.ReadOnlySqlTransaction`:
+Run a block of code in a read-only transaction using `read_only()`. Any write (INSERT, UPDATE, DELETE, DDL) raises `psycopg.errors.ReadOnlySqlTransaction`:
 
 ```python
-from plain.postgres.connections import read_only
+from plain.postgres.db 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.
+`read_only()` opens a single `BEGIN READ ONLY` transaction for the block. Nested `atomic()` blocks inside become savepoints of the outer read-only transaction and inherit read-only.
 
-For sticky read-only mode (e.g., a shell session), use `set_read_only()` on the connection directly:
+Because it opens its own transaction, `read_only()` cannot be entered inside an existing `atomic()` block — doing so raises `TransactionManagementError`.
 
-```python
-from plain.postgres.db import get_connection
+Because the whole block is one transaction, catching a database error inside `read_only()` and trying to keep reading will fail — the transaction is aborted and any further query raises `TransactionManagementError`. Wrap the write in a nested `atomic()` savepoint if you need to recover and continue:
 
-conn = get_connection()
-conn.set_read_only(True)   # all subsequent queries are read-only
-conn.set_read_only(False)  # back to normal
+```python
+with read_only():
+    try:
+        with atomic():
+            User.query.create(name="x")   # raises, savepoint rolls back
+    except psycopg.errors.ReadOnlySqlTransaction:
+        pass
+    User.query.count()   # still works — outer txn is healthy
 ```
 
-Read-only mode must be set outside a transaction — calling it inside `atomic()` raises `TransactionManagementError`.
-
 ## Schema management
 
 Schema changes fall into three categories, each with a different author and apply model:
@@ -1237,8 +1265,10 @@ The connection is configured with a single URL (`POSTGRES_URL`). `DATABASE_URL`
 | ---------------------------------------- | ------------- | ----------------------- | ---------------------------------------------- |
 | `POSTGRES_URL`                           | `Secret[str]` | `$DATABASE_URL` or `""` | `PLAIN_POSTGRES_URL`                           |
 | `POSTGRES_MANAGEMENT_URL`                | `Secret[str]` | `""`                    | `PLAIN_POSTGRES_MANAGEMENT_URL`                |
-| `POSTGRES_CONN_MAX_AGE`                  | `int`         | `600`                   | `PLAIN_POSTGRES_CONN_MAX_AGE`                  |
-| `POSTGRES_CONN_HEALTH_CHECKS`            | `bool`        | `True`                  | `PLAIN_POSTGRES_CONN_HEALTH_CHECKS`            |
+| `POSTGRES_POOL_MIN_SIZE`                 | `int`         | `4`                     | `PLAIN_POSTGRES_POOL_MIN_SIZE`                 |
+| `POSTGRES_POOL_MAX_SIZE`                 | `int`         | `20`                    | `PLAIN_POSTGRES_POOL_MAX_SIZE`                 |
+| `POSTGRES_POOL_MAX_LIFETIME`             | `float`       | `3600.0`                | `PLAIN_POSTGRES_POOL_MAX_LIFETIME`             |
+| `POSTGRES_POOL_TIMEOUT`                  | `float`       | `30.0`                  | `PLAIN_POSTGRES_POOL_TIMEOUT`                  |
 | `POSTGRES_MIGRATION_LOCK_TIMEOUT`        | `str`         | `"3s"`                  | `PLAIN_POSTGRES_MIGRATION_LOCK_TIMEOUT`        |
 | `POSTGRES_MIGRATION_STATEMENT_TIMEOUT`   | `str`         | `"3s"`                  | `PLAIN_POSTGRES_MIGRATION_STATEMENT_TIMEOUT`   |
 | `POSTGRES_CONVERGENCE_LOCK_TIMEOUT`      | `str`         | `"3s"`                  | `PLAIN_POSTGRES_CONVERGENCE_LOCK_TIMEOUT`      |
@@ -1282,13 +1312,15 @@ Currently, Plain supports a single database connection per application. For appl
 
 ## Installation
 
-Install the `plain.postgres` package from [PyPI](https://pypi.org/project/plain.postgres/):
+Install the `plain.postgres` package from [PyPI](https://pypi.org/project/plain.postgres/). You must also pick a `psycopg` implementation — `plain.postgres` depends on `psycopg` but does not pick one for you, so installing `plain.postgres` alone will not be able to connect.
 
 ```bash
-uv add plain.postgres psycopg[binary]
+uv add plain.postgres psycopg[binary]  # Pre-built wheels, easiest for local development
+# or
+uv add plain.postgres psycopg[c]       # Compiled against your system's libpq, recommended for production
 ```
 
-Then add to your `INSTALLED_PACKAGES`:
+Then add to your `INSTALLED_PACKAGES` and register [`DatabaseConnectionMiddleware`](#middleware) so pooled connections are returned at the end of each request:
 
 ```python
 # app/settings.py
@@ -1296,4 +1328,9 @@ INSTALLED_PACKAGES = [
     ...
     "plain.postgres",
 ]
+
+MIDDLEWARE = [
+    "plain.postgres.DatabaseConnectionMiddleware",
+    ...
+]
 ```

{plain_postgres-0.97.0 → plain_postgres-0.98.0}/plain/postgres/CHANGELOG.md

@@ -1,5 +1,53 @@
 # plain-postgres changelog
 
+## [0.98.0](https://github.com/dropseed/plain/releases/plain-postgres@0.98.0) (2026-04-22)
+
+### What's changed
+
+- **Pool-backed connections via `psycopg_pool.ConnectionPool`.** A new `sources` abstraction routes `DatabaseConnection` through either a long-lived `PoolSource` (runtime) or a `DirectSource` (management / one-shot). Each request checks a connection out of the pool on first use and returns it when the HTTP request finishes. `psycopg>=3.2` and `psycopg-pool>=3.2` are now declared as hard dependencies. ([2a51b25](https://github.com/dropseed/plain/commit/2a51b25))
+- **New `DatabaseConnectionMiddleware` (required).** Add `"plain.postgres.DatabaseConnectionMiddleware"` to `MIDDLEWARE` — it's what returns the pooled connection at the end of each request. For `StreamingResponse` / `AsyncStreamingResponse` the connection is returned after the body fully drains, so generators that lazily query the database (e.g. `Model.query.iterator()`) keep their cursor alive until the last chunk is sent. A new `postgres.middleware_installed` preflight check errors if the middleware is missing. ([2a51b25](https://github.com/dropseed/plain/commit/2a51b25))
+- **Connection settings replaced with pool settings.** `POSTGRES_CONN_MAX_AGE` and `POSTGRES_CONN_HEALTH_CHECKS` are gone. Tune the pool with `POSTGRES_POOL_MIN_SIZE` (default `4`), `POSTGRES_POOL_MAX_SIZE` (default `20`), `POSTGRES_POOL_MAX_LIFETIME` seconds (default `3600.0`), and `POSTGRES_POOL_TIMEOUT` seconds (default `30.0`). Each is also available as a `PLAIN_POSTGRES_POOL_*` environment variable. ([2a51b25](https://github.com/dropseed/plain/commit/2a51b25))
+- **`plain.postgres.connections` module removed.** `get_connection`, `has_connection`, `use_management_connection`, and `read_only` now live in `plain.postgres.db` (the underscore-less counterpart). ([2a51b25](https://github.com/dropseed/plain/commit/2a51b25))
+- **`read_only()` is now pgbouncer-safe.** It opens a single `BEGIN READ ONLY` transaction for the block (previously a session-level `SET default_transaction_read_only = on`). Nested `atomic()` blocks become savepoints of the outer read-only transaction. Entering `read_only()` inside an existing `atomic()` block now raises `TransactionManagementError`. The old `DatabaseConnection.set_read_only()` method is removed. ([ebdec30](https://github.com/dropseed/plain/commit/ebdec30))
+- **Added OTel pool + rowcount metrics and semconv polish.** Wires the `db.client.connection.*` metric family (count, max, idle.min/max, pending_requests, wait_time, use_time, timeouts) from the pool's stats and the acquire/release path, plus `db.client.response.returned_rows` for SELECT queries including streamed iterators. Query spans now carry `server.address` / `server.port` alongside `network.peer.*`, and the tracer/meter are tagged with the `plain.postgres` package version for `InstrumentationScope`. ([61278d5](https://github.com/dropseed/plain/commit/61278d5))
+- **Moved `psql` CLI orchestration off `DatabaseConnection`.** New `postgres_cli_args` / `postgres_cli_env` helpers in `plain.postgres.database_url` build the arguments and environment for `psql`, `pg_dump`, etc.; `plain postgres shell` and the `plain-dev` backup client both use them. `DatabaseConnection.runshell()` and `executable_name` are gone. ([5b4a488](https://github.com/dropseed/plain/commit/5b4a488))
+- **Removed dead connection-lifecycle plumbing.** `close_if_unusable_or_obsolete`, `close_if_health_check_failed`, `closed_in_transaction`, `is_usable`, `health_check_enabled`, `health_check_done`, `close_at`, `_maintenance_cursor`, and `DatabaseConnection.from_url` are gone — the pool handles recycling, health checks, and URL parsing. `close()` now validates there's no open atomic block instead of silently deferring. ([044e942](https://github.com/dropseed/plain/commit/044e942), [2a51b25](https://github.com/dropseed/plain/commit/2a51b25))
+- **Inlined `pg_version` and removed `temporary_connection()`.** The single caller now reads `connection.info.server_version` directly; `temporary_connection()` has no remaining users. ([319f6ac](https://github.com/dropseed/plain/commit/319f6ac))
+- **`APIResult` shorthand returns moved out of `View`.** Any internal views that relied on dict/int shorthand now wrap their returns in `JsonResponse` / `Response(status_code=...)` to match plain 0.134.0's narrower `View` handler return type. ([1935f3f](https://github.com/dropseed/plain/commit/1935f3f))
+- **Adapter registration extracted to `plain.postgres.adapters`.** `PlainRangeDumper` and `get_adapters_template()` moved out of `connection.py` into their own module.
+
+### Upgrade instructions
+
+- Requires `plain>=0.134.0`.
+- **Add the middleware** to `app/settings.py`:
+
+    ```python
+    MIDDLEWARE = [
+        "plain.postgres.DatabaseConnectionMiddleware",
+        # ...the rest of your middleware
+    ]
+    ```
+
+    Place it near the top so downstream middleware can use the database inside `before_request` / `after_response` and still have the connection returned cleanly. Preflight will error if it's missing.
+
+- **Replace `POSTGRES_CONN_MAX_AGE` / `POSTGRES_CONN_HEALTH_CHECKS`** with the pool settings (`POSTGRES_POOL_MIN_SIZE`, `POSTGRES_POOL_MAX_SIZE`, `POSTGRES_POOL_MAX_LIFETIME`, `POSTGRES_POOL_TIMEOUT`) or remove them to take the defaults.
+
+- **Update imports from `plain.postgres.connections`** to `plain.postgres.db`:
+
+    ```python
+    # Before
+    from plain.postgres.connections import get_connection, read_only, use_management_connection
+
+    # After
+    from plain.postgres.db import get_connection, read_only, use_management_connection
+    ```
+
+- **If you called `DatabaseConnection.set_read_only(True)`** for a sticky read-only session, switch to the `read_only()` context manager around the block you want read-only. If you need session-level enforcement outside a transaction, open a `DirectSource` connection yourself and issue `SET default_transaction_read_only = on` on it.
+
+- **If you entered `read_only()` inside an `atomic()` block**, move `read_only()` to the outer position — it now owns the transaction. Nested `atomic()` blocks inside `read_only()` are fine (they become savepoints).
+
+- **If you pinned `psycopg` via your own dependency**, make sure it's `>=3.2`, and add `psycopg-pool>=3.2` if you were installing psycopg without extras.
+
 ## [0.97.0](https://github.com/dropseed/plain/releases/plain-postgres@0.97.0) (2026-04-21)
 
 ### What's changed

plain_postgres-0.97.0/PKG-INFO → plain_postgres-0.98.0/plain/postgres/README.md

@@ -1,21 +1,11 @@
-Metadata-Version: 2.4
-Name: plain.postgres
-Version: 0.97.0
-Summary: Model your data and store it in a database.
-Author-email: Dave Gaeddert <dave.gaeddert@dropseed.dev>
-License-Expression: BSD-3-Clause
-License-File: LICENSE
-Requires-Python: >=3.13
-Requires-Dist: plain<1.0.0,>=0.132.0
-Requires-Dist: sqlparse>=0.3.1
-Description-Content-Type: text/markdown
-
 # plain.postgres
 
 **Model your data and store it in a database.**
 
 - [Overview](#overview)
 - [Database connection](#database-connection)
+    - [Middleware](#middleware)
+    - [Bypassing a connection pooler for management operations](#bypassing-a-connection-pooler-for-management-operations)
 - [Querying](#querying)
 - [Schema management](#schema-management)
     - [Syncing](#syncing)
@@ -111,6 +101,24 @@ To explicitly disable the database (e.g. during Docker builds where no database
 PLAIN_POSTGRES_URL=none
 ```
 
+### Middleware
+
+Connections are checked out lazily on first use and returned to the pool when the HTTP request finishes. That's handled by [`DatabaseConnectionMiddleware`](./middleware.py#DatabaseConnectionMiddleware) — add it to `MIDDLEWARE` once you install `plain.postgres`:
+
+```python
+# app/settings.py
+MIDDLEWARE = [
+    "plain.postgres.DatabaseConnectionMiddleware",
+    # ...other middleware
+]
+```
+
+Place it near the top so downstream middleware can use the database inside `before_request` / `after_response` and still have the connection returned cleanly at the end.
+
+For `StreamingResponse` / `AsyncStreamingResponse`, the connection is returned after the body is fully drained (not when the view returns), so generators that lazily query the database — for example `Model.query.iterator()` or raw cursor loops — keep their cursor alive until the last chunk is sent.
+
+Without the middleware, connections keep living on their thread until something explicitly calls `plain.postgres.db.return_database_connection()` (or the process exits). That's fine for short-lived scripts but wastes a connection per thread in long-running servers.
+
 ### Bypassing a connection pooler for management operations
 
 Transaction-mode poolers (PlanetScale, Supabase's pooler, Neon's pooler, standalone pgbouncer in transaction mode) can't run DDL, long transactions, or `pg_dump`. To work around this, set a second URL that management commands use to reach Postgres directly:
@@ -140,14 +148,6 @@ with use_management_connection():
 
 You _can_ point the two URLs at different Postgres roles — e.g. a least-privilege DML role for runtime and a DDL-capable role for management. Plain does not currently automate the grant/ownership plumbing that split requires (default privileges for newly-created tables, ownership reassignment, preflight checks that the runtime role can see the schema). If you adopt that pattern, you're responsible for wiring those up yourself.
 
-**PostgreSQL is the only supported database.** You need to install a PostgreSQL driver separately — [psycopg](https://www.psycopg.org/) is recommended:
-
-```bash
-uv add psycopg[binary]  # Pre-built wheels, easiest for local development
-# or
-uv add psycopg[c]       # Compiled against your system's libpq, recommended for production
-```
-
 ## Querying
 
 Models come with a powerful query API through their [`QuerySet`](./query.py#QuerySet) interface:
@@ -455,32 +455,34 @@ with transaction.atomic():
     safe_operation()  # This still runs in the outer transaction
 ```
 
-### Read-only connections
+### Read-only transactions
 
-Enforce read-only mode on the current database connection using `read_only()`. Any write (INSERT, UPDATE, DELETE, DDL) raises `psycopg.errors.ReadOnlySqlTransaction`:
+Run a block of code in a read-only transaction using `read_only()`. Any write (INSERT, UPDATE, DELETE, DDL) raises `psycopg.errors.ReadOnlySqlTransaction`:
 
 ```python
-from plain.postgres.connections import read_only
+from plain.postgres.db 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.
+`read_only()` opens a single `BEGIN READ ONLY` transaction for the block. Nested `atomic()` blocks inside become savepoints of the outer read-only transaction and inherit read-only.
 
-For sticky read-only mode (e.g., a shell session), use `set_read_only()` on the connection directly:
+Because it opens its own transaction, `read_only()` cannot be entered inside an existing `atomic()` block — doing so raises `TransactionManagementError`.
 
-```python
-from plain.postgres.db import get_connection
+Because the whole block is one transaction, catching a database error inside `read_only()` and trying to keep reading will fail — the transaction is aborted and any further query raises `TransactionManagementError`. Wrap the write in a nested `atomic()` savepoint if you need to recover and continue:
 
-conn = get_connection()
-conn.set_read_only(True)   # all subsequent queries are read-only
-conn.set_read_only(False)  # back to normal
+```python
+with read_only():
+    try:
+        with atomic():
+            User.query.create(name="x")   # raises, savepoint rolls back
+    except psycopg.errors.ReadOnlySqlTransaction:
+        pass
+    User.query.count()   # still works — outer txn is healthy
 ```
 
-Read-only mode must be set outside a transaction — calling it inside `atomic()` raises `TransactionManagementError`.
-
 ## Schema management
 
 Schema changes fall into three categories, each with a different author and apply model:
@@ -1249,8 +1251,10 @@ The connection is configured with a single URL (`POSTGRES_URL`). `DATABASE_URL`
 | ---------------------------------------- | ------------- | ----------------------- | ---------------------------------------------- |
 | `POSTGRES_URL`                           | `Secret[str]` | `$DATABASE_URL` or `""` | `PLAIN_POSTGRES_URL`                           |
 | `POSTGRES_MANAGEMENT_URL`                | `Secret[str]` | `""`                    | `PLAIN_POSTGRES_MANAGEMENT_URL`                |
-| `POSTGRES_CONN_MAX_AGE`                  | `int`         | `600`                   | `PLAIN_POSTGRES_CONN_MAX_AGE`                  |
-| `POSTGRES_CONN_HEALTH_CHECKS`            | `bool`        | `True`                  | `PLAIN_POSTGRES_CONN_HEALTH_CHECKS`            |
+| `POSTGRES_POOL_MIN_SIZE`                 | `int`         | `4`                     | `PLAIN_POSTGRES_POOL_MIN_SIZE`                 |
+| `POSTGRES_POOL_MAX_SIZE`                 | `int`         | `20`                    | `PLAIN_POSTGRES_POOL_MAX_SIZE`                 |
+| `POSTGRES_POOL_MAX_LIFETIME`             | `float`       | `3600.0`                | `PLAIN_POSTGRES_POOL_MAX_LIFETIME`             |
+| `POSTGRES_POOL_TIMEOUT`                  | `float`       | `30.0`                  | `PLAIN_POSTGRES_POOL_TIMEOUT`                  |
 | `POSTGRES_MIGRATION_LOCK_TIMEOUT`        | `str`         | `"3s"`                  | `PLAIN_POSTGRES_MIGRATION_LOCK_TIMEOUT`        |
 | `POSTGRES_MIGRATION_STATEMENT_TIMEOUT`   | `str`         | `"3s"`                  | `PLAIN_POSTGRES_MIGRATION_STATEMENT_TIMEOUT`   |
 | `POSTGRES_CONVERGENCE_LOCK_TIMEOUT`      | `str`         | `"3s"`                  | `PLAIN_POSTGRES_CONVERGENCE_LOCK_TIMEOUT`      |
@@ -1294,13 +1298,15 @@ Currently, Plain supports a single database connection per application. For appl
 
 ## Installation
 
-Install the `plain.postgres` package from [PyPI](https://pypi.org/project/plain.postgres/):
+Install the `plain.postgres` package from [PyPI](https://pypi.org/project/plain.postgres/). You must also pick a `psycopg` implementation — `plain.postgres` depends on `psycopg` but does not pick one for you, so installing `plain.postgres` alone will not be able to connect.
 
 ```bash
-uv add plain.postgres psycopg[binary]
+uv add plain.postgres psycopg[binary]  # Pre-built wheels, easiest for local development
+# or
+uv add plain.postgres psycopg[c]       # Compiled against your system's libpq, recommended for production
 ```
 
-Then add to your `INSTALLED_PACKAGES`:
+Then add to your `INSTALLED_PACKAGES` and register [`DatabaseConnectionMiddleware`](#middleware) so pooled connections are returned at the end of each request:
 
 ```python
 # app/settings.py
@@ -1308,4 +1314,9 @@ INSTALLED_PACKAGES = [
     ...
     "plain.postgres",
 ]
+
+MIDDLEWARE = [
+    "plain.postgres.DatabaseConnectionMiddleware",
+    ...
+]
 ```

{plain_postgres-0.97.0 → plain_postgres-0.98.0}/plain/postgres/__init__.py

@@ -7,6 +7,7 @@ from . import (
 from .base import Model
 from .constraints import CheckConstraint, UniqueConstraint
 from .db import get_connection, use_management_connection
+from .middleware import DatabaseConnectionMiddleware
 from .deletion import CASCADE, NO_ACTION, RESTRICT, SET_NULL
 from .expressions import F
 from .enums import TextChoices
@@ -105,6 +106,8 @@ __all__ = [
     # From db
     "get_connection",
     "use_management_connection",
+    # From middleware
+    "DatabaseConnectionMiddleware",
     # From registry
     "register_model",
     "models_registry",

plain_postgres-0.98.0/plain/postgres/adapters.py

@@ -0,0 +1,41 @@
+"""Psycopg adapter registration for Plain.
+
+The `AdaptersMap` returned by `get_adapters_template()` is attached to every
+psycopg connection we open (via `build_connection_params` in `sources.py`).
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from typing import Any
+
+from psycopg import adapt, adapters
+from psycopg.abc import PyFormat
+from psycopg.postgres import types as pg_types
+from psycopg.types.range import BaseRangeDumper, Range, RangeDumper
+from psycopg.types.string import TextLoader
+
+TSRANGE_OID = pg_types["tsrange"].oid
+TSTZRANGE_OID = pg_types["tstzrange"].oid
+
+
+class PlainRangeDumper(RangeDumper):
+    """A Range dumper customized for Plain."""
+
+    def upgrade(self, obj: Range[Any], format: PyFormat) -> BaseRangeDumper:
+        dumper = super().upgrade(obj, format)
+        if dumper is not self and dumper.oid == TSRANGE_OID:
+            dumper.oid = TSTZRANGE_OID
+        return dumper
+
+
+@lru_cache
+def get_adapters_template() -> adapt.AdaptersMap:
+    ctx = adapt.AdaptersMap(adapters)
+    # No-op JSON loader to avoid psycopg3 round trips
+    ctx.register_loader("jsonb", TextLoader)
+    # Treat inet/cidr as text
+    ctx.register_loader("inet", TextLoader)
+    ctx.register_loader("cidr", TextLoader)
+    ctx.register_dumper(Range, PlainRangeDumper)
+    return ctx

{plain_postgres-0.97.0 → plain_postgres-0.98.0}/plain/postgres/cli/core.py

@@ -1,5 +1,7 @@
 from __future__ import annotations
 
+import os
+import signal
 import subprocess
 import sys
 import time
@@ -10,6 +12,7 @@ import psycopg
 
 from plain.cli import register_cli
 
+from ..database_url import postgres_cli_args, postgres_cli_env
 from ..db import get_connection
 from ..dialect import quote_name
 from .converge import converge
@@ -36,16 +39,20 @@ cli.add_command(sync)
 @database_management_command
 def shell(parameters: tuple[str, ...]) -> None:
     """Open an interactive database shell"""
-    conn = get_connection()
+    config = get_connection().settings_dict
+    args = ["psql", *postgres_cli_args(config), *parameters, config["DATABASE"]]
+    env = {**os.environ, **postgres_cli_env(config)}
+    sigint_handler = signal.getsignal(signal.SIGINT)
     try:
-        conn.runshell(list(parameters))
+        # Allow SIGINT to pass to psql to abort queries.
+        signal.signal(signal.SIGINT, signal.SIG_IGN)
+        subprocess.run(args, env=env, check=True)
     except FileNotFoundError:
-        # Note that we're assuming the FileNotFoundError relates to the
-        # command missing. It could be raised for some other reason, in
-        # which case this error message would be inaccurate. Still, this
-        # message catches the common case.
+        # FileNotFoundError almost always means psql isn't installed or on
+        # PATH, but could be raised for other reasons — the message covers
+        # the common case.
         click.secho(
-            f"You appear not to have the {conn.executable_name!r} program installed or on your path.",
+            "You appear not to have the 'psql' program installed or on your path.",
             fg="red",
             err=True,
         )
@@ -60,6 +67,8 @@ def shell(parameters: tuple[str, ...]) -> None:
             err=True,
         )
         sys.exit(e.returncode)
+    finally:
+        signal.signal(signal.SIGINT, sigint_handler)
 
 
 @cli.command("drop-unknown-tables")

{plain_postgres-0.97.0 → plain_postgres-0.98.0}/plain/postgres/config.py

@@ -4,7 +4,9 @@ from plain.packages import (
     register_config,
 )
 
+from .otel import register_pool_observables
 from .registry import models_registry
+from .sources import runtime_pool_source
 
 
 @register_config
@@ -16,3 +18,5 @@ class Config(PackageConfig):
         packages_registry.autodiscover_modules("models", include_app=False)
 
         models_registry.ready = True
+
+        register_pool_observables(runtime_pool_source)