# PgDog — PostgreSQL Connection Pooler, Load Balancer & Sharder

> A high-performance PostgreSQL proxy written in Rust that provides connection pooling, read/write splitting, load balancing, and automatic sharding in a single binary.

## Install

Save in your project root:

# PgDog — PostgreSQL Connection Pooler, Load Balancer & Sharder

## Quick Use
```bash
# Install from cargo
cargo install pgdog

# Or download a prebuilt binary from GitHub releases
# Configure pgdog.toml with your PostgreSQL servers
pgdog --config pgdog.toml

# Connect your application to PgDog instead of PostgreSQL directly
psql -h 127.0.0.1 -p 6432 -U myuser mydb
```

## Introduction
PgDog is a PostgreSQL connection pooler, load balancer, and database sharder written in Rust. It sits between your application and PostgreSQL servers, managing connection reuse, distributing queries across replicas, and optionally sharding data across multiple databases.

## What PgDog Does
- Pools PostgreSQL connections to reduce backend connection overhead
- Splits read and write queries across primary and replica servers
- Load balances read queries across multiple PostgreSQL replicas
- Provides automatic database sharding for horizontal scaling
- Speaks the PostgreSQL wire protocol natively for drop-in deployment

## Architecture Overview
PgDog operates as a transparent proxy using an async Rust runtime (Tokio) for high-throughput connection handling. It parses the PostgreSQL wire protocol to understand query types, routes writes to the primary and reads to replicas, and manages a pool of backend connections per server. The sharding layer inspects queries and routes them to the appropriate shard based on configurable key-based partitioning rules.

## Self-Hosting & Configuration
- Install via cargo or download a release binary
- Define upstream PostgreSQL servers in a TOML configuration file
- Set pool sizes, timeouts, and connection lifetime parameters
- Enable read/write splitting with primary and replica designations
- Configure sharding rules by specifying shard keys and partition mappings

## Key Features
- Written in Rust for memory safety and high concurrency performance
- Connection pooling with session, transaction, and statement-level modes
- Automatic read/write splitting without application changes
- Built-in load balancing with health checks across replicas
- Sharding support for horizontally partitioned PostgreSQL deployments

## Comparison with Similar Tools
- **PgBouncer** — lightweight pooler only; PgDog adds load balancing, read/write splitting, and sharding
- **Pgpool-II** — mature C-based proxy; PgDog is a modern Rust implementation with simpler configuration
- **Citus** — PostgreSQL extension for sharding; PgDog is an external proxy requiring no database modifications
- **Supavisor** — Elixir-based pooler by Supabase; PgDog offers sharding and is written in Rust for lower overhead

## FAQ
**Q: Does PgDog modify my PostgreSQL installation?**
A: No. PgDog is a standalone proxy that speaks the PostgreSQL wire protocol. No extensions or modifications to your database are needed.

**Q: What pooling modes are supported?**
A: PgDog supports session-level, transaction-level, and statement-level connection pooling, similar to PgBouncer.

**Q: How does read/write splitting work?**
A: PgDog parses incoming SQL to identify reads (SELECT) and writes (INSERT, UPDATE, DELETE) and routes them to the appropriate backend automatically.

**Q: Can I use PgDog without sharding?**
A: Yes. Sharding is optional. PgDog works as a straightforward connection pooler and load balancer without any sharding configuration.

## Sources
- https://github.com/pgdogdev/pgdog
- https://pgdog.dev/

---
Source: https://tokrepo.com/en/workflows/asset-24c77a21
Author: AI Open Source