Connection Pooling in PostgreSQL: Why Your App Needs It

Connection pooling in Postgres: why your app needs it

A PostgreSQL connection isn't free — each one costs real memory, and there's a hard limit. Ignore that and a traffic spike takes your app down with "too many connections." Here's what a pooler does, why WattleDB gives you two connection strings, and exactly which one to use where.

Guide · 7 min read · Updated July 2026

Most people meet connection pooling the hard way: the app runs fine in testing, then falls over in production with FATAL: sorry, too many clients already. The database didn't run out of CPU or disk — it ran out of connections. Pooling is the fix, and on WattleDB it's already set up for you. This explains what's happening and how to use it.

Which connection string, at a glance

DATABASE_URL — pooled (PgBouncer, transaction mode). Your app, your API routes, serverless functions.
DIRECT_URL — direct session. Migrations, psql, long-running jobs, anything using session state.
Both are TLS-encrypted Australian endpoints — keep sslmode=require.

Connections are expensive

In PostgreSQL, every client connection is backed by its own server process with its own memory. A few dozen is fine; a few thousand is not. Each database has a max_connections ceiling, and once you hit it, new connections are refused — even though the server has plenty of CPU left. The problem isn't load, it's concurrency of connections.

What a pooler does

A connection pooler like PgBouncer sits between your app and Postgres. It keeps a small pool of real database connections open and lends them out to incoming clients. In transaction mode — what WattleDB's pooled endpoint uses — a real connection is assigned only for the duration of a single transaction, then returned to the pool. Thousands of clients can share a handful of backend connections, because at any instant only a few are mid-transaction.

That's why the pooled DATABASE_URL is the right default for your application: it absorbs spikes that would otherwise exhaust the database.

When you need the direct connection

Transaction-mode pooling has one trade-off: because a connection isn't dedicated to you between transactions, anything that relies on session state won't work through the pooler. That includes:

Schema migrations (they create objects and may hold long transactions).
Prepared statements that persist across calls, and LISTEN/NOTIFY.
Session-level SET commands, advisory locks, and bulk imports.

For those, use DIRECT_URL — a direct session connection that bypasses the pooler. The usual pattern: your app's runtime uses DATABASE_URL, and your migration tool uses DIRECT_URL.

The serverless trap

Serverless and edge functions make the connection problem worse: each invocation can spin up its own instance, and each instance wants its own connection. A burst of traffic becomes a burst of connections, and you hit the ceiling fast. This is exactly what transaction-mode pooling is for — point your serverless functions at DATABASE_URL and the pool soaks up the churn.

One gotcha: with some drivers you must disable prepared statements when going through a transaction pooler (for example, prepare: false in postgres.js). Prepared statements assume a stable session, which transaction mode doesn't guarantee.

Rules of thumb

App, API and serverless code → DATABASE_URL.
Migrations, psql, long jobs, LISTEN/NOTIFY → DIRECT_URL.
Seeing prepared-statement errors through the pooler? Disable prepared statements on the pooled connection.
Both strings are in the console under Connection, and both stay inside Australia.

Connection pooling questions

What is connection pooling in PostgreSQL?

Connection pooling puts a proxy (like PgBouncer) between your app and the database that keeps a small set of real connections open and shares them across many clients. Because each PostgreSQL connection costs memory and there's a hard limit, pooling lets thousands of clients run against a handful of backend connections without exhausting the database.

What is transaction-mode pooling?

In transaction mode, the pooler assigns a real database connection to a client only for the duration of a single transaction, then returns it to the pool. This gives the highest concurrency, which is why WattleDB's pooled DATABASE_URL uses it — but it means features that depend on session state (some prepared statements, LISTEN/NOTIFY, session SETs) must use the direct connection instead.

Why does WattleDB give me two connection strings?

DATABASE_URL is the pooled endpoint for your application and serverless functions — it handles connection churn under load. DIRECT_URL is a direct session connection for migrations, psql and long-running jobs that need stable session state. Using each for its intended job avoids both connection exhaustion and pooler-related errors.

Why do I get 'too many connections' errors on serverless?

Each serverless invocation tends to open its own database connection, so a traffic burst becomes a connection burst that hits PostgreSQL's limit. Pointing your functions at the pooled DATABASE_URL fixes it, because the pooler shares a small backend pool across all those short-lived clients. You may also need to disable prepared statements on the pooled connection.

Connection pooling in Postgres: why your app needs it

Which connection string, at a glance

Connections are expensive

What a pooler does

When you need the direct connection

The serverless trap

Rules of thumb

Connection pooling questions

Connect Prisma & Drizzle to WattleDB →

Build a SaaS fast: schema to a live REST API →

Pooled and direct,
both onshore.

Connection pooling in Postgres: why your app needs it

Which connection string, at a glance

Connections are expensive

What a pooler does

When you need the direct connection

The serverless trap

Rules of thumb

Connection pooling questions

Connect Prisma & Drizzle to WattleDB →

Build a SaaS fast: schema to a live REST API →

Pooled and direct,both onshore.

Pooled and direct,
both onshore.