plain.postgres 0.97.0__tar.gz → 0.99.0__tar.gz

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

@@ -1,9 +1,25 @@
+Metadata-Version: 2.4
+Name: plain.postgres
+Version: 0.99.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:
@@ -1170,37 +1198,110 @@ graph TB
 
 ## Diagnostics
 
-You can run health checks against your database to find issues like missing indexes, redundant indexes, and configuration problems.
+Run health checks against your database. `diagnose` is designed to produce
+only actionable findings — every warning has a copy-paste fix or specific
+resource to investigate, and noisy one-off signals (hit ratios, XID age) are
+surfaced as informational context rather than as warnings.
 
 ```bash
 uv run plain postgres diagnose
 ```
 
-Use `--json` for structured output (useful for scripting and AI agents):
+Output modes:
 
 ```bash
-uv run plain postgres diagnose --json
+uv run plain postgres diagnose --json      # structured output for scripts/agents
+uv run plain postgres diagnose --verbose   # expand to show every check, including passing
+uv run plain postgres diagnose --all       # include findings on installed-package tables
 ```
 
-Use `--all` to include issues in installed packages (by default, only your app's issues are shown):
+### Guiding principle
 
-```bash
-uv run plain postgres diagnose --all
-```
+`diagnose` emits a **warning** only if the remedy fits in the user's codebase
+or is an app-level action they own. If the remedy is "run SQL against your
+DB" or "configure your Postgres server," the check emits **operational
+context** or an **informational number**, not a warning. This keeps the
+warning surface high-trust — every warning has an edit-to-make — and prevents
+`diagnose` from bleeding into DB-host concerns.
+
+### Warning-tier checks
+
+Things the user can fix by editing code + running `plain postgres sync`, or
+app-level incidents they must act on.
+
+**Structural — always-real; a fix is possible immediately.**
+
+| Check                   | What it finds                                                                                       | Severity         |
+| ----------------------- | --------------------------------------------------------------------------------------------------- | ---------------- |
+| **Invalid indexes**     | Broken indexes from failed `CREATE INDEX CONCURRENTLY` — maintained on writes, never used for reads | Warning          |
+| **Duplicate indexes**   | One index is a column-prefix of another on the same table                                           | Warning          |
+| **Missing FK indexes**  | Foreign key columns without any index coverage                                                      | Warning          |
+| **Sequence exhaustion** | Identity sequences approaching their type max                                                       | Warning/Critical |
 
-### Checks
+**Cumulative — depends on stats since the last reset.**
 
-| Check                   | What it finds                                                                                                                                                  | Severity         |
-| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------- |
-| **Invalid indexes**     | Broken indexes from failed `CREATE INDEX CONCURRENTLY` — maintained on writes, never used for reads                                                            | Warning          |
-| **Duplicate indexes**   | Indexes where one is a column-prefix of another on the same table (e.g., an auto FK index that's redundant with a composite index)                             | Warning          |
-| **Unused indexes**      | Indexes with zero scans since stats reset (>1 MB). Excludes unique indexes, constraint-backing indexes, and indexes that are the sole coverage for a FK column | Warning          |
-| **Missing FK indexes**  | Foreign key columns without any index coverage — parent DELETE/UPDATE operations will sequentially scan the child table                                        | Warning          |
-| **Sequence exhaustion** | Identity sequences approaching their type max (>50% warning, >90% critical)                                                                                    | Warning/Critical |
-| **XID wraparound**      | Transaction ID age approaching the 2 billion wraparound limit (>25% warning, >40% critical)                                                                    | Warning/Critical |
-| **Cache hit ratio**     | Heap buffer hit ratio below 98.5% — indicates insufficient `shared_buffers` or RAM                                                                             | Warning          |
-| **Index hit ratio**     | Index buffer hit ratio below 98.5%                                                                                                                             | Warning          |
-| **Vacuum health**       | Tables with significant dead tuple accumulation (>10% of live rows) where autovacuum may be falling behind                                                     | Warning          |
+| Check                        | What it finds                                                                                                        | Severity |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------- | -------- |
+| **Unused indexes**           | Indexes with zero scans since stats reset (>1 MB). Excludes unique, constraint-backing, and sole-FK-coverage indexes | Warning  |
+| **Missing index candidates** | Tables with seq-scan activity suggesting a missing index. Includes top contributing queries from pg_stat_statements  | Warning  |
+
+**Snapshot — point-in-time incidents.**
+
+| Check                        | What it finds                                                           | Severity         |
+| ---------------------------- | ----------------------------------------------------------------------- | ---------------- |
+| **Long-running connections** | Client backends idle-in-transaction or running a query past a threshold | Warning/Critical |
+| **Blocking queries**         | Queries currently blocking other queries via held locks                 | Warning/Critical |
+
+### Operational-context findings
+
+These are facts about the database whose remedies live outside Plain today
+(`ANALYZE`, `VACUUM`, `REINDEX`, autovacuum server tuning). They're surfaced
+so agents and humans can interpret findings correctly, but the CLI renders
+them as context rather than alarming warnings — the user can't express the
+fix in their model code. (In JSON output each finding still carries
+`status: "warning"`; the `tier: "operational"` field is what distinguishes
+it.) Each finding still carries the exact SQL in its suggestion for anyone
+who wants to act.
+
+| Finding             | What it reports                                                                  |
+| ------------------- | -------------------------------------------------------------------------------- |
+| **Stats freshness** | Tables whose planner statistics are missing (never analyzed) or stale            |
+| **Vacuum health**   | Tables with >10% dead tuples                                                     |
+| **Index bloat**     | btree indexes with significant estimated wasted space (≥10 MB, ioguix estimator) |
+
+If a future release exposes per-table autovacuum / fillfactor parameters in
+`model_options` (see the `postgres-model-storage-parameters` arc), these
+findings can graduate back to the warning tier — because the remedy will be
+expressible in code.
+
+### Informational context
+
+Alongside checks, `diagnose` surfaces context an agent or human may want to read but that isn't actionable on its own:
+
+- **Cache hit ratio**, **Index hit ratio** — buffer hit rates (volatile after restart; not a warning in themselves)
+- **XID wraparound** — transaction ID age as a percent of the 2B limit. Autovacuum usually keeps this low; long-running transactions can block the freeze process even on managed Postgres
+- **Connection saturation** — active/max connections at this moment
+- **Stats reset** — when cumulative stats were last reset (affects the confidence of operational checks)
+- **pg_stat_statements** — whether the extension is installed
+
+### Cross-check caveats
+
+Findings whose confidence depends on another check are tagged with a caveat. For example:
+
+- `unused_indexes` on a table flagged by `stats_freshness` → caveat: "this table has never been analyzed — the planner may not yet use this index; re-check after running ANALYZE"
+- `missing_index_candidates` on a never-analyzed table → caveat: "planner statistics are absent — running ANALYZE may change query plans and make this finding moot"
+
+This prevents false confidence: dropping an "unused" index on a never-analyzed table is often the wrong move.
+
+### Model-aware suggestions
+
+Findings on app-owned tables include the Plain model class and its source file. Suggestions reference the exact edit point:
+
+```
+  app/processing/models.py :: ProcessingResult — Add an Index on ["is_processing"] to the model, then run plain postgres sync
+```
+
+This closes the loop from detection to fix — agents can draft the model edit without guessing.
 
 ### App vs package issues
 
@@ -1220,6 +1321,8 @@ heroku run -a your-app "plain postgres diagnose --json"
 
 The `--json` flag must be quoted so Heroku passes it through to the command.
 
+Cumulative-stat checks (`stats_freshness`, `vacuum_health`, `unused_indexes`, `missing_index_candidates`, `index_bloat`) need cumulative stat history after the last reset to be reliable. Check the `stats_reset` informational to see how much history you have. (Note: this list spans both the warning and operational tiers — the common thread is that all five depend on counters that `pg_stat_reset()` wipes.)
+
 ### Preflight checks
 
 Two related checks run automatically during `uv run plain preflight` (and `uv run plain check`):
@@ -1229,6 +1332,12 @@ Two related checks run automatically during `uv run plain preflight` (and `uv ru
 
 These are static, code-level checks that catch issues before you deploy. The `diagnose` command complements them with runtime stats from the actual database.
 
+### What diagnose deliberately doesn't do
+
+- **LLM-powered column recommendations for missing indexes** — `missing_index_candidates` shows the culprit queries and lets you decide. For precise column-level suggestions, use a platform tool (PlanetScale Insights, Dexter, pg_qualstats + hypopg).
+- **Historical trending** — `diagnose` is stateless; it reports on the current state of cumulative stats. Continuous monitoring is out of scope.
+- **Niche server checks** (WAL bloat, replication slot age, etc.) — better covered by your Postgres provider's monitoring or a dedicated tool; users on self-hosted setups that need them typically have their own tooling.
+
 ## Settings
 
 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).
@@ -1237,8 +1346,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 +1393,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 +1409,9 @@ INSTALLED_PACKAGES = [
     ...
     "plain.postgres",
 ]
+
+MIDDLEWARE = [
+    "plain.postgres.DatabaseConnectionMiddleware",
+    ...
+]
 ```

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

@@ -1,5 +1,68 @@
 # plain-postgres changelog
 
+## [0.99.0](https://github.com/dropseed/plain/releases/plain-postgres@0.99.0) (2026-04-23)
+
+### What's changed
+
+- **Reworked `plain postgres diagnose` around tiered findings.** Warnings are now reserved for things the user can fix by editing model code or taking an app-level action — every warning carries a copy-paste fix or a model-file pointer (`app/path.py :: ModelName`). Noisy one-off signals (cache/index hit ratios, XID wraparound, connection saturation, pg_stat_statements availability, stats reset age) render as **informational context**; DB-state facts whose remedies live outside Plain (stats freshness, vacuum health, index bloat) render as **operational context** instead of warnings. Added `--verbose` to expand every check, and `--all` still includes installed-package tables. ([26abb6cbc075](https://github.com/dropseed/plain/commit/26abb6cbc075))
+- **New diagnostic checks:** `stats_freshness` (uses `pg_class.reltuples` so it survives `pg_stat_reset`), `index_bloat` (ioguix btree estimator, public schema only), `missing_index_candidates` (seq-scan heuristics with per-query drill-down from `pg_stat_statements`), `blocking_queries` (wait age from `pg_locks.waitstart`, PG 14+), and `long_running_connections` (xact age for idle-in-transaction). Findings include **cross-check caveats** — e.g. an `unused_indexes` finding on a table that's also flagged by `stats_freshness` or `vacuum_health` now carries a warning that dropping the index may be premature. ([26abb6cbc075](https://github.com/dropseed/plain/commit/26abb6cbc075))
+- **Permission-safe probes.** Checks that may hit permission errors (`pg_stat_statements`, `pg_stat_activity`, `pg_locks`) now wrap their queries in `cursor.connection.transaction()` so a failure rolls back cleanly in either autocommit or transaction mode without cascade-failing later checks. ([26abb6cbc075](https://github.com/dropseed/plain/commit/26abb6cbc075))
+- **Refactored internals.** The 1800+ line `introspection/health.py` split into an `introspection/health/` package along natural seams (types, ownership, context, helpers, checks grouped by `structural`/`cumulative`/`snapshot`, and a runner). Public re-exports are unchanged. ([26abb6cbc075](https://github.com/dropseed/plain/commit/26abb6cbc075))
+- Adapter annotations use `Response` after plain 0.135.0 merged `ResponseBase` into `Response`. ([f5007281d7fa](https://github.com/dropseed/plain/commit/f5007281d7fa))
+
+### Upgrade instructions
+
+- Requires `plain>=0.135.0`.
+- No code changes required. If you parse `plain postgres diagnose --json`, note the new `tier` field on each finding (`"structural"`, `"cumulative"`, `"snapshot"`, or `"operational"`) — operational findings still carry `status: "warning"` but the CLI renders them as context rather than as alarming warnings.
+
+## [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