Deploy PgBouncer with Postgres

Deploy and Host PgBouncer with Postgres on Railway

PgBouncer with Postgres deploys a lightweight PostgreSQL connection pooler together with a Railway PostgreSQL database.

PgBouncer sits between your application and PostgreSQL, reducing connection overhead and allowing many client connections to share a smaller number of backend database connections.

About Hosting

This template deploys two services:

Application
    │ PostgreSQL Protocol
    ▼
PgBouncer :6432
    │ Railway Private Network
    ▼
PostgreSQL :5432

PgBouncer acts as the database endpoint used by your application, while PostgreSQL stores the actual application data.

The PostgreSQL service uses Railway-managed persistent storage. PgBouncer itself does not require a Railway Volume.

PgBouncer works with standard PostgreSQL clients and drivers, including:

• psql
• Prisma
• Drizzle
• Sequelize
• TypeORM
• Django
• SQLAlchemy
• JDBC
• Go PostgreSQL drivers
• Other PostgreSQL-compatible clients

Why Deploy

PostgreSQL creates backend processes for active connections. Applications with high concurrency or many short-lived connections can therefore consume significant database resources.

PgBouncer provides a lightweight pooling layer that can reduce the number of direct PostgreSQL connections.

This template can help:

• Reduce PostgreSQL connection overhead
• Improve connection reuse
• Handle larger numbers of application connections
• Protect PostgreSQL from connection spikes
• Reduce idle backend connections
• Centralize database connectivity
• Separate application credentials from PostgreSQL credentials
• Keep PostgreSQL private behind PgBouncer
• Simplify PostgreSQL infrastructure for APIs and web applications

Applications continue using normal PostgreSQL connection strings and drivers.

Common Use Cases

• High-concurrency APIs
• Web applications
• SaaS applications
• Microservices using PostgreSQL
• Serverless-style workloads
• Reducing PostgreSQL connection pressure
• Protecting database connection limits
• Centralized database access
• Applications with many short-lived connections
• Adding connection pooling to Railway PostgreSQL

Dependencies for

This template includes:

• PgBouncer
• Railway PostgreSQL

It does not require:

• Redis
• MongoDB
• etcd
• RabbitMQ
• Object storage
• A Railway Volume for PgBouncer

PostgreSQL persistence is handled by Railway's PostgreSQL service.

Architecture

                    Railway
                       │
                       ▼
                ┌─────────────┐
                │  PgBouncer  │
                │ TCP :6432   │
                └──────┬──────┘
                       │
                       │ Private Network
                       ▼
                ┌─────────────┐
                │ PostgreSQL  │
                │ TCP :5432   │
                └─────────────┘

Applications should connect to PgBouncer rather than directly to PostgreSQL for normal application traffic.

Important: TCP, Not HTTP

PgBouncer is not a web application.

It listens for PostgreSQL connections on:

TCP 6432

Do not connect through an HTTP URL such as:

https://example.up.railway.app

Use a PostgreSQL client or driver.

For access from outside Railway, configure a Railway TCP Proxy for PgBouncer's internal port 6432.

Applications inside the same Railway project should preferably use Railway private networking.

Environment Variables

PgBouncer generates its native configuration during container startup.

PgBouncer Settings

PostgreSQL Backend Settings

The PostgreSQL backend values are automatically referenced from the Railway PostgreSQL service.

Typical variables include:

POSTGRES_HOST
POSTGRES_PORT
POSTGRES_DATABASE
POSTGRES_USER
POSTGRES_PASSWORD

These values should reference the Railway PostgreSQL service variables such as:

PGHOST
PGPORT
PGDATABASE
PGUSER
PGPASSWORD

Users normally do not need to manually enter PostgreSQL backend credentials.

Client Credentials vs PostgreSQL Credentials

This template separates application credentials from PostgreSQL backend credentials.

Application
    │
    │ PGBOUNCER_USER
    │ PGBOUNCER_PASSWORD
    ▼
PgBouncer
    │
    │ PostgreSQL service credentials
    ▼
PostgreSQL

Applications therefore do not need direct access to the PostgreSQL username and password.

This allows PgBouncer credentials to be rotated independently from the database account.

Pool Modes

PgBouncer supports multiple pooling strategies.

This template uses:

POOL_MODE=transaction

by default.

Transaction pooling usually provides better connection reuse for APIs and web applications.

Applications that depend heavily on session-level PostgreSQL features may need session mode instead.

Connection Pooling

A typical deployment may look like:

100 application connections
          │
          ▼
      PgBouncer
          │
          ▼
20 PostgreSQL connections

The actual number of backend connections depends on:

• DEFAULT_POOL_SIZE
• Application concurrency
• Transaction duration
• Number of users
• Number of databases
• PostgreSQL connection limits

Avoid configuring the pool to consume the entire PostgreSQL connection limit.

Keep spare capacity for:

• Administration
• Database migrations
• Monitoring
• Maintenance
• Background jobs
• Other database consumers

Connecting to PgBouncer

Use a standard PostgreSQL connection string:

postgresql://PGBOUNCER_USER:PGBOUNCER_PASSWORD@TCP_HOST:TCP_PORT/PGBOUNCER_DATABASE

Example:

postgresql://pgbouncer:password@your-tcp-host:12345/app

Railway may expose an external TCP port different from PgBouncer's internal port.

PgBouncer continues listening internally on:

6432

The PostgreSQL service itself should normally remain private.

PgBouncer with Postgres vs Direct PostgreSQL

Direct PostgreSQL remains simpler for applications with low and predictable connection usage.

PgBouncer becomes more valuable as application concurrency and connection pressure increase.

Why Railway?

Railway provides a convenient environment for running PgBouncer together with PostgreSQL in a single project.

Benefits include:

• Railway-managed PostgreSQL
• Persistent database storage
• Private service networking
• Environment-based secret management
• PostgreSQL-compatible TCP endpoints
• Centralized logs
• Independent PgBouncer scaling
• Reproducible multi-service deployments
• Simple integration between PgBouncer and PostgreSQL

PgBouncer with Postgres provides a compact PostgreSQL stack with built-in connection pooling while keeping the database architecture simple.