feat(postgresql): add standalone PgBouncer component

[ldming]

Summary

• keep the existing PostgreSQL replication topology and add PgBouncer as an independent component
• default the PgBouncer component to zero replicas so the connection pool can be enabled or disabled by changing its replicas
• preserve existing PostgreSQL components and the legacy in-Pod PgBouncer sidecar created by PostgreSQL Addon 1.0.5
• add a versioned PgBouncer ComponentDefinition and ComponentVersion, starting with PgBouncer 1.25.2
• keep released PgBouncer versions in pgbouncer.componentImage.versions[] and require exactly one default version
• manage PgBouncer parameters through the KubeBlocks Parameter, ParamConfigRenderer, and ParametersDefinition APIs
• apply supported parameter changes with SIGHUP reload instead of restarting the PgBouncer container
• require readiness traffic through PgBouncer to reach a writable PostgreSQL primary

Upgrade behavior

The final candidate was validated by upgrading the PostgreSQL Addon from 1.0.5 to 1.0.6 on KubeBlocks 1.0.3-beta.10.

• the Addon upgrade itself did not restart or recreate either PostgreSQL Pod
• PostgreSQL Pod UIDs, creation timestamps, controller revisions, container IDs, image IDs, and restart counts remained unchanged
• the existing PostgreSQL component remained bound to postgresql-14-1.0.5 and service version 14.23.0
• direct PostgreSQL 5432 and the legacy sidecar 6432 remained available and retained pre-upgrade data
• the Addon upgrade did not immediately enqueue existing Clusters
• on the next normal Cluster reconciliation, KubeBlocks 1.0 materialized pgbouncer-1.0.6 with service version 1.25.2 and zero replicas
• materializing the zero-replica component did not create a PgBouncer Pod or change the PostgreSQL Pods
• scaling PgBouncer from 0 to 1 started one ready PgBouncer 1.25.2 Pod and made the standalone 6432 Service usable
• scaling PgBouncer from 1 back to 0 removed the standalone Pod and left its Services without Endpoints; PostgreSQL remained available

PgBouncer runtime and parameters

• authenticated SQL through the standalone PgBouncer Service reached the writable PostgreSQL primary and read data created before the Addon upgrade
• the readiness SQL returned true for the primary and false for a PostgreSQL replica by checking both NOT pg_is_in_recovery() and transaction_read_only = 'off'
• updating max_client_conn from 500 to 321 and pool_mode from session to transaction through the KubeBlocks Parameter API completed successfully
• PgBouncer logged got SIGHUP, re-reading config; its Pod UID, container ID, process ID, and restart count remained unchanged
• SHOW CONFIG reported the updated values and authenticated SQL continued to succeed after reload
• an invalid max_client_conn=0 update was rejected by the CUE constraint and did not change the running configuration

Verification

• KubeBlocks 1.0.3-beta.10 disposable k3d upgrade test: PostgreSQL Addon 1.0.5 to 1.0.6
• PostgreSQL 14.23.0, two replicas, with direct and pooled SQL before and after upgrade
• standalone PgBouncer lifecycle: 0 to 1 to 0 replicas
• KubeBlocks Parameter API reload and CUE negative validation
• primary and replica readiness SQL checks
• ShellSpec: 20 examples, 0 failures
• helm lint --strict and Helm render checks
• CUE validation
• shell syntax checks
• git diff --check

All runtime images in the k3d validation were pulled directly from the ApeCloud registry. No local image import was used.

Product and release boundaries

• PgBouncer uses session pooling by default and does not transparently migrate existing sessions during PostgreSQL failover. Applications must reconnect and retry failed work.
• zero replicas means disabled. The standalone Services may still exist without ready Endpoints and must not be presented as an available connection address.
• the APIServer follow-up must ensure the zero-replica PgBouncer component is materialized before submitting the first scaling operation for an existing Cluster.
• existing 1.0.5 Clusters retain their legacy PgBouncer sidecar and original PostgreSQL 6432 endpoint; the new replica setting controls only the standalone component.
• TLS is not implemented on either PgBouncer hop. The APIServer and Console follow-ups must reject enabling the pool for TLS-required Clusters.
• the standalone component currently uses the PostgreSQL postgres account. A least-privilege authentication function and account migration remain separate security work.
• rollback from Addon 1.0.6 to 1.0.5 is not supported by this change. Disabling PgBouncer does not make a Chart rollback safe.

Related to apecloud/apecloud#20276.

[codecov-commenter]

Codecov Report

❌ Patch coverage is 0% with 123 lines in your changes missing coverage. Please review.
✅ Project coverage is 0.00%. Comparing base (d233fe1) to head (eb23494).
⚠️ Report is 5 commits behind head on release-1.0.

Files with missing lines	Patch %	Lines
...postgresql/scripts-ut-spec/pgbouncer_setup_spec.sh	0.00%	94 Missing ⚠️
.../postgresql/scripts-ut-spec/version_matrix_spec.sh	0.00%	29 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           release-1.0   #3430   +/-   ##
===========================================
  Coverage         0.00%   0.00%           
===========================================
  Files               69      70    +1     
  Lines             7275    7333   +58     
===========================================
- Misses            7275    7333   +58     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.