Skip to content

Allow separate configuration for the replica connection pooler #3188

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
omkar619-dev wants to merge 6 commits into
base: master
Choose a base branch
from
Open

Allow separate configuration for the replica connection pooler #3188

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
ba552f4
Add replicaConnectionPooler spec for replica pooler overrides
omkar619-dev Sep 19, 2026
d2e4dd2
Resolve connection pooler spec per role
omkar619-dev Sep 19, 2026
ceb188f
Add tests for the replica pooler spec override
omkar619-dev Sep 19, 2026
55ec3fe
Document replicaConnectionPooler
omkar619-dev Sep 19, 2026
fa8c111
Merge branch 'master' into replica-connection-pooler-spec
FxKu Oct 2, 2026
6618523
Merge branch 'master' into replica-connection-pooler-spec
idanovinda Oct 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 109 additions & 0 deletions charts/postgres-operator/crds/postgresqls.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2488,6 +2488,115 @@ spec:
type: string
type: object
type: object
replicaConnectionPooler:
description: |-
ReplicaConnectionPooler overrides connection pooler settings for the replica
pooler. Fields left unset fall back to the values under connectionPooler, so a
manifest only has to spell out what differs between the two poolers. The pooler
user and schema are intentionally not exposed here: both poolers authenticate
through the same database objects, which are created once per cluster from
connectionPooler.
properties:
dockerImage:
type: string
maxDBConnections:
format: int32
type: integer
mode:
enum:
- session
- transaction
type: string
numberOfInstances:
format: int32
minimum: 1
type: integer
resources:
description: Resources describes requests and limits for the cluster
resouces.
properties:
limits:
description: ResourceDescription describes CPU and memory
resources defined for a cluster.
properties:
cpu:
description: |-
Decimal natural followed by m, or decimal natural followed by
dot followed by up to three decimal digits.

This is because the Kubernetes CPU resource has millis as the
maximum precision. The actual values are checked in code
because the regular expression would be huge and horrible and
not very helpful in validation error messages; this one checks
only the format of the given number.

https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu

Note: the value specified here must not be zero or be lower
than the corresponding request.
pattern: ^(\d+m|\d+(\.\d{1,3})?)$
type: string
hugepages-1Gi:
pattern: ^(\d+(e\d+)?|\d+(\.\d+)?(e\d+)?[EPTGMK]i?)$
type: string
hugepages-2Mi:
pattern: ^(\d+(e\d+)?|\d+(\.\d+)?(e\d+)?[EPTGMK]i?)$
type: string
memory:
description: |-
You can express memory as a plain integer or as a fixed-point
integer using one of these suffixes: E, P, T, G, M, k. You can
also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki

https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory

Note: the value specified here must not be zero or be higher
than the corresponding limit.
pattern: ^(\d+(e\d+)?|\d+(\.\d+)?(e\d+)?[EPTGMK]i?)$
type: string
type: object
requests:
description: ResourceDescription describes CPU and memory
resources defined for a cluster.
properties:
cpu:
description: |-
Decimal natural followed by m, or decimal natural followed by
dot followed by up to three decimal digits.

This is because the Kubernetes CPU resource has millis as the
maximum precision. The actual values are checked in code
because the regular expression would be huge and horrible and
not very helpful in validation error messages; this one checks
only the format of the given number.

https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu

Note: the value specified here must not be zero or be lower
than the corresponding request.
pattern: ^(\d+m|\d+(\.\d{1,3})?)$
type: string
hugepages-1Gi:
pattern: ^(\d+(e\d+)?|\d+(\.\d+)?(e\d+)?[EPTGMK]i?)$
type: string
hugepages-2Mi:
pattern: ^(\d+(e\d+)?|\d+(\.\d+)?(e\d+)?[EPTGMK]i?)$
type: string
memory:
description: |-
You can express memory as a plain integer or as a fixed-point
integer using one of these suffixes: E, P, T, G, M, k. You can
also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki

https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory

Note: the value specified here must not be zero or be higher
than the corresponding limit.
pattern: ^(\d+(e\d+)?|\d+(\.\d+)?(e\d+)?[EPTGMK]i?)$
type: string
type: object
type: object
type: object
replicaNodePort:
format: int32
type: integer
Expand Down
32 changes: 31 additions & 1 deletion docs/reference/cluster_manifest.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -634,7 +634,8 @@ configuration for connection pooler. If this section is not empty, a connection
pooler will be created for master service only even if `enableConnectionPooler`
is not present. But if this section is present then it defines the configuration
for both master and replica pooler services (if `enableReplicaConnectionPooler`
is enabled).
is enabled), unless individual settings are overridden under
`replicaConnectionPooler`.

* **numberOfInstances**
How many instances of connection pooler to create.
Expand All @@ -659,6 +660,35 @@ for both master and replica pooler services (if `enableReplicaConnectionPooler`
* **resources**
Resource configuration for connection pooler deployment.

## Replica connection pooler

Parameters are grouped under the `replicaConnectionPooler` top-level key and
override the `connectionPooler` settings for the replica pooler only. Any field
left out here falls back to `connectionPooler`, so a manifest only has to spell
out what differs between the two poolers. This section does not create anything
on its own - `enableReplicaConnectionPooler` is still what enables the replica
pooler.

The `schema` and `user` parameters are deliberately not available here. Both
poolers authenticate through the same database objects, which are created once
per cluster from `connectionPooler`.

* **numberOfInstances**
How many instances of the replica connection pooler to create.

* **dockerImage**
Which docker image to use for the replica connection pooler deployment.

* **maxDBConnections**
How many connections the replica pooler can max hold. This value is divided
among the pooler pods.

* **mode**
In which mode to run the replica connection pooler, transaction or session.

* **resources**
Resource configuration for the replica connection pooler deployment.

## Custom TLS certificates

Those parameters are grouped under the `tls` top-level key. Note, you have to
Expand Down
23 changes: 23 additions & 0 deletions docs/user.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1218,6 +1218,29 @@ The `enableConnectionPooler` flag is not required when the `connectionPooler`
section is present in the manifest. But, it can be used to disable/remove the
pooler while keeping its configuration.

By default the `connectionPooler` section configures both poolers. To give the
replica pooler different settings, add a `replicaConnectionPooler` section
containing only the values that should differ:

```
spec:
enableConnectionPooler: true
enableReplicaConnectionPooler: true
connectionPooler:
numberOfInstances: 2
mode: "transaction"
replicaConnectionPooler:
# the replica pooler runs more instances in session mode, everything
# else is inherited from connectionPooler
numberOfInstances: 4
mode: "session"
```

Unlike `connectionPooler`, this section does not enable anything on its own -
`enableReplicaConnectionPooler` is still required. It also does not accept
`schema` or `user`, because both poolers connect through the same database
objects, which are created once per cluster from `connectionPooler`.

By default, [`PgBouncer`](https://www.pgbouncer.org/) is used as connection pooler.
To find out about pool modes read the `PgBouncer` [docs](https://www.pgbouncer.org/config.html#pooler_mode)
(but it should be the general approach between different implementation).
Expand Down
14 changes: 14 additions & 0 deletions manifests/complete-postgres-manifest.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,20 @@ spec:
# memory: 100Mi
# limits:
# cpu: "1"
# memory: 100Mi

# override connection pooler properties for the replica pooler only,
# anything left out here is inherited from connectionPooler
# replicaConnectionPooler:
# numberOfInstances: 2
# mode: "session"
# maxDBConnections: 60
# resources:
# requests:
# cpu: 300m
# memory: 100Mi
# limits:
# cpu: "1"
# memory: 100Mi

initContainers:
Expand Down
109 changes: 109 additions & 0 deletions manifests/postgresql.crd.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2488,6 +2488,115 @@ spec:
type: string
type: object
type: object
replicaConnectionPooler:
description: |-
ReplicaConnectionPooler overrides connection pooler settings for the replica
pooler. Fields left unset fall back to the values under connectionPooler, so a
manifest only has to spell out what differs between the two poolers. The pooler
user and schema are intentionally not exposed here: both poolers authenticate
through the same database objects, which are created once per cluster from
connectionPooler.
properties:
dockerImage:
type: string
maxDBConnections:
format: int32
type: integer
mode:
enum:
- session
- transaction
type: string
numberOfInstances:
format: int32
minimum: 1
type: integer
resources:
description: Resources describes requests and limits for the cluster
resouces.
properties:
limits:
description: ResourceDescription describes CPU and memory
resources defined for a cluster.
properties:
cpu:
description: |-
Decimal natural followed by m, or decimal natural followed by
dot followed by up to three decimal digits.

This is because the Kubernetes CPU resource has millis as the
maximum precision. The actual values are checked in code
because the regular expression would be huge and horrible and
not very helpful in validation error messages; this one checks
only the format of the given number.

https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu

Note: the value specified here must not be zero or be lower
than the corresponding request.
pattern: ^(\d+m|\d+(\.\d{1,3})?)$
type: string
hugepages-1Gi:
pattern: ^(\d+(e\d+)?|\d+(\.\d+)?(e\d+)?[EPTGMK]i?)$
type: string
hugepages-2Mi:
pattern: ^(\d+(e\d+)?|\d+(\.\d+)?(e\d+)?[EPTGMK]i?)$
type: string
memory:
description: |-
You can express memory as a plain integer or as a fixed-point
integer using one of these suffixes: E, P, T, G, M, k. You can
also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki

https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory

Note: the value specified here must not be zero or be higher
than the corresponding limit.
pattern: ^(\d+(e\d+)?|\d+(\.\d+)?(e\d+)?[EPTGMK]i?)$
type: string
type: object
requests:
description: ResourceDescription describes CPU and memory
resources defined for a cluster.
properties:
cpu:
description: |-
Decimal natural followed by m, or decimal natural followed by
dot followed by up to three decimal digits.

This is because the Kubernetes CPU resource has millis as the
maximum precision. The actual values are checked in code
because the regular expression would be huge and horrible and
not very helpful in validation error messages; this one checks
only the format of the given number.

https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-cpu

Note: the value specified here must not be zero or be lower
than the corresponding request.
pattern: ^(\d+m|\d+(\.\d{1,3})?)$
type: string
hugepages-1Gi:
pattern: ^(\d+(e\d+)?|\d+(\.\d+)?(e\d+)?[EPTGMK]i?)$
type: string
hugepages-2Mi:
pattern: ^(\d+(e\d+)?|\d+(\.\d+)?(e\d+)?[EPTGMK]i?)$
type: string
memory:
description: |-
You can express memory as a plain integer or as a fixed-point
integer using one of these suffixes: E, P, T, G, M, k. You can
also use the power-of-two equivalents: Ei, Pi, Ti, Gi, Mi, Ki

https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container/#meaning-of-memory

Note: the value specified here must not be zero or be higher
than the corresponding limit.
pattern: ^(\d+(e\d+)?|\d+(\.\d+)?(e\d+)?[EPTGMK]i?)$
type: string
type: object
type: object
type: object
replicaNodePort:
format: int32
type: integer
Expand Down
Loading
Loading