fix(db): recover prepared statements that a pooler or schema change invalidates

With DATABASE_PREPARED_STATEMENTS=true behind a transaction-mode pooler
(PgBouncer 1.22+, Neon -pooler hosts), a migration that changes a column
type makes the pooler's shared prepared statement fail for every client and
process with "cached plan must not change result type", and postgres.js then
caches a statement without columns, so later executions on that connection
throw a TypeError even after the schema is fixed.

When a prepared statement fails with 26000, 42P05, or that 0A000 error, stop
preparing its text for the rest of the process (decided at execution, so
queued queries see it), retry pooled statements once unprepared, and retry a
transaction whose first statement failed. Cap prepared texts at 1,000 per
client and skip texts over 8 KB. Expose the counts through
preparedStatementStats. Behaviour with the flag unset or false is unchanged.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DottaandClaude Opus 5.5 committed 2026-11-14 21:07:41 -06:00
1 parent 8adf0a463a
commit f9b5ddc93b
6 files changed
+241 -16

No files matched your search

+4
View File
@@ -68,6 +68,10 @@ queries inside transactions and reserved or dedicated connections. Check the
provider's configuration before you enable it. Preparation caches statement
metadata, not query results. Unset preserves the existing ORM behavior and the
driver default for tagged SQL. Explicit per-query options still apply.
Each database client prepares at most 1,000 distinct statements and skips
statements longer than 8 KB. If a prepared statement fails because the pooler's copy is
stale after a schema change or was lost, Paperclip stops preparing that
statement and retries it once unprepared.
Related optional client tuning: `DATABASE_POOL_MAX`, `DATABASE_IDLE_TIMEOUT_SECONDS`, `DATABASE_CONNECT_TIMEOUT_SECONDS`, `DATABASE_MAX_LIFETIME_SECONDS`, `DATABASE_APPLICATION_NAME`. Driver defaults apply when unset, except that idle pooled connections close after 60 seconds (`DATABASE_IDLE_TIMEOUT_SECONDS=0` keeps them open) and the pool reports `application_name=paperclip`. See [Connection pool settings](#connection-pool-settings).