docs: document PgBouncer transaction pooling

[avoguru]

Why

PgBouncer transaction-pooling support shipped in Arcade Helm chart 1.10.1, but the customer-facing self-hosting docs did not explain how to configure it. Operators need to know that application traffic goes through PgBouncer while migrations and database creation use a direct PostgreSQL endpoint.

Context: DEP-35

What changed

• Add a PgBouncer section to the Self-host with Helm page.
• Provide a copyable values.yaml example using postgres.host/port and postgres.directHost/directPort.
• Explain the session-state reason for the direct endpoint.
• Clarify that prepareThreshold=0 is JDBC-specific and not used by Arcade.
• Call out the per-service direct endpoint requirement when database endpoints are overridden.

Verification

• Opened and reviewed the rendered page at /en/operate/deploy/helm using the local Next.js development server; the page returned HTTP 200.
• pnpm build — passed; all 290 static pages generated.
• pnpm typecheck — passed.
• pnpm test — passed; 69 files and 864 tests.
• git diff --check — passed.
• Local Vale execution was unavailable because the Vale executable is not installed; repository CI and the automated style review remain the source of truth.

Risks and review focus

Documentation-only change. Please verify that the example hostnames and the distinction between pooled runtime traffic and direct migration traffic are clear to self-hosted operators.

Readiness evidence

Head: cb8da9f

1. Ticket linkage — PASS: DEP-35 is linked above.
2. Author comprehension — PASS: the complete one-file diff was reviewed against chart 1.10.1 behavior.
3. End-user execution — PASS: the rendered Helm page was exercised locally and returned HTTP 200.
4. Checks — BLOCKED: local build, typecheck, tests, and diff checks pass; repository CI is pending.
5. AI review — BLOCKED: the repository's automated style review starts after PR creation.
6. Fresh self-review — PASS: the final committed diff contains only the intended Helm page change.
7. Merge confidence — PASS: no known follow-up is required for the documentation change itself.

DRAFT — awaiting repository CI and automated style review.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
docs	Ready	Preview	Sep 16, 2026 6:02am UTC

[evantahler]

Confirming this really is false?

[iherdt]

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]

Then that term is… confusing?

[iherdt]

Looks right against chart 1.10.1. Two additions worth making before this ships, since both are things an operator hits on first use:

1. Say why enabled: false. With postgres.enabled: true the chart deploys the bundled Postgres and points every service at <release>-postgres, ignoring postgres.host. One sentence under the example prevents someone flipping it back and wondering why PgBouncer is never used.

2. directHost is required, not optional, once a migration is pending. The engine probes the migration endpoint at startup and refuses to migrate through a transaction pooler (refusing to migrate: ... set direct_host/direct_port to the database server instead of a transaction pooler). A database that is already current starts fine through the pooler. Worth stating so an upgrade to 1.10.1 with pooled traffic and no direct endpoint doesn't read as a mystery failure.

Nit: the values block could take title="values.yaml" per the style guide.

[iherdt]

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.