plain.postgres 0.96.0__tar.gz → 0.98.0__tar.gz

plain_postgres-0.96.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)
@@ -70,35 +86,82 @@ admin_users = User.query.filter(is_admin=True)
 
 ## Database connection
 
-To connect to a database, you can provide a `DATABASE_URL` environment variable:
+Configure the database with a single URL. The canonical Plain setting is `POSTGRES_URL`:
+
+```python
+# app/settings.py
+POSTGRES_URL = "postgresql://user:password@localhost:5432/dbname"
+```
+
+Or via environment variable:
+
+```sh
+PLAIN_POSTGRES_URL=postgresql://user:password@localhost:5432/dbname
+```
+
+Plain also reads the `DATABASE_URL` environment variable as a fallback — it's the widely-used convention for Postgres connection strings, so most hosting setups work without extra configuration:
 
 ```sh
 DATABASE_URL=postgresql://user:password@localhost:5432/dbname
 ```
 
-Or you can set the individual `POSTGRES_*` settings (via `PLAIN_POSTGRES_*` environment variables or in `app/settings.py`):
+Precedence (highest to lowest): `PLAIN_POSTGRES_URL` → `POSTGRES_URL` in `settings.py` → `DATABASE_URL` environment variable.
+
+The URL supports any libpq connection parameter as a query string — for example `?sslmode=require&application_name=web&connect_timeout=10`. These are parsed and passed through to the driver.
+
+To explicitly disable the database (e.g. during Docker builds where no database is available), set the URL to the string `none`:
+
+```sh
+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
-POSTGRES_HOST = "localhost"
-POSTGRES_PORT = 5432
-POSTGRES_DATABASE = "dbname"
-POSTGRES_USER = "user"
-POSTGRES_PASSWORD = "password"
+MIDDLEWARE = [
+    "plain.postgres.DatabaseConnectionMiddleware",
+    # ...other middleware
+]
 ```
 
-If `DATABASE_URL` is set, it takes priority and the individual connection settings are parsed from it.
+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.
 
-To explicitly disable the database (e.g. during Docker builds where no database is available), set `DATABASE_URL=none`.
+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.
 
-**PostgreSQL is the only supported database.** You need to install a PostgreSQL driver separately — [psycopg](https://www.psycopg.org/) is recommended:
+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.
 
-```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
+### 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:
+
+```sh
+PLAIN_POSTGRES_URL=postgresql://app@pooler:6432/myapp
+PLAIN_POSTGRES_MANAGEMENT_URL=postgresql://app@postgres:5432/myapp
 ```
 
+When `POSTGRES_MANAGEMENT_URL` is set, these commands connect through it instead of `POSTGRES_URL`:
+
+- `plain migrations create`, `plain migrations apply`, `plain migrations list`, `plain migrations prune`, `plain migrations squash`
+- `plain postgres sync`, `plain postgres converge`, `plain postgres schema`
+- `plain postgres diagnose`, `plain postgres drop-unknown-tables`, `plain postgres shell`
+
+When it's unset, all commands use `POSTGRES_URL` — there's no behavior change for existing apps.
+
+To route custom code through the management connection, use the `use_management_connection()` context manager:
+
+```python
+from plain.postgres import use_management_connection
+
+with use_management_connection():
+    # Any get_connection() / ORM calls inside this block use POSTGRES_MANAGEMENT_URL.
+    run_custom_schema_change()
+```
+
+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.
+
 ## Querying
 
 Models come with a powerful query API through their [`QuerySet`](./query.py#QuerySet) interface:
@@ -406,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:
@@ -1194,27 +1259,20 @@ These are static, code-level checks that catch issues before you deploy. The `di
 
 ## Settings
 
-Connection settings are configured via `DATABASE_URL` or individual `POSTGRES_*` settings.
-
-When `DATABASE_URL` is set, it is parsed into the individual connection settings automatically. When `DATABASE_URL` is not set, the connection settings are required individually.
-
-Set `DATABASE_URL=none` to explicitly disable the database (e.g. during Docker image builds).
-
-| Setting                                  | Type          | Default | Env var                                        |
-| ---------------------------------------- | ------------- | ------- | ---------------------------------------------- |
-| `POSTGRES_HOST`                          | `str`         | —       | `PLAIN_POSTGRES_HOST`                          |
-| `POSTGRES_PORT`                          | `int \| None` | `None`  | `PLAIN_POSTGRES_PORT`                          |
-| `POSTGRES_DATABASE`                      | `str`         | —       | `PLAIN_POSTGRES_DATABASE`                      |
-| `POSTGRES_USER`                          | `str`         | —       | `PLAIN_POSTGRES_USER`                          |
-| `POSTGRES_PASSWORD`                      | `Secret[str]` | —       | `PLAIN_POSTGRES_PASSWORD`                      |
-| `POSTGRES_CONN_MAX_AGE`                  | `int`         | `600`   | `PLAIN_POSTGRES_CONN_MAX_AGE`                  |
-| `POSTGRES_CONN_HEALTH_CHECKS`            | `bool`        | `True`  | `PLAIN_POSTGRES_CONN_HEALTH_CHECKS`            |
-| `POSTGRES_OPTIONS`                       | `dict`        | `{}`    | —                                              |
-| `POSTGRES_TIME_ZONE`                     | `str \| None` | `None`  | `PLAIN_POSTGRES_TIME_ZONE`                     |
-| `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`      |
-| `POSTGRES_CONVERGENCE_STATEMENT_TIMEOUT` | `str`         | `"3s"`  | `PLAIN_POSTGRES_CONVERGENCE_STATEMENT_TIMEOUT` |
+The connection is configured with a single URL (`POSTGRES_URL`). `DATABASE_URL` is read as a platform-compat fallback. Set the URL to `none` to explicitly disable the database (e.g. during Docker image builds).
+
+| Setting                                  | Type          | Default                 | Env var                                        |
+| ---------------------------------------- | ------------- | ----------------------- | ---------------------------------------------- |
+| `POSTGRES_URL`                           | `Secret[str]` | `$DATABASE_URL` or `""` | `PLAIN_POSTGRES_URL`                           |
+| `POSTGRES_MANAGEMENT_URL`                | `Secret[str]` | `""`                    | `PLAIN_POSTGRES_MANAGEMENT_URL`                |
+| `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`      |
+| `POSTGRES_CONVERGENCE_STATEMENT_TIMEOUT` | `str`         | `"3s"`                  | `PLAIN_POSTGRES_CONVERGENCE_STATEMENT_TIMEOUT` |
 
 See [`default_settings.py`](./default_settings.py) for more details.
 
@@ -1254,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
@@ -1268,4 +1328,9 @@ INSTALLED_PACKAGES = [
     ...
     "plain.postgres",
 ]
+
+MIDDLEWARE = [
+    "plain.postgres.DatabaseConnectionMiddleware",
+    ...
+]
 ```

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

@@ -1,5 +1,83 @@
 # 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
+
+- **Replaced individual `POSTGRES_*` connection fields with a single `POSTGRES_URL` setting.** `POSTGRES_HOST`, `POSTGRES_PORT`, `POSTGRES_DATABASE`, `POSTGRES_USER`, `POSTGRES_PASSWORD`, `POSTGRES_OPTIONS`, and `POSTGRES_TIME_ZONE` are gone — configure the connection with one URL (e.g. `postgresql://user:pass@host:5432/db?sslmode=require`). `DATABASE_URL` is still read as a fallback. Set the URL to `none` to explicitly disable the database (e.g. during Docker image builds). ([770a74606463](https://github.com/dropseed/plain/commit/770a74606463))
+- **Added `POSTGRES_MANAGEMENT_URL` for routing DDL through a separate connection.** When set, `plain migrations create|apply|list|prune|squash`, `plain postgres sync|converge|schema|diagnose|drop-unknown-tables|shell` connect through this URL instead of `POSTGRES_URL`. Use it to bypass transaction-mode poolers (PlanetScale, Supabase's pooler, Neon's pooler, pgbouncer) for schema changes, long transactions, and `pg_dump`. A new `use_management_connection()` context manager routes custom code through the same connection. When unset, all commands use `POSTGRES_URL` — no behavior change for existing apps. ([d1cc9630d049](https://github.com/dropseed/plain/commit/d1cc9630d049))
+- **Extracted the test-database lifecycle off `DatabaseConnection`.** Test setup/teardown now lives in `plain.postgres.test` instead of coupling it to the runtime connection class. ([ea67f82c746c](https://github.com/dropseed/plain/commit/ea67f82c746c))
+- **Removed thin psycopg re-export wrappers.** Internal code now imports directly from `psycopg` rather than the redundant Plain-level passthroughs. ([d1cb74100e0d](https://github.com/dropseed/plain/commit/d1cb74100e0d))
+
+### Upgrade instructions
+
+- **Replace individual `POSTGRES_*` settings with `POSTGRES_URL`** in `app/settings.py` (or `PLAIN_POSTGRES_URL` in the environment). For example:
+
+    ```python
+    # Before
+    POSTGRES_HOST = "localhost"
+    POSTGRES_PORT = 5432
+    POSTGRES_DATABASE = "myapp"
+    POSTGRES_USER = "app"
+    POSTGRES_PASSWORD = "secret"
+
+    # After
+    POSTGRES_URL = "postgresql://app:secret@localhost:5432/myapp"
+    ```
+
+    Apps that already set `DATABASE_URL` in the environment don't need any change.
+
+- **If `POSTGRES_OPTIONS` or `POSTGRES_TIME_ZONE` were set**, move them into the URL as query parameters (e.g. `?application_name=web&timezone=UTC`).
+- **If you run behind a transaction-mode pooler**, consider setting `POSTGRES_MANAGEMENT_URL` to a direct-to-Postgres connection string so `plain migrations` and `plain postgres sync` can issue DDL.
+
 ## [0.96.0](https://github.com/dropseed/plain/releases/plain-postgres@0.96.0) (2026-04-17)
 
 ### What's changed

plain_postgres-0.96.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.96.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)
@@ -82,35 +72,82 @@ admin_users = User.query.filter(is_admin=True)
 
 ## Database connection
 
-To connect to a database, you can provide a `DATABASE_URL` environment variable:
+Configure the database with a single URL. The canonical Plain setting is `POSTGRES_URL`:
+
+```python
+# app/settings.py
+POSTGRES_URL = "postgresql://user:password@localhost:5432/dbname"
+```
+
+Or via environment variable:
+
+```sh
+PLAIN_POSTGRES_URL=postgresql://user:password@localhost:5432/dbname
+```
+
+Plain also reads the `DATABASE_URL` environment variable as a fallback — it's the widely-used convention for Postgres connection strings, so most hosting setups work without extra configuration:
 
 ```sh
 DATABASE_URL=postgresql://user:password@localhost:5432/dbname
 ```
 
-Or you can set the individual `POSTGRES_*` settings (via `PLAIN_POSTGRES_*` environment variables or in `app/settings.py`):
+Precedence (highest to lowest): `PLAIN_POSTGRES_URL` → `POSTGRES_URL` in `settings.py` → `DATABASE_URL` environment variable.
+
+The URL supports any libpq connection parameter as a query string — for example `?sslmode=require&application_name=web&connect_timeout=10`. These are parsed and passed through to the driver.
+
+To explicitly disable the database (e.g. during Docker builds where no database is available), set the URL to the string `none`:
+
+```sh
+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
-POSTGRES_HOST = "localhost"
-POSTGRES_PORT = 5432
-POSTGRES_DATABASE = "dbname"
-POSTGRES_USER = "user"
-POSTGRES_PASSWORD = "password"
+MIDDLEWARE = [
+    "plain.postgres.DatabaseConnectionMiddleware",
+    # ...other middleware
+]
 ```
 
-If `DATABASE_URL` is set, it takes priority and the individual connection settings are parsed from it.
+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.
 
-To explicitly disable the database (e.g. during Docker builds where no database is available), set `DATABASE_URL=none`.
+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.
 
-**PostgreSQL is the only supported database.** You need to install a PostgreSQL driver separately — [psycopg](https://www.psycopg.org/) is recommended:
+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.
 
-```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
+### 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:
+
+```sh
+PLAIN_POSTGRES_URL=postgresql://app@pooler:6432/myapp
+PLAIN_POSTGRES_MANAGEMENT_URL=postgresql://app@postgres:5432/myapp
 ```
 
+When `POSTGRES_MANAGEMENT_URL` is set, these commands connect through it instead of `POSTGRES_URL`:
+
+- `plain migrations create`, `plain migrations apply`, `plain migrations list`, `plain migrations prune`, `plain migrations squash`
+- `plain postgres sync`, `plain postgres converge`, `plain postgres schema`
+- `plain postgres diagnose`, `plain postgres drop-unknown-tables`, `plain postgres shell`
+
+When it's unset, all commands use `POSTGRES_URL` — there's no behavior change for existing apps.
+
+To route custom code through the management connection, use the `use_management_connection()` context manager:
+
+```python
+from plain.postgres import use_management_connection
+
+with use_management_connection():
+    # Any get_connection() / ORM calls inside this block use POSTGRES_MANAGEMENT_URL.
+    run_custom_schema_change()
+```
+
+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.
+
 ## Querying
 
 Models come with a powerful query API through their [`QuerySet`](./query.py#QuerySet) interface:
@@ -418,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:
@@ -1206,27 +1245,20 @@ These are static, code-level checks that catch issues before you deploy. The `di
 
 ## Settings
 
-Connection settings are configured via `DATABASE_URL` or individual `POSTGRES_*` settings.
-
-When `DATABASE_URL` is set, it is parsed into the individual connection settings automatically. When `DATABASE_URL` is not set, the connection settings are required individually.
-
-Set `DATABASE_URL=none` to explicitly disable the database (e.g. during Docker image builds).
-
-| Setting                                  | Type          | Default | Env var                                        |
-| ---------------------------------------- | ------------- | ------- | ---------------------------------------------- |
-| `POSTGRES_HOST`                          | `str`         | —       | `PLAIN_POSTGRES_HOST`                          |
-| `POSTGRES_PORT`                          | `int \| None` | `None`  | `PLAIN_POSTGRES_PORT`                          |
-| `POSTGRES_DATABASE`                      | `str`         | —       | `PLAIN_POSTGRES_DATABASE`                      |
-| `POSTGRES_USER`                          | `str`         | —       | `PLAIN_POSTGRES_USER`                          |
-| `POSTGRES_PASSWORD`                      | `Secret[str]` | —       | `PLAIN_POSTGRES_PASSWORD`                      |
-| `POSTGRES_CONN_MAX_AGE`                  | `int`         | `600`   | `PLAIN_POSTGRES_CONN_MAX_AGE`                  |
-| `POSTGRES_CONN_HEALTH_CHECKS`            | `bool`        | `True`  | `PLAIN_POSTGRES_CONN_HEALTH_CHECKS`            |
-| `POSTGRES_OPTIONS`                       | `dict`        | `{}`    | —                                              |
-| `POSTGRES_TIME_ZONE`                     | `str \| None` | `None`  | `PLAIN_POSTGRES_TIME_ZONE`                     |
-| `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`      |
-| `POSTGRES_CONVERGENCE_STATEMENT_TIMEOUT` | `str`         | `"3s"`  | `PLAIN_POSTGRES_CONVERGENCE_STATEMENT_TIMEOUT` |
+The connection is configured with a single URL (`POSTGRES_URL`). `DATABASE_URL` is read as a platform-compat fallback. Set the URL to `none` to explicitly disable the database (e.g. during Docker image builds).
+
+| Setting                                  | Type          | Default                 | Env var                                        |
+| ---------------------------------------- | ------------- | ----------------------- | ---------------------------------------------- |
+| `POSTGRES_URL`                           | `Secret[str]` | `$DATABASE_URL` or `""` | `PLAIN_POSTGRES_URL`                           |
+| `POSTGRES_MANAGEMENT_URL`                | `Secret[str]` | `""`                    | `PLAIN_POSTGRES_MANAGEMENT_URL`                |
+| `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`      |
+| `POSTGRES_CONVERGENCE_STATEMENT_TIMEOUT` | `str`         | `"3s"`                  | `PLAIN_POSTGRES_CONVERGENCE_STATEMENT_TIMEOUT` |
 
 See [`default_settings.py`](./default_settings.py) for more details.
 
@@ -1266,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
@@ -1280,4 +1314,9 @@ INSTALLED_PACKAGES = [
     ...
     "plain.postgres",
 ]
+
+MIDDLEWARE = [
+    "plain.postgres.DatabaseConnectionMiddleware",
+    ...
+]
 ```

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

@@ -6,7 +6,8 @@ from . import (
 # Imports that would create circular imports if sorted
 from .base import Model
 from .constraints import CheckConstraint, UniqueConstraint
-from .db import get_connection
+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
@@ -104,6 +105,9 @@ __all__ = [
     "ReverseManyToMany",
     # 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