Skip to content

docs: document PgBouncer transaction pooling #1196

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

Draft
avoguru wants to merge 1 commit into
base: main
Choose a base branch
from
Draft

docs: document PgBouncer transaction pooling #1196

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
19 changes: 19 additions & 0 deletions app/en/operate/deploy/helm/page.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,25 @@ Configure the platform through Helm values. The chart covers:
The full, versioned values reference lives on [Artifact Hub](https://artifacthub.io/packages/helm/arcade/arcade). Use it as the source of truth for every value and default.
</Callout>

### Use PgBouncer transaction pooling

Arcade Helm chart 1.10.1 and later supports PostgreSQL through PgBouncer in transaction pooling mode. Route application traffic through PgBouncer, and configure a direct connection to the PostgreSQL primary for migrations and database creation:

```yaml
postgres:
enabled: false

@evantahler evantahler Sep 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Confirming this really is false?

@iherdt iherdt Sep 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

seems correct, if it's not set to false then the host value is ignored Deploys the bundled Postgres StatefulSet. Set false for external.

@evantahler evantahler Sep 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Then that term is… confusing?

host: pgbouncer.database.svc.cluster.local
port: 6432
directHost: postgres-primary.database.svc.cluster.local
directPort: 5432
```

`postgres.host` and `postgres.port` are used by the running services. `postgres.directHost` and `postgres.directPort` are used for operations that require PostgreSQL session state, which transaction pooling doesn't preserve.

@iherdt iherdt Sep 16, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
`postgres.host` and `postgres.port` are used by the running services. `postgres.directHost` and `postgres.directPort` are used for operations that require PostgreSQL session state, which transaction pooling doesn't preserve.
`postgres.enabled: false` turns off the bundled Postgres so the chart uses the hosts above. `postgres.host` and `postgres.port` serve the running services. `postgres.directHost` and `postgres.directPort` serve migrations and database creation, which need PostgreSQL session state that transaction pooling doesn't preserve. When a migration is pending, the engine checks the migration endpoint at startup and refuses to run it through a transaction pooler, so set the direct endpoint before upgrading. A database that is already current starts through the pooler without it.


Don't add `prepareThreshold=0` to the connection string. That setting applies to JDBC clients and isn't used by Arcade.

If a service defines its own `<service>.database.host` or `<service>.database.port`, also configure that service's `<service>.database.directHost` and `<service>.database.directPort`.

## Upgrade and roll back

Upgrade to a new chart version with `helm upgrade`, and roll back with `helm rollback` if needed. See the [Artifact Hub listing](https://artifacthub.io/packages/helm/arcade/arcade) for version-specific upgrade notes.
Expand Down
Loading