## Context Today, the Fairway-generated Helm chart wires services to a PostgreSQL connection using the `host` and `port` fields from the operator-managed Secret. However, investigation of how the three supported PostgreSQL operators expose connection pooling revealed that the current wiring does **not** go through PgBouncer — it connects directly to the primary instance in all cases. The root cause is a misunderstanding of the CNPG Secret model: the `<cluster>-app` Secret always sets `host` to the `<cluster>-rw` Service (the primary), regardless of whether a `Pooler` resource exists. The `Pooler` does not write a pooler host into the application Secret, nor does is create a new `kubernetes.io/basic-auth` Secret. This means Fairway-managed services have never connected to PostgreSQL using PgBouncer. Artifact Registry (AR) is the concrete driving use case, with two distinct connection requirements: - **Normal traffic** → should go through PgBouncer for connection multiplexing. - **Migration client** → must bypass PgBouncer and connect directly to the primary, since PgBouncer's statement timeout kills long-running migrations. AR runs migrations at boot via a `pg_advisory_lock`. AR's higher-level migration strategy is an AR design conversation that lives in [ADR 006](https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/artifact_registry/decisions/006_technology_stack.md#21-database-schema-migrations) and is **out of scope** for this issue. Not all deployments will have a connection pooler. Our dev environment (Caproni) is a concrete example: it runs without PgBouncer, and the chart must work correctly in this configuration. ## Operator coverage Across the three supported operators, the pooler host is never reliably present in the application Secret: - **CloudNativePG**: `<cluster>-app` Secret always contains `host` = `<cluster>-rw` (primary). The `Pooler` host is not written anywhere. The pooler `Service` DNS name must be configured explicitly. - **CrunchyData**: the `<clusterName>-pguser-<userName>` Secret always contains `host` (primary Service) and, when a PgBouncer proxy is enabled, also `pgbouncer-host` and `pgbouncer-port`. This is the only operator that natively exposes both endpoints in a single Secret. - **Zalando**: the `<user>.<cluster>.credentials.postgresql.acid.zalan.do` Secret contains credentials only (username and password) — no host at all. Both the primary host (`<cluster>`) and the pooler host (`<cluster>-pooler`) are derived purely from Service naming conventions. Since no single Secret shape is universal across operators, the correct approach is to treat both the pooler address and primary address as explicitly configurable values in `values.yaml`, with optional `Secret` projection fallbacks. ## Scope End-to-end across all three layers: ### 1. Fairway (data structure) Add two optional fields to the `PostgreSQL` message in the Infrastructure proto: ```proto string pgbouncer_host = N [(buf.validate.field).string.hostname = true]; int32 pgbouncer_port = N [(buf.validate.field).int32 = { gte: 1 lte: 65535 }]; ``` Both fields are optional. When absent, LabKit falls back through the lookup chain (see below). Add corresponding projections for both fields, so they can be read from a `Secret` via the existing `secretRef` machinery. The CrunchyData projection preset must be updated to include `pgbouncer-host` and `pgbouncer-port` as the Secret keys for the two new fields. **Host and port lookup order** (first non-empty value wins): For the pooled connection: 1. `pgbouncer_host` Helm value → `pgbouncer-host` Secret key → `host` Helm value → `host` Secret key 2. `pgbouncer_port` Helm value → `pgbouncer-port` Secret key → `port` Helm value → `port` Secret key This means: in a CrunchyData deployment with a pooler, the Secret alone is sufficient and no Helm values need to be set. In a CNPG deployment, `pgbouncer_host` (and optionally `pgbouncer_port`) must be set explicitly. In a pooler-less deployment (e.g. Caproni), neither field is set and traffic falls through to `host`/`port` as today. ### 2. LabKit (middleware) Add an option to `postgres.New`: ```go postgres.WithConnectionPool(bool) ``` The option **defaults to `true`**: when constructing a client without this option, LabKit uses the pooler address (following the lookup chain above). Pass `WithConnectionPool(false)` to explicitly bypass the pooler and connect directly to the primary — the intended usage for migration clients. This replaces the previously proposed `WithPrimary(bool)` option. The semantic inversion is intentional: the pooler is the default path; the direct connection is the opt-out. ### 3. Artifact Registry (consumer) Wire AR's `NewMigrationClient` to call `postgres.New(..., postgres.WithConnectionPool(false))`. AR's `NewAppClient` continues to use the default (pooled) connection. Having a dedicated `NewMigrationClient` keeps the abstraction layer right: callers don't need to know which option means "bypass the pooler" — they ask for a migration client. ## Related - AR's database-strategy ADR: [`006_technology_stack.md`](https://gitlab.com/gitlab-com/content-sites/handbook/-/blob/main/content/handbook/engineering/architecture/design-documents/artifact_registry/decisions/006_technology_stack.md#21-database-schema-migrations) (background, out of scope). - Legacy Container Registry primary-host config in [`releases/gitlab/values/gprd.yaml.gotmpl`](https://gitlab.com/gitlab-com/gl-infra/k8s-workloads/gitlab-com/-/blob/master/releases/gitlab/values/gprd.yaml.gotmpl#L129) (precedent for the operator-facing shape). ## Tasks - [x] Add `pgbouncer_host` and `pgbouncer_port` to the `PostgreSQL` message in the Infrastructure proto - [x] Add Secret projections for `pgbouncer_host` and `pgbouncer_port`; update the CrunchyData projection preset to map `pgbouncer-host` / `pgbouncer-port` - [x] Implement the host/port lookup chain in Fairway's Helm chart templating - [x] Add `postgres.WithConnectionPool(bool)` (defaulting to `true`) to LabKit's `postgres` package - [ ] AR: implement `NewMigrationClient` using `postgres.WithConnectionPool(false)` - [x] Tests cover: pooler-less deployment (fallback to `host`/`port`), explicit `pgbouncer_host` value, CrunchyData Secret projection, both clients in the same process