pgdogdev / pgdog

PgDog is a proxy for scaling PostgreSQL. It supports connection pooling, load balancing queries and sharding entire databases. Written in Rust, PgDog is fast, secure and can manage thousands of connections on commodity hardware. Documentation 📘 PgDog documentation can be **found here**. Any questions? Chat with us on **Discord**. Quick start Kubernetes Helm chart is **here**. To install it, run: AWS If you're using AWS RDS, you can deploy PgDog using one of two supported methods: • Helm chart with EKS, or a self-hosted Kubernetes cluster • Terraform module to deploy PgDog on ECS Try in Docker You can try PgDog quickly using Docker. Install Docker Compose and run: Once started, you can connect to PgDog with psql or any other PostgreSQL client: The demo comes with 3 shards and 2 sharded tables: Features 📘 **Configuration** All PgDog features are configurable and can be turned on and off. PgDog requires 2 configuration files to operate: • : hosts, sharding configuration, and other settings • : usernames and passwords Example Most options have reasonable defaults, so a basic configuration for a single user and database running on the same machine is pretty short: ** ** ** ** If a database in doesn't have a user in , the connection pool for that database will not be created and users won't be able to connect. If you'd like to try it out locally, create the database and user like so: Transaction pooling 📘 **Transactions** Like PgBouncer, PgDog supports transaction (and session) pooling, allowing thousands of clients to use just a few PostgreSQL server connections. Unlike PgBouncer, PgDog can parse and handle statements and startup options, ensuring session state is set correctly when sharing server connections between clients with different parameters. PgDog also has more advanced connection recovery options, like automatic abandoned transaction rollbacks and connection re-synchronization to avoid churning server connections during an application crash. Load balancer 📘 **Load balancer** PgDog is an application layer (OSI Level 7) load balancer for PostgreSQL. It understands the Postgres protocol, can proxy multiple replicas (and primary) and distributes transactions evenly between databases. The load balancer supports 3 strategies: round robin, random and least active connections. **Example** The load balancer is enabled automatically when a database has more than one host: Health checks 📘 **Healthchecks** PgDog maintains a real-time list of healthy hosts. When a database fails a health check, it's removed from the active rotation and queries are re-routed to other replicas. This works like an HTTP load balancer, except it's for your database. Health checks maximize database availability and protect against bad network connections, temporary hardware failures or misconfiguration. Single endpoint 📘 **Single endpoint** PgDog uses , which includes the PostgreSQL native parser. By parsing queries, PgDog can detect writes (e.g. , , , etc.) and send them to the primary, leaving the replicas to serve reads ( ). This allows applications to connect to the same PgDog deployment for both reads and writes. Transactions 📘 **Load balancer & transactions** Transactions can execute multiple statements, so in a primary & replica configuration, PgDog routes them to the primary. Clients can indicate a transaction is read-only, in which case PgDog will send it to a replica: Failover 📘 **Failover** PgDog monitors Postgres replication state and can automatically redirect writes to a different database if a replica is promoted. This doesn't replace tools like Patroni that actually orchestrate failovers. You can use PgDog alongside Patroni (or AWS RDS or other managed Postgres host), to gracefully failover live traffic. **Example** To enable failover, set all database attributes to and enable replication monitoring ( setting): Authentication 📘 **Authentication** PgDog supports two authentication methods: • Password-based • AWS RDS IAM Password-based authentication Password-based authentication allows for clients to authenticate to PgDog and for PgDog to authenticate to PostgreSQL. It currently supports the following password hashing algorithms: • SCRAM-SHA-256 • MD5 • Plain RDS IAM backend authentication PgDog can keep client-to-PgDog authentication unchanged while using AWS RDS IAM tokens for PgDog-to-PostgreSQL authentication on a per-user basis. **Example** When any user has , the following settings must be configured as well: • must **not** be . • must be . Sharding 📘 **Sharding** PgDog is able to manage databases with multiple shards. By using the PostgreSQL parser, PgDog extracts sharding keys and determines the best routing strategy for each query. For cross-shard queries, PgDog assembles and transforms results in memory, sending all rows to the client as if they are coming from a single database. **Example** Configuring multiple hosts for the same database with different shard numbers ( setting) enables sharding: Note: read below for how to configure query routing. At least one sharded table is required for sharding to work as expected. Sharding functions 📘 **Sharding functions** PgDog has two main sharding algorithms: • PostgreSQL partition functions ( , , ) • Using schemas Partition-based sharding Partition-based sharding functions are taken directly from Postgres source code. This choice intentionally allows to shard data both with PgDog and with Postgres foreign tables and . **Examples** The algorithm is used by default when configuring sharded tables: List-based sharding (same as in Postgres) can be configured as follows: For range-based sharding, replace the setting with a range, for example: Schema-based sharding 📘 **Schema-based sharding** Schema-based sharding works on the basis of PostgreSQL schemas. Tables under the same schema are…