Transaction pooling::
Server connection is assigned to client only during a transaction.
When PgBouncer notices that transaction is over, the server
- will be put back into pool.
+ will be put back into pool. This is a hack as it breaks application
+ expectations of backend connection. You can use it only when
+ application cooperates with such usage by not using features
+ that can break. See the table below for breaking features.
Statement pooling::
- Most aggressive method. The server connection will be put back into
- pool immidiately after a query completes. Multi-statement
- transactions are disallowed in this mode as they would break.
+ Most aggressive method. This is transaction pooling with a twist -
+ multi-statement transactions are disallowed. This is meant to enforce
+ "autocommit" mode on client, mostly targeted for PL/Proxy.
* Low memory requirements (2k per connection by default). This is due
to the fact that PgBouncer does not need to see full packet at once.
* Supports online reconfiguration for most of the settings.
- * Supports online restart/upgrade - is able transfer sockets to new process.
+ * Supports online restart/upgrade without dropping client connections.
* Supports protocol V3 only, so backend version must be >= 7.4.
* Detailed usage info: ./UsageInfo
* Config file help: ./ConfigFile
* TODO list: ./ToDo
+
+== Feature map ==
+
+Following table list various PostgreSQL features and whether they are
+compatible with PgBouncer pooling modes. Note that 'transaction'
+pooling breaks client expectations of server and can be used only
+if application cooperates by not using non-working features.
+
+|| Feature || Session pooling || Transaction pooling ||
+|| Startup parameters || Yes [0] || Yes [0] ||
+|| SET/RESET || Yes || Never ||
+|| LISTEN/NOTIFY || Yes || Never ||
+|| WITHOUT HOLD CURSOR || Yes || Yes ||
+|| WITH HOLD CURSOR || Yes [1] || Never ||
+|| Protocol-level prepared plans || Yes [1] || No [2] ||
+|| PREPARE / DEALLOCATE || Yes [1] || Never ||
+|| ON COMMIT DROP temp tables || Yes || Yes ||
+|| PRESERVE/DELETE ROWS temp tables || Yes [1] || Never ||
+|| Cached plan reset || Yes [1] || Yes [1] ||
+|| LOAD statement || Yes || Never ||
+
+ * [0] - Startup parameters are: `client_encoding`, `datestyle`, `timezone`
+ and `standard_conforming_strings`. PgBouncer can detect their changes
+ so it can guarantee they remain consistent for client. Available
+ from PgBouncer 1.1.
+ * [1] - Full transparency requires PostgreSQL 8.3 and PgBouncer 1.1 with `server_reset_query = DISCARD ALL`
+ * [2] - It is possible to add support for that into PgBouncer.
.\" Title: pgbouncer
.\" Author:
.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/>
-.\" Date: 09/06/2007
+.\" Date: 10/03/2007
.\" Manual:
.\" Source:
.\"
-.TH "PGBOUNCER" "5" "09/06/2007" "" ""
+.TH "PGBOUNCER" "5" "10/03/2007" "" ""
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.sp
.RS 4
.nf
-max_client_conn * max_pool_size * total_databases * total_users
+max_client_conn + (max_pool_size * total_databases * total_users)
.fi
.RE
.sp
.sp
.RS 4
.nf
-max_client_conn * max_pool_size * total_databases
+max_client_conn + (max_pool_size * total_databases)
.fi
.RE
.sp
-The theoretical maximum is never reaches, unless somebody deliberately crafts special load for it. Still, it means you should give fds liberately.
+The theoretical maximum should be never reached, unless somebody deliberately crafts special load for it. Still, it means you should give fds liberately.
.sp
Search for ulimit in your favourite shell man page.
.sp
Otherwise pgbouncer tries to log into destination database with client username, meaning that there will be one pool per user.
.sp
.RE
+.SS "Per\-database pool Size"
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
+\fBpool_size\fR
+.RS
+Set maximum size of pools for this database. If not set, the default_pool_size is used.
+.sp
+.RE
.SS "Extra parameters"
They allow setting default parameters on server connection.
.sp
descriptor limits should also be increased. Note that actual number of file
descriptiors used is more that max_client_conn. Theoretical maximum used is:
- max_client_conn * max_pool_size * total_databases * total_users
+ max_client_conn + (max_pool_size * total_databases * total_users)
if each user connects under it's own username to server. If database user
is specified in connect string (all users connect under same username),
the theoretical maximum is:
- max_client_conn * max_pool_size * total_databases
+ max_client_conn + (max_pool_size * total_databases)
-The theoretical maximum is never reaches, unless somebody deliberately
+The theoretical maximum should be never reached, unless somebody deliberately
crafts special load for it. Still, it means you should give fds liberately.
Search for `ulimit` in your favourite shell man page.
projects / pgbouncer / commitdiff