Neon pooled vs direct: the one rule behind every connection bug

TL;DR: Agents copy whichever they see first into every slot: app, migrations, scripts, BI tools. # Neon pooled vs direct: the master rule ## The trap Neon gives you two connection strings per branch and the Console defaults to pooled. Half of Neon's connection failure modes are just this choice made wrong. ## The rule - Pooled (hostname contains

Fix

1. Agents copy whichever they see first into every slot: app, migrations, scripts, BI tools. Expected: this specific failure stops.

2. SET. Expected: this specific failure stops.

3. Neon's pooling docs list exactly what transaction-mode pooling does not support: SET/RESET, LISTEN/NOTIFY, WITH HOLD cursors, PREPARE/DEALLOCATE, qualifying temp tables, LOAD, session-level advisory locks. ## How to tell which one you have Look at the hostname:. Expected: this specific failure stops.

Details

Half of Neon's connection failure modes are just this choice made wrong. ## The rule - Pooled (hostname contains -pooler ): application request traffic, serverless functions, anything with high concurrency and short transactions. PgBouncer multiplexes up to 10,000 client connections. - Direct (no -pooler ): migrations, schema changes, seeds, admin scripts, LISTEN / NOTIFY , session vars, prepared statements, logical replication subscribers, pg_dump . ep-xyz-pooler.us-east-2.aws.neon.tech is pooled; without -pooler it is direct. If a query works from psql (direct) and fails from your app, compare the two strings before debugging anything else. ## Checklist - App runtime env vars: pooled. CI migrate jobs: direct. - Framework adapters (Prisma adapter, Drizzle, Kysely): pooled for the client, direct for the migration runner. - Logical replication and pg_dump / pg_restore : always direct. - When in doubt, SELECT from a fresh psql on each string and compare behavior.

When to use

You hit exactly this: Neon pooled vs direct: the one rule behind every connection bug in Neon pooled vs direct.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Neon pooled vs direct.

Edge cases

• # Neon pooled vs direct: the master rule ## The trap Neon gives you two connection strings per branch and the Console defaults to pooled.

Neon's connect docs (verified live 2026-09-26): pooled connections via -pooler hostname are the Console default; PgBouncer in transaction mode; the pooling guide lists the unsupported session features and the 10,000-client limit.