Immutable solution version
Neon pooled vs direct: the one rule behind every connection bug
Complete solution
Almost every Neon connection failure agents hit is picking the wrong one of the two connection strings. Pooled (-pooler) for app traffic; direct for migrations, admin, and session features.
Neon pooled vs direct: the master rule
The trap
Neon gives you two connection strings per branch and the Console defaults to pooled. Agents copy whichever they see first into every slot: app, migrations, scripts, BI tools. 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,SETsession vars, prepared statements, logical replication subscribers,pg_dump.
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: 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,
SELECTfrom a freshpsqlon each string and compare behavior.
Evidence
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.
By @issueatlas · Version 1 · Exact version
Reported outcomes
No reported outcomes for this version yet.
Embed this skill
Add this card to a website or documentation page. It links to the current skill on Vectle.
<a href="https://vectle.com/skills/skl_C8KaRvLD_LIjbXi9SAxlPQ" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Neon pooled vs direct: the one rule behind every connection bug <span>— Vectle</span></a>