-include ../config.mak
MANPAGES = pgbouncer.1 pgbouncer.5
-HTML = config.html usage.html todo.html
+HTML = config.html usage.html todo.html faq.html
all: $(MANPAGES)
endif
clean:
- rm -f *.html *.xml
+ rm -f *.html
distclean: clean
+ rm -f *.xml
realclean: distclean
rm -f *.[1-9]
==== logfile ====
-Specifies log file. Logging is done by open/write/close, so it can be safely
-rotasted, without informing pooler.
+Specifies log file. Log file is kept open so after rotation
+`kill -HUP` or on console `RELOAD;` should be done.
Default: not set.
==== listen_addr ====
-Specifies IPv4 address, where to listen for TCP connections. Or +++"*"+++
-meaning 'listen on all addresses'. When not set, only unix socket
+Specifies IPv4 address, where to listen for TCP connections. Or `*`
+meaning "listen on all addresses". When not set, only unix socket
connections are allowed.
-Default: not set.
+Default: not set
==== listen_port ====
How to authenticate users.
md5::
- Use MD5-based password check. auth_file may contain both md5-encrypted
+ Use MD5-based password check. `auth_file` may contain both md5-encrypted
or plain-text passwords. Default.
crypt::
- Use crypt(3) based bassword check. auth_file must contain plain-text
+ Use crypt(3) based bassword check. `auth_file` must contain plain-text
passwords.
plain::
Clear-text password is sent over wire.
trust::
- No authentication is done. Username must still exists in auth_file.
+ No authentication is done. Username must still exists in `auth_file`.
any::
- Like trust but username given is ignored. Requires that all databases
- have configured to log in as specific user.
+ Like `trust` but username given is ignored. Requires that all databases
+ have configured to log in as specific user.
==== pool_mode ====
=== Connection sanity checks, timeouts ===
+==== server_reset_query ====
+
+Query send to server on connection release, before making it
+available to other clients. At that moment no transaction is in
+progress so it should not include `ABORT` or `ROLLBACK`.
+
+Good choice for 8.2 and below is:
+
+ server_reset_query = RESET ALL; SET SESSION AUTHORIZATION DEFAULT;
+
+for 8.3 and above its enough to do:
+
+ server_reset_query = DISCARD ALL;
+
==== server_check_delay ====
How long to keep released immidiately available, without running sanity-check
They allow setting default parameters on server connection.
-Note that since version 1.1 PgBouncer honours client
-changes for there values, so their use in pgbouncer.ini
-is deprecated.
+Note that since version 1.1 PgBouncer tracks client
+changes for their values, so their use in pgbouncer.ini
+is deprecated now.
==== client_encoding ====
--- /dev/null
+
+= PgBouncer FAQ =
+
+== How to load-balance queries between several servers? ==
+
+Use a TCP connection load-balancer. Either http://www.linuxvirtualserver.org/[LVS]
+or http://haproxy.1wt.eu/[HAProxy] seem to be good choices. On PgBouncer
+side it may be good idea to make `server_lifetime` smaller and also
+turn `server_round_robin` on - by default idle connections are
+reused by LIFO algorithm which may work not so well when
+load-balancing is needed.
+
+
+== How to use SSL connections with PgBouncer? ==
+
+Use http://www.stunnel.org/[Stunnel]. Only problem is that
+Stunnel (as of v4.21) does not support PostgreSQL SSL handshake
+at the beginnning of connection. Solution is to use either
+Stunnel on both sides of connection or to apply
+following patch to Stunnel -
+http://pgbouncer.projects.postgresql.org/patches/stunnel-postgres.diff[stunnel-postgres.diff]
+- that adds PostgreSQL protocol support to it (specified as `protocol=pgsql`).
+
+
+== How to use prepared statements with PgBouncer? ==
+
+These tricks are mostly needed for JDBC which just loves them.
+
+=== Session pooling with PostgreSQL 8.3 and newer ===
+
+This is easy - just set `server_reset_query = DISCARD ALL;`
+or at least to `DEALLOCATE ALL;`
+
+=== Session pooling with PostgreSQL 8.2 and older ===
+
+This is problematic as older versions of PostgreSQL do not allow
+easy way to drop prepared statements. Luckily there is system
+view that shows prepared plans in current session. So as a workaround
+following function can be created:
+
+ CREATE OR REPLACE FUNCTION deallocate_all()
+ RETURNS void AS $$
+ DECLARE
+ sql text;
+ BEGIN
+ FOR sql IN
+ SELECT 'deallocate ' || quote_ident(name)
+ FROM pg_catalog.pg_prepared_statements
+ LOOP
+ EXECUTE sql;
+ END LOOP;
+ END;
+ $$ LANGUAGE plpgsql;
+
+Then the `server_reset_query` can be set to call it:
+
+ server_reset_query = RESET ALL; SET SESSION AUTHORIZATION DEFAULT; SELECT deallocate_all();
+
+
+=== Transaction pooling ===
+
+To make prepared statements work in this mode would need PgBouncer
+to keep track of them internally, which it does not do. So only way to
+keep using PgBouncer in this mode is to disable prepared statements
+completely.
+
+For JDBC this seems to be achieved by adding `protocolVersion=2`
+parameter to connect string.
+
+
+== How to upgrade PgBouncer without dropping connections? ==
+
+This is as easy as launching new PgBouncer process with `-R` switch
+and same config:
+
+ $ pgbouncer -R -d config.ini
+
+The `-R` (reboot) switch makes new process connect to console
+of the old process (dbname=pgbouncer), issue following commands:
+
+ SUSPEND;
+ SHOW FDS;
+ SHUTDOWN;
+
+After that if new one notices old one gone it resumes work with
+old connections. The magic happens during `SHOW FDS` command which
+transports actual file descriptors to new process.
+
+If the takeover does not work for whatever reason, the new process
+can be simply killed, old one notices this and resumes work.
+
+
Transaction pooling::
Server connection is assigned to client only during a transaction.
- When PgBouncer notices that transaction is over, the server
+ When !PgBouncer notices that transaction is over, the server
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
"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.
+ to the fact that !PgBouncer does not need to see full packet at once.
* It is not tied to one backend server, the destination databases can
reside on different hosts.
== Docs ==
- * Detailed usage info: [http://pgbouncer.projects.postgresql.org/doc/usage.html usage.html]
- * Config file help: [http://pgbouncer.projects.postgresql.org/doc/config.html config.html]
- * TODO list: [http://pgbouncer.projects.postgresql.org/doc/todo.html todo.html]
+ * [http://pgbouncer.projects.postgresql.org/doc/usage.html Usage documentation]
+ * [http://pgbouncer.projects.postgresql.org/doc/config.html Config file documentation]
+ * [http://pgbouncer.projects.postgresql.org/doc/todo.html TODO list]
+ * [http://pgbouncer.projects.postgresql.org/doc/faq.html FAQ]:
+ Load-balancing, SSL, prepared statements, online restart.
-== Feature map ==
+== SQL feature map for pooling modes ==
Following table list various PostgreSQL features and whether they are
-compatible with PgBouncer pooling modes. Note that 'transaction'
+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.
|| LOAD statement || Yes || Never ||
* [0] - Startup parameters are: `client_encoding`, `datestyle`, `timezone`
- and `standard_conforming_strings`. PgBouncer can detect their changes
+ 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.
+ 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: 10/20/2007
+.\" Date: 11/04/2007
.\" Manual:
.\" Source:
.\"
-.TH "PGBOUNCER" "1" "10/20/2007" "" ""
+.TH "PGBOUNCER" "1" "11/04/2007" "" ""
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.\" Title: pgbouncer
.\" Author:
.\" Generator: DocBook XSL Stylesheets v1.71.1 <http://docbook.sf.net/>
-.\" Date: 10/20/2007
+.\" Date: 11/21/2007
.\" Manual:
.\" Source:
.\"
-.TH "PGBOUNCER" "5" "10/20/2007" "" ""
+.TH "PGBOUNCER" "5" "11/21/2007" "" ""
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.br
\fBlogfile\fR
.RS
-Specifies log file. Logging is done by open/write/close, so it can be safely rotasted, without informing pooler.
+Specifies log file. Log file is kept open so after rotation kill \-HUP or on console RELOAD; should be done.
.sp
Default: not set.
.sp
.br
\fBlisten_addr\fR
.RS
-Specifies IPv4 address, where to listen for TCP connections. Or "*" meaning \fIlisten on all addresses\fR. When not set, only unix socket connections are allowed.
+Specifies IPv4 address, where to listen for TCP connections. Or * meaning "listen on all addresses". When not set, only unix socket connections are allowed.
.sp
-Default: not set.
+Default: not set
.sp
.RE
.sp
.PP
md5
.RS 4
-Use MD5\-based password check. auth_file may contain both md5\-encrypted or plain\-text passwords. Default.
+Use MD5\-based password check.
+auth_file
+may contain both md5\-encrypted or plain\-text passwords. Default.
.RE
.PP
crypt
.RS 4
-Use crypt(3) based bassword check. auth_file must contain plain\-text passwords.
+Use crypt(3) based bassword check.
+auth_file
+must contain plain\-text passwords.
.RE
.PP
plain
.PP
trust
.RS 4
-No authentication is done. Username must still exists in auth_file.
+No authentication is done. Username must still exists in
+auth_file.
.RE
.PP
any
.RS 4
-Like trust but username given is ignored. Requires that all databases have configured to log in as specific user.
+Like
+trust
+but username given is ignored. Requires that all databases have configured to log in as specific user.
.RE
.RE
.sp
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
+\fBserver_reset_query\fR
+.RS
+Query send to server on connection release, before making it available to other clients. At that moment no transaction is in progress so it should not include ABORT or ROLLBACK.
+.sp
+Good choice for 8.2 and below is:
+.sp
+.sp
+.RS 4
+.nf
+server_reset_query = RESET ALL; SET SESSION AUTHORIZATION DEFAULT;
+.fi
+.RE
+.sp
+for 8.3 and above its enough to do:
+.sp
+.sp
+.RS 4
+.nf
+server_reset_query = DISCARD ALL;
+.fi
+.RE
+.RE
+.sp
+.it 1 an-trap
+.nr an-no-space-flag 1
+.nr an-break-flag 1
+.br
\fBserver_check_delay\fR
.RS
How long to keep released immidiately available, without running sanity\-check query on it. If 0 then the query is ran always.
.SS "Extra parameters"
They allow setting default parameters on server connection.
.sp
-Note that since version 1.1 PgBouncer honours client changes for there values, so their use in pgbouncer.ini is deprecated.
+Note that since version 1.1 PgBouncer tracks client changes for their values, so their use in pgbouncer.ini is deprecated now.
.sp
.sp
.it 1 an-trap
== Minor features ==
* suspend_timeout - drop stalled conns
+ * when dest db does not exists, stalled logins can halt suspend
+ fix with suspend_timeout?
* some preliminary notification that fd limit is full
* drop_on_error/keep_on_error - if released conn is in error state,
then issue rollback and keep it
+ * removing db from config and reload; should work
+ * show stalled; command - like show sockets; but filter only active ones
* keep stats about error counts
* auth_conn - access to pg_shadow, so auth_file is not needed
projects / pgbouncer / commitdiff