labkit/v2/postgres: PgBouncer compatibility (QueryExecModeSimpleProtocol)

Context

GitLab.com routes all database connections through PgBouncer in transaction pooling mode. This breaks server-side prepared statements — the default query execution mode in pgx.

Identified as a required change in the Artifact Registry PoC assessment: "Required for GitLab.com deployment. Small change."

Problem

pgx defaults to QueryExecModeCacheStatement which uses prepared statements. PgBouncer in transaction mode does not support prepared statements across connections, causing ERROR: prepared statement "..." already exists or similar failures in production.

The Container Registry handles this with QueryExecModeSimpleProtocol.

Tasks

  • Expose QueryExecMode as a configuration option on postgres.Config
  • Default to QueryExecModeSimpleProtocol (matches GitLab.com deployment requirements), or document DSN-based workaround
  • Add documentation about PgBouncer pooling mode requirements
  • Test against a PgBouncer instance in CI or local dev setup

References

Edited by Elliot Forbes