pg.ddx.io  pgdogdev/pgdog GitHub issues and pull requests  
help / color / mirror / Atom feed
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.

view thread (7+ messages)  latest in thread

Message-ID: <gh-pgdogdev-pgdog-2075@github.com>
Permalink:  ../gh-pgdogdev-pgdog-2075@github.com/

 · 


This inbox is served by DDX for PostgreSQL; see mirroring instructions
for how to clone and mirror all data and code used for this inbox