PgBouncer

PgBouncer sits between your application and PostgreSQL, multiplexing hundreds of app connections over a small number of database connections. This reduces connection overhead and prevents your database from running out of connections under load.

When to use PgBouncer

• Your app opens many concurrent connections (e.g. serverless functions, high-traffic APIs)
• You’re seeing “too many connections” errors from PostgreSQL
• You want to improve connection setup latency — pooled connections are reused instead of created fresh
• You’re using a framework that opens a connection per request (e.g. serverless Next.js API routes)

Adding PgBouncer

1. Open your project and click Add Service
2. Search for or select PgBouncer
3. Click Add

PgBouncer automatically connects to your existing PostgreSQL service. No configuration needed — it reads the database credentials from the project’s environment variables.

Connecting through PgBouncer

When you add PgBouncer, Stackpad auto-injects these variables into your web services:

Variable	Description	Example
POOLER_URL	Full connection string via PgBouncer	postgresql://user:pass@pgbouncer:6432/db
POOLER_HOST	PgBouncer hostname	pgbouncer
POOLER_PORT	PgBouncer port	6432

Update your application to use POOLER_URL instead of DATABASE_URL for pooled connections:

import { Pool } from 'pg';

// Use POOLER_URL for connection pooling, fall back to direct connection
const pool = new Pool({
  connectionString: process.env.POOLER_URL ?? process.env.DATABASE_URL,
});

// Drizzle ORM
import { drizzle } from 'drizzle-orm/node-postgres';
const db = drizzle(process.env.POOLER_URL!);

Caution

Keep DATABASE_URL available for operations that need a direct connection — migrations, LISTEN/NOTIFY, prepared statements, and advisory locks don’t work well through a connection pooler in transaction mode.

How it works

PgBouncer runs in transaction pooling mode by default:

• A database connection is assigned to a client only for the duration of a transaction
• Between transactions, the connection is returned to the pool
• This allows hundreds of application connections to share a small pool of database connections

Technical details

Setting	Value
Image	edoburu/pgbouncer:1.24.0
Port	6432
Default pool mode	Transaction
Resources	64 MB RAM, 0.1 CPU

Public access

PgBouncer supports public access — connect from your local machine or external tools through the pooler instead of directly to PostgreSQL. Enable it in the PgBouncer service settings.

What’s next?

• PostgreSQL — manage your PostgreSQL database
• Connecting services — how service-to-service networking works
• Horizontal scaling — scale your web app to handle more traffic