LICENSE Documentation

1. Project Overview & Quickstart (pgdogdev/LICENSE) Copy Chapter

LICENSE

Open-source repository pgdogdev/LICENSE

Repository Details Copy Section

• Repository: pgdogdev/LICENSE
• Primary Language: Code

Note: High-volume repository documentation is actively indexed and synchronized by YakaAI.

2. Official Technical Reference & Guides (pgdogdev/docs) Copy Chapter

File: README.md Copy Chapter

PgDog Documentation

This repository contains the documentation hosted on https://docs.pgdog.dev.

Contributions Copy Chapter

Contributions are welcome. Please open a pull request / issue with requested changes. Once the PR is merged,
you should see changes in production within a few minutes.

File: docs/administration/clients.md Copy Chapter

icon: material/account-multiple Copy Chapter

Client connections

PgDog provides real time statistics and information on all client connections. They can be accessed by connecting to the admin database and running the SHOW CLIENTS command:

SHOW CLIENTS;

The following information is returned for each client connection to PgDog:

File: docs/administration/config.md Copy Chapter

icon: material/cog Copy Chapter

Configuration

PgDog provides real time access to its current configuration values. They can be accessed by connecting to the admin database and running the SHOW CONFIG command:

SHOW CONFIG;

The following configuration parameters are available and their current values:

File: docs/administration/index.md Copy Chapter

icon: material/monitor-dashboard Copy Chapter

Administration overview

PgDog keeps track of clients, servers and connection pools. It provides real time statistics on its internal operations for system
administrators to keep track of and integrate with monitoring tools like Datadog.

Just like pgbouncer, PgDog has a special "admin" database clients can connect to and run custom SQL commands
to get statistics.

Admin database Copy Chapter

The admin database name is configurable. By default, the database is called admin. It supports a number of commands, documented below.

Commands Copy Section

Shutting down PgDog Copy Chapter

When you need to shutdown PgDog, e.g. to deploy a new version, you can do so gracefully by issuing SIGINT (e.g. Ctrl-C) to the pgdog process.
PgDog will stop listening for new connections and give connected clients some time to finish their transactions and disconnect.

The amount of time PgDog will wait is configurable. By default, PgDog will wait 60 seconds.

Example

$ pkill pgdog -SIGINT

File: docs/administration/maintenance_mode.md Copy Chapter

icon: material/wrench Copy Chapter

Maintenance mode

Maintenance mode pauses queries from all clients so you can synchronize configuration changes across multiple instances of PgDog. This is useful if you're changing the sharding options.

How it works Copy Section

You can turn on maintenance mode by connecting to the admin database and running this query:

MAINTENANCE ON;

Clients that are currently executing a transaction will be allowed to finish, while all others will be immediately paused. Pausing traffic has the effect of holding query requests inside PgDog's network buffer. To the client, this will seem like the proxy isn't responding.

!!! note
Before enabling maintenance mode, make sure to set the application-level timeouts high enough as to avoid erroring out.

During maintenance mode, you can perform live configuration changes. The following flow is typical and, if performed quickly, won't cause errors or downtime:

1. Make changes to pgdog.toml and/or users.toml
2. Enable maintenance mode
3. Reload config on all instances of PgDog
4. Disable maintenance mode

Turn off maintenance mode

Turning off maintenance mode and resuming all queries can be done with a query:

MAINTENANCE OFF;

File: docs/administration/pools.md Copy Chapter

icon: material/pool Copy Chapter

Connection pools

PgDog provides real time statistics and information on its connection pools. You can view them by connecting to the admin database and running the SHOW POOLS command:

SHOW POOLS;

The following information is returned for each connection pool (user/database pair) managed by PgDog:

File: docs/administration/replication.md Copy Chapter

icon: material/content-copy Copy Chapter

Replication

PgDog provides a real time view into PostgreSQL replication for the purposes of monitoring replication delay and performing query traffic failover.

You can view this data by connecting to the admin database and running this query:

SHOW REPLICATION;

The following information is returned for each database:

File: docs/administration/servers.md Copy Chapter

icon: material/server Copy Chapter

Server connections

PgDog provides real time statistics and information on all connections to PostgreSQL databases. They can be accessed by connecting to the admin database and running the SHOW SERVERS command:

SHOW SERVERS;

The following information is returned for each connection from PgDog to a PostgreSQL database:

File: docs/administration/tasks.md Copy Chapter

icon: material/format-list-checks Copy Chapter

Background tasks

Long-running operations like resharding don't block the connection that started them. Instead, RESHARD, COPY_DATA, REPLICATE, and SCHEMA_SYNC each return a task_id and run in the background. SHOW TASKS is how you track those tasks: it reports their lifecycle status and progress, lets you find the task_id to pass to STOP_TASK or CUTOVER, and surfaces failures.

Run it on the admin database:

SHOW TASKS;

!!! note "Admin database tasks only"
SHOW TASKS lists the background tasks running inside the same PgDog process. The equivalent CLI commands (pgdog data-sync, pgdog schema-sync) spawn their own process in the foreground instead, and block until they finish or are stopped with SIGINT (or SIGTERM).

=== "Output"
-[ RECORD 1 ]+---------------------------------- id | 14 scope | root type | reshard prod -> prod_sharded status | running inner_status | syncing data started_at | 2026-06-30 18:02:11.004 UTC updated_at | 2026-06-30 18:05:42.119 UTC elapsed | 00:03:31:115 elapsed_ms | 211115 -[ RECORD 2 ]+---------------------------------- id | scope | subtask type | copy_data prod -> prod_sharded status | running inner_status | started_at | 2026-06-30 18:02:30.550 UTC updated_at | 2026-06-30 18:05:42.119 UTC elapsed | 00:03:11:569 elapsed_ms | 191569

Tasks are ordered by creation date, starting at the oldest.

Columns Copy Chapter

Statuses Copy Chapter

The status column describes where the task is in its lifecycle:

finished, cancelled, failed, and panicked are terminal. Terminal tasks stay listed with their final status (and last progress) for a while so you can inspect the outcome, then they're pruned automatically.

Progress Copy Chapter

The inner_status column shows what the task is doing within its current status. The values depend on the task type:

Finding the right ID Copy Chapter

STOP_TASK and CUTOVER always operate on the parent ID:

• A RESHARD or COPY_DATA shows as a root task with its child steps listed as subtask rows. Target the root ID, not a subtask; subtask rows have an empty id on purpose.
• After a cutover, the reverse replication stream appears as its own root task of type replication ... (reverse). Use its ID to roll back (CUTOVER ) or to finalize the migration (STOP_TASK ).

Spotting issues Copy Chapter

Stopping a task Copy Chapter

Stop any running task by its root id:

STOP_TASK <task_id>;

This requests cancellation; the task winds down gracefully and stops appearing as running once it has actually stopped. For replication and copy tasks, a graceful stop also drops the replication slot the task created. See finalizing the migration for how this is used after a cutover.

File: docs/architecture/benchmarks.md Copy Chapter

icon: material/chart-bar Copy Chapter

Benchmarks

PgDog does its best to minimize its impact on database performance. Great care is taken to make sure as few operations as possible are performed
when passing data between clients and servers.

All benchmarks listed below were done on my local system (AMD Ryzen 7 5800X). Real world performance is impacted by factors like network speed, query complexity and especially by hardware used for running PgDog and PostgreSQL servers.

pgbench Copy Chapter

The simplest way to test PostgreSQL performance is with pgbench. It comes standard with all PostgreSQL installations (Mac and Linux):

$ pgbench --version
pgbench (PostgreSQL) 16.4 (Postgres.app)

A standard pgBench benchmark will run INSERT, UPDATE, SELECT and DELETE queries to get an overall view of database performance. Since we are only testing the performance of PgDog, we are going to run SELECT queries only and minimize the impact of hard disk I/O on this test.

This benchmark can be reproduced by passing the -S flag to pgbench. The results below were performed using the configuration found in pgdog.toml.

Results Copy Chapter

Multi-threaded Copy Section

Numbers below are for a single database benchmark in transaction mode. workers are set to 4, so PgDog is running 4 threads and using async I/O.

Protocol

The protocol column indicates what kind of communication protocol
pgbench is using to talk to PgDog/Postgres.

simple protocol is sending
queries with parameters included in query text. This requires Postgres
to receive only one message but has parsing overhead inside PgDog.

extended protocol separates parameters from query text. This prevents
SQL injection attacks, but PgDog is able to deduplicate statements and most parsing overhead.

prepared protocol is the fastest since pgbench is re-using the same
statements and only sends different parameters. This removes the need to parse
statements inside PgDog and Postgres.

The numbers

Single-threaded Copy Section

This benchmark ran with workers set to 0. This makes PgDog run in single-threaded mode, but still uses async I/O.

Interpretation Copy Section

1 client

Benchmarks with -c 1 (1 client) are a good baseline for what's possible under the best possible circumstances. There is no contention on resources
and PgDog effectively receives data in one socket and pushes it out the other.

10 clients

With 10 clients actively querying the database, the connection pool is at full capacity (default_pool_size is set to 10). While there are no clients waiting for connections, the pool has to serve clients without any slack in the system.

100 clients

With over 10x more clients connected than available servers, connections are fighting for resources and PgDog has to make sure everyone gets served in a fair way. Consistent throughput in this benchmark demonstrates our ability to timeshare server connections effectively.

Parser overhead Copy Section

PgDog parses statements to figure out where they should go. When using simple protocol, PgDog can't cache statements (since they include parameters), so the overhead of the parser is noticeable. When using extended and prepared protocols, the cache is doing its job and the parser overhead is almost entirely eliminated.

In the real world Copy Section

In production, PostgreSQL clients are expected to be mostly idle. For example, web applications spend a lot of their time parsing HTTP requests, running code and waiting on network I/O. This leaves plenty of time for PgDog (and PostgreSQL) to serve queries for thousands of clients.

Hardware impact

Benchmark results will vary widely with hardware. For example, these numbers will be better on new Apple M chips and slower on older Intel CPUs. This benchmark was ran on AMD Ryzen 7 5800X. Expect yours to vary, but the overall trend to be directionally similar.

pgbench configuration Copy Section

export PGPASSWORD=pgdog

pgbench -P 1 -h 127.0.0.1 -p 6432 \
    -U pgdog pgdog -c 10 -t 100000 -S \
    --protocol prepared