From f4b44057694e51cbad98d4d90df5b6e772356bd8 Mon Sep 17 00:00:00 2001 From: Marko Kreen Date: Mon, 8 Oct 2007 06:57:58 +0000 Subject: [PATCH] doc updates --- doc/overview.txt | 40 ++++++++++++++++++++++++++++++++++----- doc/pgbouncer.1 | 6 +++--- doc/pgbouncer.5 | 21 +++++++++++++++----- doc/pgbouncer.cmdline.txt | 2 +- doc/pgbouncer.config.txt | 6 +++--- 5 files changed, 58 insertions(+), 17 deletions(-) diff --git a/doc/overview.txt b/doc/overview.txt index bed5136..156c299 100644 --- a/doc/overview.txt +++ b/doc/overview.txt @@ -18,12 +18,15 @@ Downloads, bugtracker, CVS: http://pgfoundry.org/projects/pgbouncer 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. @@ -33,7 +36,7 @@ Downloads, bugtracker, CVS: http://pgfoundry.org/projects/pgbouncer * 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. @@ -42,3 +45,30 @@ Downloads, bugtracker, CVS: http://pgfoundry.org/projects/pgbouncer * 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. diff --git a/doc/pgbouncer.1 b/doc/pgbouncer.1 index e0c98c3..500a0b8 100644 --- a/doc/pgbouncer.1 +++ b/doc/pgbouncer.1 @@ -1,11 +1,11 @@ .\" Title: pgbouncer .\" Author: .\" Generator: DocBook XSL Stylesheets v1.71.1 -.\" Date: 09/06/2007 +.\" Date: 10/03/2007 .\" Manual: .\" Source: .\" -.TH "PGBOUNCER" "1" "09/06/2007" "" "" +.TH "PGBOUNCER" "1" "10/03/2007" "" "" .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) @@ -606,7 +606,7 @@ no, shows if the variable is changeable when running. If no, the variable can be changed only boot\-time. .RE .RE -.SS "PROCESS CONTROLING COMMANDS" +.SS "PROCESS CONTROLLING COMMANDS" .sp .it 1 an-trap .nr an-no-space-flag 1 diff --git a/doc/pgbouncer.5 b/doc/pgbouncer.5 index 29001a9..2317d5c 100644 --- a/doc/pgbouncer.5 +++ b/doc/pgbouncer.5 @@ -1,11 +1,11 @@ .\" Title: pgbouncer .\" Author: .\" Generator: DocBook XSL Stylesheets v1.71.1 -.\" 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) @@ -176,7 +176,7 @@ Maximum number of client connections allowed. When increased then the file descr .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 @@ -185,11 +185,11 @@ if each user connects under it's own username to server. If database user is spe .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 @@ -509,6 +509,17 @@ If user= is set, all connections to destination database will be done with that 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 diff --git a/doc/pgbouncer.cmdline.txt b/doc/pgbouncer.cmdline.txt index 17db7e8..2b7ee09 100644 --- a/doc/pgbouncer.cmdline.txt +++ b/doc/pgbouncer.cmdline.txt @@ -354,7 +354,7 @@ changeable:: Either +yes+ or +no+, shows if the variable is changeable when running. If +no+, the variable can be changed only boot-time. -=== PROCESS CONTROLING COMMANDS === +=== PROCESS CONTROLLING COMMANDS === ==== PAUSE; ==== diff --git a/doc/pgbouncer.config.txt b/doc/pgbouncer.config.txt index bba7e9f..fa8d6a7 100644 --- a/doc/pgbouncer.config.txt +++ b/doc/pgbouncer.config.txt @@ -106,15 +106,15 @@ Maximum number of client connections allowed. When increased then the file 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. -- 2.40.0