From: levkk (@levkk) <noreply+levkk@github.com>
To: pgdogdev/pgdog <noreply+pgdogdev-pgdog@github.com>
Subject: [pgdogdev/pgdog] PR #2075: feat(lb): label replicas
Date: Thu, 19 Nov 2026 18:08:17 +0000
Message-ID: <gh-pgdogdev-pgdog-2075@github.com> (raw)
### Description
Fix #2051
Support comment-based routing to specific set of replicas. This allows the caller to specify which replicas each query should use, based on a pre-configured label.
### Example
```toml
# pgdog.toml
[[databases]]
host = "10.0.0.1"
name = "prod"
labels = ["analytics"]
[[databases]]
host = "10.0.01"
name = "prod"
labels = ["slow_queries", "analytics"]
```
The caller can select which database(s) each query uses as follows:
```sql
-- this will run on the "analytics" replicas, using `load_balancing_algorithm` to even out
/* pgdog_role: analytics */ SELECT * FROM users GROUP BY login_count;
-- this will run only on "slow_queries"
/* pgdog_role: slow_queries */ SELECT * FROM users WHERE not_indexed_field = $1;
```
### Implementation details
Labeled queries will _ignore_ host bans if the number of replicas it can send the query to is 0. For example, if you have two "analytics" replicas, and one of them is banned, the other will serve all queries, but if both are, the bans will be ignored and the query will attempt to connect to one of them using `load_balancing_algorithm`.
We are re-using `pgdog_role` because the routing decision conflicts with `primary`/`replica` and the caller expects the label to respected over a read/write preference.
### Mandatory labels
By default, a query without a label will be routed between all replicas. This may not be desirable, e.g., you'd want to exclude some underpowered or special replicas from regular traffic.
You can do this with a config:
```toml
[[databases]]
host = "10.0.0.1"
name = "prod"
labels = ["analytics"]
label_required = true
```
Queries without a label will not be routed to this replica.
### Specifying labels
Labels can be specified in the query as follows:
1. Query comment: `/* pgdog_role: analytics */`
2. Session parameter, e.g., `SET pgdog.role TO 'analytics'` or via connection parameter, e.g., `-c pgdog.role=analytics`
### Reviewer notes
`Request` was split up into `LbRequest` and `Request`, to avoid passing information to the `Pool` it doesn't need.