--- title: "Deploy PgDog" description: "Fast PostgreSQL proxy with connection pooling and query routing." category: "Storage" url: https://railway.com/deploy/pgdog --- # Deploy PgDog Fast PostgreSQL proxy with connection pooling and query routing. **[Deploy PgDog on Railway](https://railway.com/template/pgdog)** - **Creator:** INF Labs - **Category:** Storage ## Template content ### pgdog https://pgdog.dev/assets/images/logo2.png - **Image:** ghcr.io/pgdogdev/pgdog:v0.1.48 - **Start command:** `/bin/sh -c 'printf "%s\n" "[general]" "host = \"0.0.0.0\"" "port = ${PGDOG_PORT}" "default_pool_size = ${PGDOG_POOL_SIZE}" "" "[[databases]]" "name = \"${PGDOG_DATABASE}\"" "host = \"${POSTGRES_HOST}\"" "port = ${POSTGRES_PORT}" "database_name = \"${POSTGRES_DATABASE}\"" > /pgdog/pgdog.toml && printf "%s\n" "[[users]]" "name = \"${PGDOG_USER}\"" "database = \"${PGDOG_DATABASE}\"" "password = \"${PGDOG_PASSWORD}\"" "server_user = \"${POSTGRES_USER}\"" "server_password = \"${POSTGRES_PASSWORD}\"" "pool_size = ${PGDOG_POOL_SIZE}" > /pgdog/users.toml && exec /usr/local/bin/pgdog --config /pgdog/pgdog.toml --users /pgdog/users.toml'` ## Documentation # 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: ```text 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: ```text TCP 6432 ``` Do not connect through an HTTP URL such as: ```text 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 | Variable | Description | Default | | ----------------- | -------------------------------------------------- | ------- | | `PGDOG_PORT` | Incoming PostgreSQL TCP port | `6432` | | `PGDOG_DATABASE` | Virtual database name exposed to clients | — | | `PGDOG_USER` | Username applications use when connecting to PgDog | — | | `PGDOG_PASSWORD` | Password applications use when connecting to PgDog | — | | `PGDOG_POOL_SIZE` | Maximum backend PostgreSQL connections | `10` | `PGDOG_DATABASE` can be different from the actual backend PostgreSQL database. For example: ```text PGDOG_DATABASE=app POSTGRES_DATABASE=production ``` Applications connect to: ```text app ``` while PgDog connects to: ```text production ``` ### PostgreSQL Backend Settings | Variable | Description | Default | | ------------------- | --------------------------- | ------- | | `POSTGRES_HOST` | PostgreSQL hostname | — | | `POSTGRES_PORT` | PostgreSQL port | `5432` | | `POSTGRES_DATABASE` | Actual PostgreSQL database | — | | `POSTGRES_USER` | Backend PostgreSQL username | — | | `POSTGRES_PASSWORD` | Backend PostgreSQL password | — | 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. ```text 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: ```text postgresql://PGDOG_USER:PGDOG_PASSWORD@TCP_HOST:TCP_PORT/PGDOG_DATABASE ``` Example: ```text postgresql://myapp:password@your-tcp-host:12345/app ``` Railway may expose a different external TCP port while PgDog continues listening internally on: ```text 6432 ``` Always use the TCP hostname and port shown by Railway when connecting externally. ## Configuration Files PgDog normally uses two configuration files: ```text 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 | Feature | PgDog | PgBouncer | | ----------------------------- | ----: | --------: | | PostgreSQL connection pooling | ✅ | ✅ | | Transaction pooling | ✅ | ✅ | | Session pooling | ✅ | ✅ | | PostgreSQL wire protocol | ✅ | ✅ | | Built with Rust | ✅ | ❌ | | Query parsing and routing | ✅ | ❌ | | Native sharding capabilities | ✅ | ❌ | | Read/write routing | ✅ | Limited | | Multi-shard architecture | ✅ | ❌ | 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. ## Similar templates - [Garage S3 Storage](https://railway.com/deploy/garage-s3-storage) — Ultra-light S3 server: fast, open-source, plug-and-play. - [Redis](https://railway.com/deploy/redis-1) — Self Host Latest Redis with Railway - [EasyImg](https://railway.com/deploy/easyimg) — Simple self-hostable Nuxt.js personal image hosting system. Open this page in a browser: https://railway.com/deploy/pgdog