Deploy PgDog with Postgres

Deploy and Host PgDog with Postgres on Railway

PgDog with Postgres deploys a high-performance PostgreSQL proxy together with two PostgreSQL shards on Railway.

PgDog sits between your application and PostgreSQL, providing connection pooling, query routing, authentication, and horizontal sharding while keeping your application connected through the standard PostgreSQL wire protocol.

About Hosting

This template deploys three services:

Application
    │ PostgreSQL Protocol
    ▼
 PgDog :6432
   ├── PostgreSQL Shard 0
   └── PostgreSQL Shard 1

PgDog acts as the single PostgreSQL endpoint used by your application.

The two PostgreSQL services run as independent shards, while PgDog routes queries based on the configured sharding key.

PgDog uses PostgreSQL's native wire protocol and works with standard clients and drivers such as:

• psql
• Prisma
• Drizzle
• Sequelize
• TypeORM
• Django
• SQLAlchemy
• JDBC
• Go PostgreSQL drivers

PgDog itself does not require a Railway Volume. Persistent database storage is handled by the PostgreSQL services.

Why Deploy

This template is useful when you want to introduce horizontal PostgreSQL scaling without changing the database protocol used by your application.

PgDog provides:

• PostgreSQL connection pooling
• Query routing
• Horizontal sharding
• Centralized database access
• PostgreSQL wire protocol compatibility
• Reduced direct application connections to PostgreSQL
• Independent PostgreSQL shards
• A foundation for larger distributed PostgreSQL architectures

Applications continue connecting through a standard PostgreSQL connection string while PgDog manages the backend topology.

Common Use Cases

• Horizontally sharded PostgreSQL workloads
• Multi-tenant SaaS applications
• Workloads partitioned by tenant or customer
• High-concurrency APIs
• PostgreSQL connection pooling
• Centralized database routing
• Large datasets distributed across multiple PostgreSQL instances
• Preparing applications for future database growth
• Testing distributed PostgreSQL architectures

Dependencies for

This template includes:

• PgDog
• PostgreSQL Shard 0
• PostgreSQL Shard 1

It does not require:

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

The PostgreSQL services use Railway-managed persistent storage and private networking.

Important: TCP, Not HTTP

PgDog 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 instead.

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

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

Environment Variables

PgDog uses environment variables to dynamically generate its native pgdog.toml and users.toml configuration files during startup.

PgDog Settings

Sharding Settings

For example:

SHARDING_COLUMN=tenant_id
SHARDING_DATA_TYPE=bigint

A query such as:

SELECT *
FROM orders
WHERE tenant_id = 123;

can be routed by PgDog to the appropriate PostgreSQL shard.

PostgreSQL Shard Configuration

The template automatically references both Railway PostgreSQL services.

PgDog receives backend settings similar to:

SHARD_0_HOST
SHARD_0_PORT
SHARD_0_DATABASE
SHARD_0_USER
SHARD_0_PASSWORD

SHARD_1_HOST
SHARD_1_PORT
SHARD_1_DATABASE
SHARD_1_USER
SHARD_1_PASSWORD

These values should be populated using Railway reference variables from each PostgreSQL service.

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

Important: Keep Schemas Consistent

PgDog routes queries between shards, but it does not automatically create or synchronize database schemas.

If a sharded table exists on Shard 0, the same compatible schema should also exist on Shard 1.

Example:

CREATE TABLE orders (
    id BIGSERIAL PRIMARY KEY,
    tenant_id BIGINT NOT NULL,
    amount NUMERIC
);

Database migrations should therefore be applied consistently across all shards.

Choosing a Sharding Key

The sharding key determines how data is distributed.

Common examples include:

• tenant_id
• customer_id
• account_id
• user_id
• organization_id

A good sharding key should:

• Exist in common application queries
• Distribute data relatively evenly
• Avoid creating a single hot shard
• Remain stable over time
• Match application access patterns

Supported key types include common values such as:

• bigint
• uuid
• varchar
• vector

The configured type must match the actual PostgreSQL column type.

Connecting to PgDog

Use a standard PostgreSQL connection string:

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

Railway may expose an external TCP port different from the internal PgDog port.

Internally PgDog continues listening on:

6432

The PostgreSQL shards should remain behind Railway private networking unless direct access is specifically required.

PgDog with Postgres vs Single PostgreSQL

A single PostgreSQL instance remains simpler for small and medium workloads.

PgDog with multiple shards becomes useful when database scale, tenant isolation, or distributed data architecture justifies the additional complexity.

Why Railway?

Railway provides a convenient environment for running PgDog together with multiple PostgreSQL services in one project.

Benefits include:

• Managed PostgreSQL services
• Railway-managed persistent storage
• Private service networking
• Environment-based secret management
• PostgreSQL-compatible TCP endpoints
• Independent service scaling
• Centralized deployment logs
• Reproducible multi-service deployments

PgDog with Postgres provides a compact foundation for running horizontally sharded PostgreSQL workloads on Railway.