feat: enhance PgBouncer transaction pooling mode for high-performance clients#51
feat: enhance PgBouncer transaction pooling mode for high-performance clients#51
Conversation
… clients Upgrade PgBouncer to 1.25+ (PGDG) enabling max_prepared_statements support for full ORM/driver compatibility in transaction pooling mode. PgBouncer changes: - Upgrade Dockerfile to use PGDG repository (1.25+ vs Debian's 1.18) - Add max_prepared_statements=1024 for prepared statement caching - Add ignore_startup_parameters for JDBC/Go/Node compatibility - Add connection lifecycle controls (server_lifetime, server_idle_timeout) - Add client timeout protection (query_wait_timeout, client_idle_timeout) - Add DNS failover settings (dns_max_ttl, dns_nxdomain_ttl) - Add application_name_add_host for connection debugging PostgreSQL changes: - Add plan_cache_mode=auto for generic plan caching - Enable JIT compilation (jit=on, jit_above_cost=100000) - Add parallel query settings (max_parallel_workers_per_gather=4) - Add TCP keepalive settings for fast dead connection detection - Add idle_session_timeout and temp_file_limit settings Documentation: - Add comprehensive transaction pooling guide with client library examples - Document limitations and solutions for session state, temp tables, etc. - Include troubleshooting guide and diagnostic commands
Summary of ChangesHello @paudley, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly enhances the transaction pooling capabilities by upgrading PgBouncer to a version that supports prepared statements, introducing a suite of new configuration options for robust connection management and failover, and optimizing PostgreSQL settings for high-performance pooled environments. A detailed guide is also included to assist users in configuring their applications and understanding the nuances of transaction pooling. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request introduces a comprehensive set of enhancements for using PgBouncer in transaction pooling mode. The changes are well-structured and include upgrades to PgBouncer, extensive configuration options for both PgBouncer and PostgreSQL, and excellent documentation to guide users.
The implementation is solid, with new configurations clearly exposed through environment variables and reflected in the docker-compose.yml and startup scripts. The new PGBOUNCER_TRANSACTION_POOLING.md guide is particularly noteworthy for its detail and practical client library examples.
I have a couple of suggestions for improvement:
- In the
pgbouncerDockerfile, addingapt-get cleanwould help to further optimize the image size. - The
node-postgresexample in the new documentation uses an insecure SSL configuration that should be corrected to promote better security practices.
Overall, this is a great contribution that significantly improves the transaction pooling capabilities and usability of the project.
There was a problem hiding this comment.
Pull request overview
This PR enhances the PgBouncer configuration to support transaction pooling mode with full ORM and driver compatibility by upgrading to PgBouncer 1.21+ from the PGDG repository. The enhancement centers around enabling max_prepared_statements support, which allows prepared statements to work correctly in transaction pooling mode by automatically tracking and re-preparing them across connection reassignments. Additionally, the PR adds comprehensive timeout protection, connection lifecycle management, DNS failover settings, and PostgreSQL-side optimizations for transaction pooling performance.
Key changes:
- Added PGDG repository to Dockerfile for PgBouncer 1.21+ with
max_prepared_statementssupport - Extended PgBouncer configuration with transaction mode compatibility settings, connection lifecycle management, and timeout protection
- Added PostgreSQL optimizations for plan caching, JIT compilation, parallel queries, and TCP keepalives
- Created comprehensive documentation guide with client library examples and troubleshooting guidance
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| docker/pgbouncer/Dockerfile | Adds PGDG repository to install PgBouncer 1.21+ with prepared statement support |
| pgbouncer/entrypoint.sh | Adds environment variables and configuration generation for transaction pooling features |
| postgres/conf/postgresql.conf.tpl | Adds PostgreSQL configuration optimizations for transaction pooling (plan cache, JIT, TCP keepalives) |
| docker-compose.yml | Passes new environment variables to both PostgreSQL and PgBouncer services |
| .env.example | Documents all new configuration options with detailed comments |
| docs/PGBOUNCER_TRANSACTION_POOLING.md | New comprehensive guide for transaction pooling with examples and troubleshooting |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Add apt-get clean before rm -rf for smaller image size (Gemini) - Fix inconsistent version reference: 1.25+ → 1.21+ (Copilot) max_prepared_statements requires PgBouncer 1.21+, not 1.25+
Address Copilot review: Go examples now show proper error handling with if err != nil checks instead of ignoring errors with _
1 participant
Summary
max_prepared_statementsfor full ORM/driver compatibility in transaction pooling modeKey Changes
PgBouncer Enhancements
max_prepared_statements=1024- enables automatic prepared statement tracking in transaction modeignore_startup_parametersfor JDBC, Go lib/pq, Node.js, psqlserver_lifetime=1800,server_idle_timeout=300for connection recyclingquery_wait_timeout=30,client_idle_timeout=3600for fast-fail and cleanupdns_max_ttl=30,dns_nxdomain_ttl=5for quick failoverapplication_name_add_host=1appends client IP:port to application_namePostgreSQL Optimizations
plan_cache_mode=auto- generic plan caching after 5 executionsjit=onwithjit_above_cost=100000- JIT for complex queriesmax_parallel_workers_per_gather=4- parallel query supporttcp_keepalives_idle=60- fast dead connection detectionDocumentation
docs/PGBOUNCER_TRANSACTION_POOLING.mdFiles Changed
docker/pgbouncer/Dockerfile- Add PGDG repository for PgBouncer 1.25+pgbouncer/entrypoint.sh- Add env vars and config generationpostgres/conf/postgresql.conf.tpl- Add transaction pooling optimizationsdocker-compose.yml- Pass new env vars to both services.env.example- Document all new configuration optionsdocs/PGBOUNCER_TRANSACTION_POOLING.md- New comprehensive guideTest plan
docker compose build pgbouncer && docker compose run --rm pgbouncer pgbouncer --versiondocker compose --profile pgbouncer up -ddocker compose exec pgbouncer cat /tmp/pgbouncer.iniSHOW jit; SHOW plan_cache_mode; SHOW tcp_keepalives_idle;