Self-hosted service
pgdogdev/pgdog avatar
pgdogdev/pgdog

PgDog: a Postgres proxy that reads the query before it picks a host

PostgreSQL connection pooler, load balancer and database sharder.

5,614 stars314 forksRustAGPL-3.0

At a glance

What is it?
PgDog puts an application layer proxy in front of PostgreSQL, pooling connections, sending reads and writes to different hosts by parsing each statement, and watching replication LSNs. The query parser is what separates it from PgBouncer, and it is also a pinned git dependency you take on with every build.
Who is it for?
PgDog is worth a trial when one endpoint has to serve both a primary and its replicas and you want pooling in the same process. Before you commit, read the docs site for configuration details, and remember that PgDog will not promote a replica for you.
Can I use it commercially?
Yes, with strict conditions. AGPL-3.0 is a network copyleft licence: if people use a modified version over a network, for example as a hosted service, you must offer them its source code under the same licence.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Rust, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • pgdogdev/pgdog5,614 ★ · +97
Star history
Repository2026-09-232026-11-15
pgdogdev/pgdog5.5k5.6k

97 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Two TOML files decide whether you get a connection pool at all

PgDog requires two configuration files to operate. `pgdog.toml` holds the general settings, the host list and the sharding configuration; `users.toml` holds usernames and passwords. The smallest useful pair is short:

toml
[general]
port = 6432
default_pool_size = 10

[[databases]]
name = "pgdog"
host = "127.0.0.1"
toml
[[users]]
name = "alice"
database = "pgdog"
password = "hunter2"

Here is the part worth keeping in your head: if a database named in `pgdog.toml` has no matching entry in `users.toml`, the connection pool for that database is never created and clients cannot connect at all. Note too that `default_pool_size` sits under `[general]` in this example.

docker-compose up gives you three shards behind port 6432

The fastest way to see sharding work is the demo at the repository root, which needs Docker Compose installed and nothing else. The compose file defines one PgDog service on the `ghcr.io/pgdogdev/pgdog:main` image and three Postgres 18 services named `shard_0`, `shard_1` and `shard_2`, all on a network called `postgres`. Each shard mounts `docker/setup.sql` into `/docker-entrypoint-initdb.d/`, and PgDog itself mounts `docker/pgdog.toml` and `docker/users.toml` into `/pgdog/`. Start it, then connect:

bash
docker-compose up
bash
PGPASSWORD=postgres psql -h 127.0.0.1 -p 6432 -U postgres

Only `6432:6432` is published, so that port is the single door into the cluster, and the three shards publish nothing at all. The demo comes with 3 shards and 2 sharded tables, so `users` and `payments` are spread across those three servers and the proxy is what stitches them into one logical database:

sql
INSERT INTO users (id, email) VALUES (1, '[email protected]');
INSERT INTO payments (id, user_id, amount) VALUES (1, 1, 100.0);

SELECT * FROM users WHERE id = 1;
SELECT * FROM payments WHERE user_id = 1;

The compose file also sets `RUST_LOG: debug` on the PgDog service, which is the first place to look when a demo query fails.

pg_raw_parse picks the primary or the replica before the query runs

PgDog is an application layer load balancer for PostgreSQL, which means it reads the wire protocol instead of just moving bytes. That capability is bought with a dependency: the workspace pulls `pg_raw_parse` from git at a pinned revision, `89937b1`, and the README credits it with including the PostgreSQL native parser. With that parser in place PgDog can tell a write from a read. `INSERT`, `UPDATE` and `CREATE TABLE` are sent to the host marked `primary`, and `SELECT` is left to the replicas, so one endpoint serves both kinds of traffic and the application stops needing a second read DSN.

The classification is per statement, and the README is explicit about where that leaves the writer. Transactions can execute multiple statements, so in a primary and replica configuration PgDog routes them to the primary. The escape hatch is a client declaration.

BEGIN READ ONLY is the only documented way off the primary

This is the routing rule that surprises people moving off a two-host setup. Transactions can execute multiple statements, so in a primary and replica configuration PgDog routes transactions to the primary. To land on a replica the client has to say so at the start:

sql
BEGIN READ ONLY;
-- This goes to a replica.
SELECT * FROM users LIMIT 1;
COMMIT;

The comment in that example is load bearing: without `READ ONLY` the identical `SELECT` goes to the primary too.

The session story is the part that actually differs from the pooler everyone already runs. Unlike PgBouncer, PgDog parses and handles `SET` statements and startup options, so session state lands correctly when two clients with different parameters share one server connection. Recovery is different too: automatic rollback of abandoned transactions, plus re-synchronization of the connection, which the README frames as a way to avoid churning server connections when an application crashes mid-query.

A second host under the same name turns the load balancer on

No config key says `load_balancer = true`. The load balancer switches itself on when a database has more than one host, so the real switch is a duplicated `name` plus a `role` on each entry:

toml
[[databases]]
name = "prod"
host = "10.0.0.1"
role = "primary"

[[databases]]
name = "prod"
host = "10.0.0.2"
role = "replica"

PgDog calls itself an application layer (OSI level 7) load balancer that understands the Postgres protocol, and it distributes transactions evenly across the databases in the group. Three strategies are offered: round robin, random, and least active connections. The first two are self explanatory; the third takes the host with the fewest connections in use, which is a rough proxy for load rather than a measurement of query cost.

Health is handled separately and continuously. PgDog keeps a real time list of healthy hosts, drops a host from the active rotation when it fails a health check, and re-routes its queries elsewhere, which the README compares to an HTTP load balancer pointed at a database. The `role` attribute is what keeps a `SELECT` off the write host, and both examples in the README set it explicitly, so treat an omitted role as unspecified rather than harmless.

Failover needs role = auto and lsn_check_delay, and still promotes nothing

Here is the boundary people misread. PgDog monitors Postgres replication state and can redirect writes to a different database once a replica has been promoted. It does not promote anything. The README says plainly that this does not replace tools like Patroni that actually orchestrate failovers, and that PgDog is meant to run alongside Patroni, AWS RDS, or another managed Postgres host so live traffic fails over gracefully.

Turning it on takes two config changes. Every `role` becomes `auto`, so PgDog works out the primary itself instead of trusting a static label, and replication monitoring is switched on through `lsn_check_delay`:

toml
[general]
lsn_check_delay = 0

[[databases]]
name = "prod"
host = "10.0.0.1"
role = "auto"

[[databases]]
name = "prod"
host = "10.0.0.2"
role = "auto"

So the order is always the same: something else promotes, PgDog notices, PgDog moves writes. If you are evaluating PgDog as a failover system rather than a client of one, the answer is no.

AGPL-3.0, weekly 0.1.x tags, and a plugin that has to be recompiled

Licence is AGPL-3.0, which matters most for anyone planning to modify the proxy and serve it as part of a hosted product. The repository also carries a separate `enterprise/` directory, a `CHANGELOG-ENTERPRISE.md` of its own, and enterprise documentation hosted apart from the open source docs.

Release cadence is quick and the line is still pre-1.0. Tags v0.1.61, v0.1.62 and v0.1.63 landed on 2026-10-09, 2026-10-16 and 2026-11-02, and the last push to the main branch was 2026-11-02. Nothing in that cadence promises config stability across a version bump, which matters for a service whose whole job is to sit in front of production traffic.

The build shape is what bites operators who want to extend it. The workspace is edition 2024, the release profile optimises hard, and there is a second profile for profiling:

toml
[profile.release]
lto = true
codegen-units = 1

[profile.flamegraph]
inherits = "release"
debug = true
lto = false
codegen-units = 16

Plugins are native libraries, not scripts. The container build copies `libpgdog_primary_only_tables.so` into `/usr/lib`, built with `cargo build --release -p pgdog-primary-only-tables` in the same build stage as the binary. The `examples/` directory holds a routing plugin written in C at `examples/routing-plugin-c/`, next to setups for `pgvector`, `multi_tenant`, `mastodon` and `pgbouncer_benchmark`.

What the open source docs leave you to find yourself

Several things an operator will ask about are not in the README, and guessing at them is how a migration goes wrong. The health check section covers only one host leaving the rotation while others remain: it does not say what a client sees in the window where every host for a database has failed.

The repository description calls PgDog a sharder, `pgdog.toml` is listed as holding sharding configuration, and the compose demo ships three shards; the README points to docs.pgdog.dev for configuration details. PgDog supports five authentication methods: password-based, AWS RDS IAM, Azure Workload Identity, and two HashiCorp Vault variants, one using dynamic credentials and one using static role credentials.

Health checking protects the database hosts behind the proxy. The proxy is one process, launched as `/usr/local/bin/pgdog` and stopped with `STOPSIGNAL SIGINT`.

Editorial conclusion

PgDog is worth a trial when one endpoint has to serve both a primary and its replicas and you want pooling in the same process. Before you commit, read the docs site for configuration details, and remember that PgDog will not promote a replica for you.

Frequently asked questions

What are the key differences between PgDog and PgBouncer?

Both do transaction and session pooling so thousands of clients share a few server connections. The stated difference is that PgDog parses and handles SET statements and startup options so session state is correct when connections are shared, and it adds automatic rollback of abandoned transactions plus connection re-synchronization. PgDog also parses each query to send writes to the primary and SELECTs to replicas.

What is PgDog?

PgDog is an open source proxy for scaling PostgreSQL, written in Rust and licensed under AGPL-3.0. It pools connections, load balances transactions across a primary and its replicas, and shards databases. It needs two files to start, pgdog.toml and users.toml.

Is PgDog a replacement for Patroni?

No. PgDog monitors replication state and redirects writes after a replica has been promoted, but the README states it does not replace tools like Patroni that actually orchestrate failovers. PgDog is meant to run alongside Patroni, AWS RDS or another managed Postgres host.

What is an alternative to PgDog?

For transaction pooling the README compares PgDog with PgBouncer, which also supports transaction and session pooling, and for failover orchestration it names Patroni. PgDog is the different choice when you want pooling and one endpoint that routes reads and writes by parsing queries, inside a single proxy process.

Official sources

  1. License: AGPL-3.0
  2. pgdogdev/pgdog on GitHub
  3. Project website
  4. README
  5. Releases
Add this badge to your README

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/pgdogdev-pgdog.svg)](https://hysenlabs.com/projects/pgdogdev-pgdog)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/pgdogdev-pgdog.svg)](https://hysenlabs.com/projects/pgdogdev-pgdog)

Was this useful?