Deploy PgDog

Deploy and Host PgDog on Railway

PgDog is a high-performance PostgreSQL proxy and connection pooler built in Rust. It sits between applications and PostgreSQL to manage connections, authentication, transaction pooling, routing, load balancing, and advanced database architectures.

This Railway template deploys PgDog as a standalone service connected to an existing PostgreSQL database hosted on Railway or another provider.

About Hosting

Hosting PgDog on Railway adds a dedicated PostgreSQL proxy and connection-pooling layer between your applications and an existing PostgreSQL database.

The architecture is simple:

Application
    │ PostgreSQL Protocol
    ▼
 PgDog :6432
    │ PostgreSQL Protocol
    ▼
Existing PostgreSQL

PgDog uses PostgreSQL's native wire protocol and works with standard clients and drivers, including:

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

This template deploys PgDog only. PostgreSQL itself is not included.

You can connect PgDog to PostgreSQL hosted on:

• Railway PostgreSQL
• Amazon RDS
• Amazon Aurora PostgreSQL
• Google Cloud SQL
• Azure Database for PostgreSQL
• Supabase
• Neon
• Self-hosted PostgreSQL
• Other PostgreSQL-compatible providers

Backend connection details are supplied through environment variables during deployment.

Why Deploy

Deploying PgDog in front of PostgreSQL can reduce the number of direct database connections created by applications and provide a centralized database access layer.

PgDog can help you:

• Reduce PostgreSQL connection pressure
• Pool many client connections into fewer backend connections
• Separate application credentials from PostgreSQL credentials
• Centralize PostgreSQL traffic through one proxy
• Add transaction pooling
• Prepare for future read/write routing
• Prepare for PostgreSQL replicas
• Build toward horizontally sharded PostgreSQL architectures
• Scale the proxy independently from the database
• Keep applications using standard PostgreSQL drivers

PgDog is especially useful when applications create many concurrent connections or when you expect the PostgreSQL architecture to become more complex over time.

Common Use Cases

• PostgreSQL connection pooling
• Reducing direct PostgreSQL connections
• Handling application connection spikes
• Centralized PostgreSQL authentication
• Database proxying
• Transaction pooling
• Protecting PostgreSQL connection capacity
• Separating client and backend credentials
• Connecting multiple applications through one PostgreSQL gateway
• Preparing for read replicas
• Preparing for read/write query routing
• Preparing for PostgreSQL sharding
• Adding a PostgreSQL infrastructure layer to Railway applications

Dependencies for

PgDog requires an existing PostgreSQL-compatible database.

Required dependencies and configuration:

• Existing PostgreSQL server
• PostgreSQL hostname
• PostgreSQL port
• PostgreSQL database name
• Valid PostgreSQL username
• Valid PostgreSQL password
• Network connectivity between PgDog and PostgreSQL

PgDog does not require:

• Redis
• MongoDB
• etcd
• RabbitMQ
• Object storage
• Railway Volume

PgDog does not store database data itself. Persistence remains the responsibility of the PostgreSQL backend.

Important: PostgreSQL Is Not Included

This template deploys PgDog only.

It does not provision or contain PostgreSQL.

Before deploying, make sure you already have a PostgreSQL database and valid connection credentials.

Important: TCP, Not HTTP

PgDog is not a web application.

It listens for PostgreSQL connections using:

TCP 6432

Do not connect through an HTTP URL such as:

https://example.up.railway.app

Use a PostgreSQL client instead.

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

Applications running inside the same Railway project should preferably communicate with PgDog through Railway private networking.

Environment Variables

This template uses environment variables to dynamically generate PgDog's native pgdog.toml and users.toml configuration files when the container starts.

PgDog does not directly use these template environment variables. They are translated into its native TOML configuration during startup.

PgDog Settings

PGDOG_DATABASE can be different from the actual backend PostgreSQL database.

For example:

PGDOG_DATABASE=app
POSTGRES_DATABASE=production

Applications connect to:

app

while PgDog connects to:

production

PostgreSQL Backend Settings

Keep PGDOG_POOL_SIZE safely below the PostgreSQL server's total connection limit.

PostgreSQL should retain connection capacity for:

• Database administration
• Migrations
• Monitoring
• Maintenance
• Background workers
• Other services

Client Credentials vs PostgreSQL Credentials

PgDog supports separate credentials for applications and the upstream PostgreSQL server.

Application
    │
    │ PGDOG_USER
    │ PGDOG_PASSWORD
    ▼
  PgDog
    │
    │ POSTGRES_USER
    │ POSTGRES_PASSWORD
    ▼
PostgreSQL

This means applications do not need direct access to your PostgreSQL credentials.

PgDog client credentials can also be rotated independently from the backend PostgreSQL account.

Connecting to PgDog

Connect using a normal PostgreSQL connection string:

postgresql://PGDOG_USER:PGDOG_PASSWORD@TCP_HOST:TCP_PORT/PGDOG_DATABASE

Example:

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

Railway may expose a different external TCP port while PgDog continues listening internally on:

6432

Always use the TCP hostname and port shown by Railway when connecting externally.

Configuration Files

PgDog normally uses two configuration files:

pgdog.toml
users.toml

pgdog.toml contains:

• Listener configuration
• PostgreSQL backend configuration
• Connection pool settings
• Routing settings

users.toml contains:

• Client users
• Authentication credentials
• Database mappings
• Backend PostgreSQL credential overrides

This Railway template generates both files during container startup from environment variables.

Because configuration is reconstructed during startup, persistent storage is not required.

PgDog vs PgBouncer

PgBouncer remains an excellent lightweight PostgreSQL pooler.

PgDog is particularly interesting when you need connection pooling today while retaining a path toward advanced routing, replicas, or horizontally sharded PostgreSQL architectures later.

Troubleshooting

Application Cannot Connect

Check that:

• The application is using PostgreSQL protocol instead of HTTP.
• The correct TCP hostname is configured.
• The correct Railway external TCP port is configured.
• TCP Proxy is enabled when connecting externally.
• PgDog is listening internally on 6432.
• PGDOG_USER is correct.
• PGDOG_PASSWORD is correct.
• The requested database matches PGDOG_DATABASE.

PgDog Cannot Connect to PostgreSQL

Check that:

• POSTGRES_HOST is correct.
• POSTGRES_PORT is correct.
• POSTGRES_DATABASE exists.
• POSTGRES_USER is valid.
• POSTGRES_PASSWORD is valid.
• The PostgreSQL provider allows connections from Railway.
• Required TLS settings are satisfied.
• Private hostnames are resolvable from the PgDog service.

Why Railway?

Railway provides a convenient platform for running PgDog alongside applications and PostgreSQL infrastructure.

Benefits include:

• Dedicated PgDog service
• Private service networking
• Environment-based secret management
• PostgreSQL-compatible TCP endpoints
• Independent service scaling
• Reproducible configuration
• Centralized logs
• Easy integration with Railway PostgreSQL
• Support for PostgreSQL providers outside Railway

PgDog acts as a lightweight PostgreSQL infrastructure layer between your applications and an existing PostgreSQL database.