-*.rst whitespace=-blank-at-eol
-doc/frag-*-man whitespace=-blank-at-eof
test/hba_test.rules -whitespace
test/ssl/TestCA1/certs/*.pem whitespace=-blank-at-eol
test/ssl/TestCA1/sites/*.crt whitespace=-blank-at-eol
test/test.sh whitespace=-blank-at-eol
win32/eventmsg.rc whitespace=-blank-at-eol
-
-# Avoid confusing ASCII underlines with leftover merge conflict markers
-*.rst conflict-marker-size=32
- libevent-dev
- libudns-dev
- lintian
- - python-docutils
+before_install:
+ - wget https://github.com/jgm/pandoc/releases/download/2.4/pandoc-2.4-1-amd64.deb
+ - sudo dpkg -i pandoc-2.4-1-amd64.deb
compiler:
- clang
- gcc
pgbouncer_EMBED_LIBUSUAL = 1
# docs to install as-is
-dist_doc_DATA = README.rst NEWS.rst etc/pgbouncer.ini etc/userlist.txt
+dist_doc_DATA = README.md NEWS.md etc/pgbouncer.ini etc/userlist.txt
DISTCLEANFILES = config.mak config.status lib/usual/config.h config.log
ctags src/*.c include/*.h lib/usual/*.[ch] lib/usual/*/*.[ch]
htmls:
- for f in *.rst doc/*.rst; do \
- mkdir -p html && rst2html $$f > html/`basename $$f`.html; \
+ for f in *.md doc/*.md; do \
+ mkdir -p html && $(PANDOC) $$f -o html/`basename $$f`.html; \
done
doc/pgbouncer.1 doc/pgbouncer.5:
**2018-08-13 - PgBouncer 1.9.0 - "Chaos Survival"**
- Features
-
* RECONNECT command
-
* WAIT_CLOSE command
-
* Fast close - Disconnect a server in session pool mode immediately if
it is in "close_needed" (reconnect) mode.
-
* Add close_needed column to SHOW SERVERS
-
- Fixes
-
* Avoid double-free in parse_filename
* Avoid NULL pointer deref in parse_line
-
- Cleanups
-
* Port mkauth.py to Python 3
-
* Improve signals documentation
-
* Improve quick start documentation
-
* Document SET command
-
* Correct list of required software
-
* Fix -Wimplicit-fallthrough warnings
-
* Add missing documentation for various SHOW fields
-
* Document reconnect behavior on reload and DNS change
-
* Document that KILL requires RESUME afterwards
-
* Clarify documentation of server_lifetime
-
* Typos and capitalization fixes in messages and docs
-
* Fix psql invocation in tests
-
* Various other test setup improvements
PgBouncer 1.8.x
**2017-12-20 - PgBouncer 1.8.1 - "Ground-and-pound Mentality"**
- Fixes
-
* Include file `include/pam.h` into distribution tarball. This
prevented the 1.8 tarball from building at all.
**2017-12-19 - PgBouncer 1.8 - "Confident at the Helm"**
- Features
-
* Support PAM authentication. (Enable with `--with-pam`.)
-
* Add `paused` and `disabled` fields to `SHOW DATABASES` output.
-
* Add `maxwait_us` field to `SHOW POOLS` output.
-
* Add `wait` and `wait_us` fields to `SHOW` commands output.
-
* Add new commands `SHOW STATS_TOTALS` and `SHOW STATS_AVERAGES`.
-
* Track queries and transactions separately in `SHOW STATS`. The
fields `total_requests`, `avg_req`, and
`avg_query` have been replaced by new fields.
-
* Add `wait_time` to `SHOW STATS`.
-
- Fixes
-
* Updated libusual supports OpenSSL 1.1.
-
* Do not attempt to use TLS on Unix sockets.
-
* When parsing `pg_hba.conf`, keep parsing after erroneous lines instead of rejecting the whole file.
- (`#118 <https://github.com/pgbouncer/pgbouncer/issues/118>`_)
-
+ ([#118](https://github.com/pgbouncer/pgbouncer/issues/118))
* Several other hba parsing fixes.
-
* Fix race condition when canceling query.
- (`#141 <https://github.com/pgbouncer/pgbouncer/issues/141>`_)
-
+ ([#141](https://github.com/pgbouncer/pgbouncer/issues/141))
- Cleanups
-
* `auth_user` setting is now also allowed globally, not only per database.
- (`#142 <https://github.com/pgbouncer/pgbouncer/issues/142>`_)
-
+ ([#142](https://github.com/pgbouncer/pgbouncer/issues/142))
* Set console client and server encoding to `UTF8`.
PgBouncer 1.7.x
**2016-02-26 - PgBouncer 1.7.2 - "Finally Airborne"**
- Fixes
-
* Fix crash on stale pidfile removal. Problem introduced in 1.7.1.
-
* Disable cleanup - it breaks takeover and is not useful
for production loads. Problem introduced in 1.7.1.
-
* After takeover, wait until pidfile is gone before booting.
Slow shutdown due to memory cleanup exposed existing race.
- (`#113 <https://github.com/pgbouncer/pgbouncer/issues/113>`_)
-
+ ([#113](https://github.com/pgbouncer/pgbouncer/issues/113))
- Cleanups
-
* Make build reproducible by dropping DBGVER handling.
- (`#112 <https://github.com/pgbouncer/pgbouncer/issues/112>`_)
-
+ ([#112](https://github.com/pgbouncer/pgbouncer/issues/112))
* Antimake: Sort file list from $(wildcard), newer gmake does not
sort it anymore.
- (`#111 <https://github.com/pgbouncer/pgbouncer/issues/111>`_)
-
+ ([#111](https://github.com/pgbouncer/pgbouncer/issues/111))
* Show libssl version in log.
-
* deb: Turn on full hardening.
**2016-02-18 - PgBouncer 1.7.1 - "Forward To Five Friends Or Else"**
instead expected 20-30k. Something to keep an eye on when using TLS.
- Fixes
-
* TLS: Rename sslmode "disabled" to "disable" as that is what
PostgreSQL uses.
-
* TLS: `client_tls_sslmode=verify-ca/-full` now reject
connections without client certificate.
- (`#104 <https://github.com/pgbouncer/pgbouncer/issues/104>`_)
-
+ ([#104](https://github.com/pgbouncer/pgbouncer/issues/104))
* TLS: `client_tls_sslmode=allow/require` do validate client
certificate if sent. Previously they left cert validation
unconfigured so connections with client cert failed.
- (`#105 <https://github.com/pgbouncer/pgbouncer/issues/105>`_)
-
+ ([#105](https://github.com/pgbouncer/pgbouncer/issues/105))
* Fix memleak when freeing database.
-
* Fix potential memleak in tls_handshake().
-
* Fix EOF handling in tls_handshake().
-
* Fix too small memset in asn1_time_parse compat.
-
* Fix non-TLS (`--without-openssl`) build.
- (`#101 <https://github.com/pgbouncer/pgbouncer/issues/101>`_)
-
+ ([#101](https://github.com/pgbouncer/pgbouncer/issues/101))
* Fix various issues with Windows build.
- (`#100 <https://github.com/pgbouncer/pgbouncer/issues/100>`_)
-
+ ([#100](https://github.com/pgbouncer/pgbouncer/issues/100))
- Cleanups
-
* TLS: Use SSL_MODE_RELEASE_BUFFERS to decrease memory usage
of inactive connections.
-
* Clean allocated memory on exit. Helps to run memory-leak checkers.
-
* Improve `server_reset_query` documentation.
- (`#110 <https://github.com/pgbouncer/pgbouncer/issues/110>`_)
-
+ ([#110](https://github.com/pgbouncer/pgbouncer/issues/110))
* Add TLS options to sample config.
**2015-12-18 - PgBouncer 1.7 - "Colors Vary After Resurrection"**
- Features
-
* Support TLS connections. OpenSSL/LibreSSL is used
as backend implementation.
-
* Support authentication via TLS client certificate.
-
* Support "peer" authentication on Unix sockets.
-
* Support Host Based Access control file, like
- `pg_hba.conf <http://www.postgresql.org/docs/9.4/static/auth-pg-hba-conf.html>`_
+ [pg_hba.conf](http://www.postgresql.org/docs/9.4/static/auth-pg-hba-conf.html)
in Postgres. This allows to configure TLS for network connections and "peer"
authentication for local connections.
-
- Cleanups
-
* Set `query_wait_timeout` to 120s by default. Current default
(0) causes infinite queueing, which is not useful. That
means if client has pending query and has not been
assigned to server connection, the client connection will
be dropped.
-
* Disable `server_reset_query_always` by default. Now reset
query is used only in pools that are in session mode.
-
* Increase pkt_buf to 4096 bytes. Improves performance with TLS.
The behaviour is probably load-specific, but it should be
safe to do as since v1.2 the packet buffers are split
from connections and used lazily from pool.
-
* Support pipelining count expected ReadyForQuery packets.
This avoids releasing server too early. Fixes
- `#52 <https://github.com/pgbouncer/pgbouncer/issues/52>`_.
-
+ [#52](https://github.com/pgbouncer/pgbouncer/issues/52).
* Improved sbuf_loopcnt logic - socket is guarateed to be
reprocessed even if there are no event from socket.
Required for TLS as it has it's own buffering.
-
* Adapt system tests to work with modern BSD and MacOS.
(Eric Radman)
-
* Remove **crypt** auth. It's obsolete and not supported
by PostgreSQL since 8.4.
-
* Fix plain "--with-cares" configure option - without argument
it was broken.
**2015-09-03 - PgBouncer 1.6.1 - "Studio Audience Approves"**
- Features
-
* New setting: `server_reset_query_always`. When set,
disables `server_reset_query` use on non-session pools.
PgBouncer introduces per-pool pool_mode, but session-pooling
It is set in 1.6.x, but will be disabled in 1.7.
- Fixes
-
* [SECURITY] Remove invalid assignment of `auth_user`. (#69)
When `auth_user` is set and client asks non-existing username,
client will log in as `auth_user`. Not good.
- `CVE-2015-6817 <https://access.redhat.com/security/cve/cve-2015-6817>`_
+ [CVE-2015-6817](https://access.redhat.com/security/cve/cve-2015-6817)
* Skip NoticeResponce in handle_auth_response. Otherwise verbose
log levels on server cause login failures.
- Cleanups
* log: wrap ipv6 address with []
-
* log: On connect to server, show local ip and port
-
* win32: use gnu-style for long args: --foo
-
* Allow numbers in hostname, always try to parse with inet_pton
-
* Fix deallocate_all() in FAQ
-
* Fix incorrect keyword in example config file
(Magnus Hagander)
-
* Allow comments (with ';') in auth files.
(Guillaume Aubert)
-
* Fix spelling mistakes in log messages and comments.
(Dmitriy Olshevskiy)
* fix launching new connections during maintenance
(Cody Cutrer)
-
* don't load auth file twice at boot
(Cody Cutrer)
-
* Proper invalidation for autodbs
-
* ipv6: Set IPV6_V6ONLY on listen socket.
-
* win32: Don't set SO_REUSEADDR on listen socket.
-
* Fix IPv6 address memcpy
-
* Fix cancellation of of waiting clients.
(Mathieu Fenniak)
-
* Small bug fix, must check calloc result
(Heikki Linnakangas)
-
* Add newline at the end of the PID file
(Peter Eisentraut)
-
* Don't allow new server connections when PAUSE <db> was issued.
(Petr Jelinek)
-
* Fix 'bad packet' during login when header is delayed.
(Michał Trojnara, Marko Kreen)
-
* Fix errors detected by Coverty.
(Euler Taveira)
-
* Disable server_idle_timeout when server count gets below min_pool (#60)
(Marko Kreen)
**2015-04-09 - PgBouncer 1.5.5 - "Play Dead To Win"**
- Fixes
-
* Fix remote crash - invalid packet order causes lookup of NULL
pointer. Not exploitable, just DoS.
**2012-11-28 - PgBouncer 1.5.4 - "No Leaks, Potty-Training Successful"**
- Fixes
-
* DNS: Fix memory leak in getaddrinfo_a() backend.
-
* DNS: Fix memory leak in udns backend.
-
* DNS: Fix stats calculation.
-
* DNS: Improve error message handling for getaddrinfo_a().
-
* Fix win32 compile.
-
* Fix compiler dependency support check in configure.
-
* Few documentation fixes.
**2012-09-12 - PgBouncer 1.5.3 - "Quantum Toaster"**
- by '*' in [databases] section - the database name can come
from network thus making remote shutdown possible.
- `CVE-2012-4575 <https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2012-4575>`_
+ [CVE-2012-4575](https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2012-4575)
- Minor Features
* max_packet_size - config parameter to tune maximum packet size
that is allowed through. Default is kept same: (2G-1), but now
it can be made smaller.
-
* In case of unparseable packet header, show it in hex in log and
error message.
* AntiMake: it used $(relpath) and $(abspath) to manupulate pathnames,
but the result was build failure when source tree path contained
symlinks. The code is now changed to work on plain strings only.
-
* console: now SET can be used to set empty string values.
-
* config.txt: show that all timeouts can be set in floats.
This is well-hidden feature introduced in 1.4.
**2012-05-29 - PgBouncer 1.5.2 - "Don't Chew, Just Swallow"**
- Fixes
-
* Due to mistake, reserve_pool_timeout was taken in microseconds,
not seconds, effectively activating reserve pool immediately
when pool got full. Now use it as seconds, as was intended.
**2012-04-17 - PgBouncer 1.5.1 - "Abort, Retry, Ignore?"**
- Features
-
* Parameters to tune permissions on unix socket:
unix_socket_mode=0777, unix_socket_group=''.
-
- Fixes
-
* Allow empty string for server-side variable - this is
needed to get "application_name" properly working, as it's
the only parameter that does not have server-side default.
-
* If connect string changes, require refresh of server parameters.
Previously PgBouncer continued with old parameters,
which breaks in case of Postgres upgrade.
-
* If autodb connect string changes, drop old connections.
-
* cf_setint: Use strtol() instead atoi() to parse integer config
parameters. It allows hex, octal and better error detection.
-
* Use sigqueue() to detect union sigval existence - fixes
compilation on HPUX.
-
* Remove 'git' command from Makefile, it throws random errors
in case of plain-tarball build.
-
* Document stats_period parameter. This tunes the period for
stats output.
-
* Require Asciidoc >= 8.4, seems docs are not compatible with
earlier versions anymore.
-
* Stop trying to retry on EINTR from close().
**2012-01-05 - PgBouncer 1.5 - "Bouncing Satisified Clients Since 2007"**
GNU Make 3.81+ is required for building.
- Features
-
* Detect DNS reply changes and invalidate connections to IPs no longer
present in latest reply.
(Petr Jelinek)
-
* DNS zone serial based hostname invalidation. When option
dns_zone_check_period is set, all DNS zones will be queried
for SOA, and when serial has changed, all hostnames
connection invalidation, because invalidation on lookup
is useless when no lookups are performed.
Works only with new UDNS backend.
-
* New SHOW DNS_HOSTS, SHOW DNS_ZONES commands to examine DNS cache.
-
* New param: min_pool_size - avoids dropping all connections
when there is no load.
(Filip Rembiałkowski)
-
* idle_in_transaction_timeout - kill transaction if idle too long.
Not set by default.
-
* New libudns backend for DNS lookups. More featureful than evdns.
Use --with-udns to activate. Does not work with IPv6 yet.
-
* KILL command, to immediately kill all connections for one database.
(Michael Tharp)
-
* Move to Antimake build system to have better looking Makefiles.
Now GNU Make 3.81+ is required for building.
-
- Fixes
-
* DNS now works with IPv6 hostnames.
-
* Don't change connection state when NOTIFY arrives from server.
-
* Various documentation fixes.
(Dan McGee)
-
* Console: Support ident quoting with "". Originally we did not
have any commands that took database names, so no quoting was needed.
-
* Console: allow numbers at the stard of word regex. Trying
to use strict parser makes things too complex here.
-
* Don't expire auto DBs that are paused.
(Michael Tharp)
-
* Create auto databases as needed when doing PAUSE.
(Michael Tharp)
-
* Fix wrong log message issued by RESUME command.
(Peter Eisentraut)
-
* When user= without password= is in database connect string,
password will be taken from userlist.
-
* Parse '*' properly in takeover code.
-
* autogen.sh: work with older autoconf/automake.
-
* Fix run-as-service crash on win32 due to bad basename() from
mingw/msvc runtime. Now compat basename() is always used.
Affected OS-es: \*BSD, Solaris, Win32.
- Portability Fixes
-
* Give CFLAGS to linker. Needed when using pthread-based
getaddrinfo_a() fallback.
-
* lib/find_modules.sh: Replace split() with index()+substr().
This should make it work with older AWKs.
-
* <usual/endian.h>: Ignore system htoX/Xtoh defines. There
may be only subset of macros defined.
-
* <usual/signal.h>: Separate compat sigval from compat sigevent
-
* <usual/socket.h>: Include <sys/uio.h> to get iovec
-
* <usual/time.h>: Better function autodetection on win32
-
* <usual/base_win32.h>: Remove duplicate sigval/sigevent declaration
**2011-04-01 - PgBouncer 1.4.1 - "It Was All An Act"**
* Support listening/connect for IPv6 addresses.
(Hannu Krosing)
-
* Multiple listen addresses in 'listen_addr'. For each getaddrinfo()
is called, so names can also be used.
-
* console: Send PgBouncer version as 'server_version' to client.
- Important Fixes
* Make compat getaddrinfo_a() non-blocking, by using single parallel
thread to do lookups.
-
* Enable pthread compilation if compat getaddrinfo_a is used.
-
* release_server missed setting ->last_lifetime_disconnect on lifetime disconnect.
(Emmanuel Courreges)
-
* win32: fix auth file on DOS line endings - load_file() did not take
account of file shringage when loading.
(Rich Schaaf)
-
* <usual/endian.h>: add autoconf detection for enc/dec functions
so it would not create conflicts on BSD.
(James Pye)
-
* Don't crash when config file does not exist.
(Lou Picciano)
-
* Don't crash on DNS lookup failure when logging on noise level (-v -v).
(Hubert Depesz Lubaczewski, Dominique Hermsdorff)
-
* Use backticks instead of $(cmd) in find_modules.sh to make it more portable.
(Lou Picciano)
-
* Use 'awk' instead of 'sed' in find_modules.sh to make it more portable.
(Giorgio Valoti)
-
* Log active async DNS backend info on startup.
-
* Fix --disable-evdns to mean 'no' instead 'yes'.
-
* Mention in docs that -R requires unix_socket_dir.
-
* Discuss server_reset_query in faq.txt.
-
* Restore lost memset in slab allocator
-
* Various minor portability fixes in libusual.
**2011-01-11 - PgBouncer 1.4 - "Gore Code"**
- Fixes
* DateStyle and TimeZone server params need to use exact case.
-
* Console: send datetime, timezone and stdstr server params to client.
- Internal cleanups
* Use libusual library for low-level utility functions.
-
* Remove fixed-length limit from server params.
PgBouncer 1.3.x
**2010-09-09 - PgBouncer 1.3.4 - "Bouncer is always right"**
- Fixes
-
* Apply fast-fail logic at connect time. So if server is failing,
the clients get error when connecting.
-
* Don't tag automatically generated databases for checking on reload time,
otherwise they get killed, because they don't exist in config.
-
* Ignore application_name parameter by default. This avoids the need
for all Postgres 9.0 users to add it into ignore_startup_parameters=
themselves.
-
* Correct pg_auth quoting. '\' is not used there.
-
* Better error reporting on console, show incoming query to user.
-
* Support OS'es (OpenBSD) where tv_sec is not time_t.
-
* Avoid too noisy warnings on gcc 4.5.
**2010-05-10 - PgBouncer 1.3.3 - "NSFW"**
- Improvements
-
* Make listen(2) argument configurable: listen_backlog. This is
useful on OS'es, where system max allowed is configurable.
-
* Improve disconnect messages to show what username or dbname caused
login to fail.
-
- Fixes
-
* Move fast-fail relaunch logic around. Old one was annoying in case of
permanently broken databases or users, by trying to retry even if
there is no clients who want to login.
-
* Make logging functions keep old errno, otherwise pgbouncer may act funny
on higher loglevels and logging problems.
-
* Increase the size of various startup-related buffers to handle
EDB more noisy startup.
-
* Detect V2 protocol startup request and give clear reason for disconnect.
**2010-03-15 - PgBouncer 1.3.2 - "Boomerang Bullet"**
**2009-07-06 - PgBouncer 1.3.1 - "Now fully conforming to NSA monitoring requirements"**
- Fixes
-
* Fix problem with sbuf_loopcnt which could make connections hang.
If query or result length is nearby of multiple of (pktlen*sbuf_loopcnt)
[10k by default], it could stay waiting for more data which will not
appear.
-
* Make database reconfigure immediate. Currently old connections
could be reused after SIGHUP.
-
* Fix SHOW DATABASES which was broken due to column addition.
-
* Console access was disabled when "auth_type=any" as pgbouncer dropped username.
Fix: if "auth_type=any", allow any user to console as admin.
-
* Fix bad CUSTOM_ALIGN macro. Luckily it's unused if OS already
defines ALIGN macro thus seems the bug has not happened in wild.
-
* win32: call WSAStartup() always, not only in daemon mode
as config parsing wants to resolve hosts.
-
* win32: put quotes around config filename in service
cmdline to allow spaces in paths. Executable path
does not seem to need it due to some win32 magic.
-
* Add STATS to SHOW HELP text.
-
* doc/usage.txt: the time units in console results are in
microseconds, not milliseconds.
PgBouncer runs on Windows 2000+ now. Command line usage stays same,
except it cannot run as daemon and cannot do online reboot.
- To run as service, define parameter service_name in config. Then::
+ To run as service, define parameter service_name in config. Then:
- > pgbouncer.exe config.ini -regservice
- > net start SERVICE_NAME
+ > pgbouncer.exe config.ini -regservice
+ > net start SERVICE_NAME
- To stop and unregister::
+ To stop and unregister:
- > net stop SERVICE_NAME
- > pgbouncer.exe config.ini -unregservice
+ > net stop SERVICE_NAME
+ > pgbouncer.exe config.ini -unregservice
- To use Windows Event Log, event DLL needs to be registered first::
+ To use Windows Event Log, event DLL needs to be registered first:
- > regsrv32 pgbevent.dll
+ > regsrv32 pgbevent.dll
Afterwards you can set "syslog = 1" in config.
**2008-08-08 - PgBouncer 1.2.3 - "Carefully Selected Bytes"**
- Fixes
-
* Disable SO_ACCEPTFILTER code for BSDs which did not work.
* Include example etc/userlist.txt in tgz.
* Use '$(MAKE)' instead 'make' for recursion (Jørgen Austvik)
**2008-08-06 - PgBouncer 1.2.2 - "Barf-bag Included"**
- Fixes
-
* Remove 'drop_on_error', it was a bad idea. It was added as workaround
for broken plan cache behaviour in Postgres, but can cause damage
in common case when some queries always return error.
**2008-08-04 - PgBouncer 1.2.1 - "Waterproof"**
- Features
-
* New parameter 'drop_on_error' - if server throws error the connection
will not be reused but dropped after client finished with it. This is
needed to refresh plan cache. Automatic refresh does not work even in 8.3.
Defaults to 1.
-
- Fixes
-
* SHOW SOCKETS/CLIENTS/SERVERS: Don't crash if socket has no buffer.
* Fix infinite loop on SUSPEND if suspend_timeout triggers.
-
- Minor cleanups
-
* Use <sys/uio.h> for 'struct iovec'.
* Cancel shutdown (from SIGINT) on RESUME/SIGUSR2,
otherwise it will trigger on next PAUSE.
**2007-12-10 - PgBouncer 1.1.2 - "The Hammer"**
- Features
-
* Disconnects because of server_lifetime are now separated by
(server_lifetime / pool_size) seconds. This avoids pgbouncer
causing reconnect floods.
-
- Fixes
-
* Online upgrade 1.0 -> 1.1 problems:
-
- 1.0 does not track server parameters, so they stay NULL
but 1.1 did not expect it and crashed.
-
- If server params are unknown, but client ones are set,
then issue a SET for them, instead complaining.
-
* Remove temp debug statements that were accidentally left
in code on INFO level, so they polluted logs.
-
* Unbroke debian/changelog
-
- Cleanup
-
* reorder struct SBuf fields to get better alignment for buffer.
**2007-10-26 - PgBouncer 1.1.1 - "Breakdancing Bee"**
- Fixes
-
* Server parameter cache could stay uninitialized, which caused
unnecessary SET of them. This caused problem on 8.1 which
does not allow touching standard_conforming_strings.
(Thanks to Dimitri Fontaine for report & testing.)
-
* Some doc fixes.
-
* Include doc/fixman.py in .tgz.
**2007-10-09 - PgBouncer 1.1 - "Mad-Hat Toolbox"**
- Features
- * Keep track of following server parameters::
+ * Keep track of following server parameters:
- client_encoding datestyle, timezone, standard_conforming_strings
+ client_encoding datestyle, timezone, standard_conforming_strings
* Database connect string enhancements:
**2007-06-18 - PgBouncer 1.0.8 - "Undead Shovel Jutsu"**
- Fixes
-
* Fix crash in cancel packet handling. (^C from psql)
-
- Features
-
* PAUSE <db>; RESUME <db>; works now.
* Cleanup of console command parsing.
* Disable expensive in-list assert check.
**2007-04-19 - PgBouncer 1.0.7 - "With Vitamin A-Z"**
- Fixes
-
* Several error/notice packets with send() blocking between
triggered assert. Fix it by removing flushing logic altogether.
As pgbouncer does not actively buffer anything, its not needed.
**2007-04-12 - PgBouncer 1.0.6 - "Daily Dose"**
- Fixes
-
* The "Disable maintenance during the takeover" fix could
disable maintenance altogether. Fix it.
* Compilation fix for FreeBSD, <sys/ucred.h> requires <sys/param.h> there.
**2007-04-11 - PgBouncer 1.0.5 - "Enough for today"**
- Fixes
-
* Fix online-restart bugs:
- Set ->ready for idle servers.
- Remove obsolete code from use_client_socket()
**2007-04-11 - PgBouncer 1.0.4 - "Last 'last' bug"**
- Fixes
-
* Notice from idle server tagged server dirty.
release_server() did not expect it. Fix it
by dropping them.
**2007-04-11 - PgBouncer 1.0.3 - "Fearless Fork"**
- Fixes
-
* Some error handling was missing in login path, so dying
connection there could trigger asserts.
* Cleanup of asserts in sbuf.c to catch problems earlier.
* Create core when Assert() triggers.
- New stuff
-
* New config vars: log_connections, log_disconnections,
log_pooler_errors to turn on/off noise.
* Config var: client_login_timeout to kill dead connections
**2007-03-28 - PgBouncer 1.0.2 - "Supersonic Spoon"**
- Fixes
-
* libevent may report a deleted event inside same loop.
Avoid socket reuse for one loop.
* release_server() from disconnect_client() didnt look
**2007-03-15 - PgBouncer 1.0.1 - "Alien technology"**
- Fixes
-
* Mixed usage of cached and non-cached time, plus unsiged usec_t typedef
created spurious query_timeout errors.
* Fix rare case when socket woken up from send-wait could stay stalling.
* Delay server release until everything is guaranteed to be sent.
- Features
-
* SHOW SOCKETS command to have detailed info about state state.
* Put PgSocket ptr to log, to help tracking one connection.
* In console, allow SELECT in place of SHOW.
Lightweight connection pooler for PostgreSQL.
-Homepage
- https://pgbouncer.github.io
+Homepage: <https://pgbouncer.github.io>
-Sources, bugtracking
- https://github.com/pgbouncer/pgbouncer
+Sources, bugtracking: <https://github.com/pgbouncer/pgbouncer>
Building
---------
PgBouncer depends on few things to get compiled:
-* `GNU Make`_ 3.81+
-* libevent_ 2.0
-* `pkg-config`_
-* (optional) OpenSSL_ 1.0.1 for TLS support.
-* (optional) `c-ares`_ as alternative to libevent's evdns.
+* [GNU Make] 3.81+
+* [libevent] 2.0
+* [pkg-config]
+* [OpenSSL] 1.0.1 for TLS support.
+* (optional) [c-ares] as alternative to libevent's evdns.
-.. _GNU Make: https://www.gnu.org/software/make/
-.. _libevent: http://libevent.org/
-.. _`pkg-config`: https://www.freedesktop.org/wiki/Software/pkg-config/
-.. _OpenSSL: https://www.openssl.org/
-.. _`c-ares`: http://c-ares.haxx.se/
+[GNU Make]: https://www.gnu.org/software/make/
+[libevent]: http://libevent.org/
+[pkg-config]: https://www.freedesktop.org/wiki/Software/pkg-config/
+[OpenSSL]: https://www.openssl.org/
+[c-ares]: http://c-ares.haxx.se/
-When dependencies are installed just run::
+When dependencies are installed just run:
$ ./configure --prefix=/usr/local --with-libevent=libevent-prefix
$ make
async DNS implementation. Following list shows supported backends
and their probing order:
-+----------------------------+----------+-----------+------------+----------------+---------------------------------------+
| backend | parallel | EDNS0 (1) | /etc/hosts | SOA lookup (2) | note |
-+============================+==========+===========+============+================+=======================================+
+|----------------------------|----------|-----------|------------|----------------|---------------------------------------|
| c-ares | yes | yes | yes | yes | ipv6+CNAME buggy in <=1.10 |
-+----------------------------+----------+-----------+------------+----------------+---------------------------------------+
| udns | yes | yes | no | yes | ipv4-only |
-+----------------------------+----------+-----------+------------+----------------+---------------------------------------+
| evdns, libevent 2.x | yes | no | yes | no | does not check /etc/hosts updates |
-+----------------------------+----------+-----------+------------+----------------+---------------------------------------+
| getaddrinfo_a, glibc 2.9+ | yes | yes (3) | yes | no | N/A on non-linux |
-+----------------------------+----------+-----------+------------+----------------+---------------------------------------+
| getaddrinfo, libc | no | yes (3) | yes | no | N/A on win32, requires pthreads |
-+----------------------------+----------+-----------+------------+----------------+---------------------------------------+
| evdns, libevent 1.x | yes | no | no | no | buggy |
-+----------------------------+----------+-----------+------------+----------------+---------------------------------------+
1. EDNS0 is required to have more than 8 addresses behind one hostname.
2. SOA lookup is needed to re-check hostnames on zone serial change
Building PgBouncer from Git requires that you fetch libusual
submodule and generate the header and config files before
-you can run configure::
+you can run configure:
$ git clone https://github.com/pgbouncer/pgbouncer.git
$ cd pgbouncer
$ make
$ make install
-Additional packages required: autoconf, automake, libtool, python-docutils
+Additional packages required: autoconf, automake, libtool, pandoc
Building for WIN32
------------------
and Visual $ANYTHING are untested. Libevent 2.x is required
for DNS hostname lookup.
-Then do the usual::
+Then do the usual:
$ ./configure ...
$ make
-If cross-compiling from Unix::
+If cross-compiling from Unix:
$ ./configure --host=i586-mingw32msvc ...
-R (reboot) and -u (switch user) switches will not work.
To run pgbouncer as a Windows service, you need to configure
-`service_name` parameter to set name for service. Then::
+`service_name` parameter to set name for service. Then:
$ pgbouncer -regservice config.ini
-To uninstall service::
+To uninstall service:
$ pgbouncer -unregservice config.ini
To use Windows Event Log, set "syslog = 1" in config file.
-But before you need to register pgbevent.dll::
+But before you need to register pgbevent.dll:
$ regsvr32 pgbevent.dll
-To unregister it, do::
+To unregister it, do:
- $ regsvr32 /u pgbevent.dll
+ $ regsvr32 /u pgbevent.dll
TLS_LDFLAGS = @TLS_LDFLAGS@
TLS_LIBS = @TLS_LIBS@
-RST2MAN = @RST2MAN@
+PANDOC = @PANDOC@
DLLWRAP = @DLLWRAP@
DLLTOOL = @DLLTOOL@
WINDRES = @WINDRES@
PKG_PROG_PKG_CONFIG
-dnl check for rst2man
-AC_CHECK_PROGS(RST2MAN, rst2man, rst2man)
+AC_CHECK_PROGS(PANDOC, pandoc, pandoc)
dnl check for windows tools
if test "$PORTNAME" = "win32"; then
Priority: extra
Maintainer: Marko Kreen <markokr@gmail.com>
Standards-Version: 3.6.2
-Build-Depends: debhelper (>= 9), make (>= 3.81), python-docutils,
+Build-Depends: debhelper (>= 9), make (>= 3.81), pandoc (>= 2.0),
libevent-dev (>= 2.0), libssl-dev (>= 1.0.1), libc-ares-dev (>= 1.7.0)
Package: pgbouncer
dist_man_MANS = $(manpages)
-EXTRA_DIST = config.rst usage.rst Makefile $(manpages) \
- frag-config-man frag-usage-man
+EXTRA_DIST = config.md usage.md Makefile $(manpages) \
+ frag-config-man.md frag-usage-man.md
# make maintainer-clean removes those
MAINTAINERCLEANFILES = $(manpages)
include $(abs_top_srcdir)/lib/mk/antimake.mk
-pgbouncer.1: usage.rst frag-usage-man
- $(SED) -e '4r frag-usage-man' usage.rst | $(RST2MAN) --exit-status=2 > $@
+pgbouncer.1: frag-usage-man.md usage.md
+ $(PANDOC) --lua-filter=filter.lua -s -t man -o $@ $^
-pgbouncer.5: config.rst frag-config-man
- $(SED) -e '4r frag-config-man' config.rst | $(RST2MAN) --exit-status=2 > $@
+pgbouncer.5: frag-config-man.md config.md
+ $(PANDOC) --lua-filter=filter.lua -s -t man -o $@ $^
web:
make -C ../../pgbouncer.github.io
+# pgbouncer.ini
-pgbouncer.ini
-#############
-Description
-===========
+## Description
The configuration file is in "ini" format. Section names are between "[" and "]". Lines
starting with ";" or "#" are taken as comments and ignored. The characters ";"
and "#" are not recognized when they appear later in the line.
-Generic settings
-================
+## Generic settings
-logfile
--------
+### logfile
-Specifies log file. Log file is kept open so after rotation ``kill -HUP``
-or on console ``RELOAD;`` should be done.
+Specifies log file. Log file is kept open so after rotation `kill -HUP`
+or on console `RELOAD;` should be done.
Note: On Windows machines, the service must be stopped and started.
Default: not set.
-pidfile
--------
+### pidfile
Specifies the pid file. Without a pidfile, daemonization is not allowed.
Default: not set.
-listen_addr
------------
+### listen_addr
Specifies list of addresses, where to listen for TCP connections.
-You may also use ``*`` meaning "listen on all addresses". When not set,
+You may also use `*` meaning "listen on all addresses". When not set,
only Unix socket connections are allowed.
Addresses can be specified numerically (IPv4/IPv6) or by name.
Default: not set
-listen_port
------------
+### listen_port
Which port to listen on. Applies to both TCP and Unix sockets.
Default: 6432
-unix_socket_dir
----------------
+### unix_socket_dir
Specifies location for Unix sockets. Applies to both listening socket and
server connections. If set to an empty string, Unix sockets are disabled.
Default: /tmp
-unix_socket_mode
-----------------
+### unix_socket_mode
File system mode for Unix socket.
Default: 0777
-unix_socket_group
------------------
+### unix_socket_group
Group name to use for Unix socket.
Default: not set
-user
-----
+### user
If set, specifies the Unix user to change to after startup. Works only if
PgBouncer is started as root or if it's already running as given user.
Default: not set
-auth_file
----------
+### auth_file
The name of the file to load user names and passwords from. See
-section `Authentication file format`_ below about details.
+section [Authentication file format](#authentication-file-format) below about details.
Default: not set.
+### auth_hba_file
-auth_hba_file
--------------
-
-HBA configuration file to use when `auth_type`_ is ``hba``.
+HBA configuration file to use when `auth_type` is `hba`.
Supported from version 1.7 onwards.
Default: not set
-auth_type
----------
+### auth_type
How to authenticate users.
pam
- PAM is used to authenticate users, `auth_file`_ is ignored. This method is not
- compatible with databases using `auth_user`_ option. Service name reported to
+: PAM is used to authenticate users, `auth_file` is ignored. This method is not
+ compatible with databases using `auth_user` option. Service name reported to
PAM is "pgbouncer". Also, `pam` is still not supported in HBA configuration file.
hba
- Actual auth type is loaded from `auth_hba_file`_. This allows different
+: Actual auth type is loaded from `auth_hba_file`. This allows different
authentication methods different access paths. Example: connection
- over Unix socket use ``peer`` auth method, connection over TCP
+ over Unix socket use `peer` auth method, connection over TCP
must use TLS. Supported from version 1.7 onwards.
cert
- Client must connect over TLS connection with valid client cert.
+: Client must connect over TLS connection with valid client cert.
Username is then taken from CommonName field from certificate.
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. This is the default authentication method.
plain
- Clear-text password is sent over wire. Deprecated.
+: Clear-text password is sent over wire. Deprecated.
trust
- No authentication is done. Username must still exist in `auth_file`_.
+: No authentication is done. Username must still exist in `auth_file`.
any
- Like the ``trust`` method, but the username given is ignored. Requires that all
+: Like the `trust` method, but the username given is ignored. Requires that all
databases are configured to log in as specific user. Additionally, the console
database allows any user to log in as admin.
-auth_query
-----------
+### auth_query
Query to load user's password from database.
Note that the query is run inside target database, so if a function
is used it needs to be installed into each database.
-Default: ``SELECT usename, passwd FROM pg_shadow WHERE usename=$1``
-
-.. _auth_user:
+Default: `SELECT usename, passwd FROM pg_shadow WHERE usename=$1`
-auth_user
----------
+### auth_user
-If ``auth_user`` is set, any user not specified in auth_file will be
-queried through the ``auth_query`` query from pg_shadow in the database
-using ``auth_user``. Auth_user's password will be taken from ``auth_file``.
+If `auth_user` is set, any user not specified in auth_file will be
+queried through the `auth_query` query from pg_shadow in the database
+using `auth_user`. Auth_user's password will be taken from `auth_file`.
Direct access to pg_shadow requires admin rights. It's preferable to
use non-admin user that calls SECURITY DEFINER function instead.
Default: not set.
-pool_mode
----------
+### pool_mode
Specifies when a server connection can be reused by other clients.
session
- Server is released back to pool after client disconnects. Default.
+: Server is released back to pool after client disconnects. Default.
transaction
- Server is released back to pool after transaction finishes.
+: Server is released back to pool after transaction finishes.
statement
- Server is released back to pool after query finishes. Long transactions
+: Server is released back to pool after query finishes. Long transactions
spanning multiple statements are disallowed in this mode.
-max_client_conn
----------------
+### max_client_conn
Maximum number of client connections allowed. When increased then the file
descriptor limits should also be increased. Note that actual number of file
-descriptors used is more than max_client_conn. Theoretical maximum used is::
+descriptors used is more than 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 its own username to server. If a database user
is specified in connect string (all users connect under same username),
-the theoretical maximum is::
+the theoretical maximum is:
- max_client_conn + (max pool_size * total databases)
+ max_client_conn + (max pool_size * total databases)
The theoretical maximum should be never reached, unless somebody deliberately
crafts special load for it. Still, it means you should set the number of
file descriptors to a safely high number.
-Search for ``ulimit`` in your favorite shell man page.
-Note: ``ulimit`` does not apply in a Windows environment.
+Search for `ulimit` in your favorite shell man page.
+Note: `ulimit` does not apply in a Windows environment.
Default: 100
-default_pool_size
------------------
+### default_pool_size
How many server connections to allow per user/database pair. Can be overridden in
the per-database configuration.
Default: 20
-min_pool_size
--------------
+### min_pool_size
Add more server connections to pool if below this number.
Improves behavior when usual load comes suddenly back after period
Default: 0 (disabled)
-reserve_pool_size
------------------
+### reserve_pool_size
How many additional connections to allow to a pool. 0 disables.
Default: 0 (disabled)
-reserve_pool_timeout
---------------------
+### reserve_pool_timeout
If a client has not been serviced in this many seconds, pgbouncer enables
use of additional connections from reserve pool. 0 disables.
Default: 5.0
-max_db_connections
-------------------
+### max_db_connections
Do not allow more than this many connections per-database (regardless of pool - i.e.
user). It should be noted that when you hit the limit, closing a client connection
Default: unlimited
-max_user_connections
---------------------
+### max_user_connections
Do not allow more than this many connections per-user (regardless of pool - i.e.
user). It should be noted that when you hit the limit, closing a client connection
Once the server connection closes (due to idle timeout), a new server connection
will immediately be opened for the waiting pool.
-server_round_robin
-------------------
+### server_round_robin
By default, pgbouncer reuses server connections in LIFO (last-in, first-out) manner,
so that few connections get the most load. This gives best performance if you have
Default: 0
-ignore_startup_parameters
--------------------------
+### ignore_startup_parameters
By default, PgBouncer allows only parameters it can keep track of in startup
-packets - ``client_encoding``, ``datestyle``, ``timezone`` and ``standard_conforming_strings``.
+packets - `client_encoding`, `datestyle`, `timezone` and `standard_conforming_strings`.
All others parameters will raise an error. To allow others parameters, they can be
specified here, so that pgbouncer knows that they are handled by admin and it can ignore them.
Default: empty
-disable_pqexec
---------------
+### disable_pqexec
Disable Simple Query protocol (PQexec). Unlike Extended Query protocol, Simple Query
allows multiple queries in one packet, which allows some classes of SQL-injection
Default: 0
-application_name_add_host
--------------------------
+### application_name_add_host
Add the client host address and port to the application name setting set on connection start.
This helps in identifying the source of bad queries etc. This logic applies
Default: 0
-conffile
---------
+### conffile
Show location of current config file. Changing it will make PgBouncer use another
-config file for next ``RELOAD`` / ``SIGHUP``.
+config file for next `RELOAD` / `SIGHUP`.
Default: file from command line.
-service_name
-------------
+### service_name
Used on win32 service registration.
Default: pgbouncer
-job_name
---------
+### job_name
-Alias for `service_name`_.
+Alias for `service_name`.
-Log settings
-============
+## Log settings
-syslog
-------
+### syslog
Toggles syslog on/off
As for windows environment, eventlog is used instead.
Default: 0
-syslog_ident
-------------
+### syslog_ident
Under what name to send logs to syslog.
Default: pgbouncer (program name)
-syslog_facility
----------------
+### syslog_facility
Under what facility to send logs to syslog.
-Possibilities: ``auth``, ``authpriv``, ``daemon``, ``user``, ``local0-7``.
+Possibilities: `auth`, `authpriv`, `daemon`, `user`, `local0-7`.
Default: daemon
-log_connections
----------------
+### log_connections
Log successful logins.
Default: 1
-log_disconnections
-------------------
+### log_disconnections
Log disconnections with reasons.
Default: 1
-log_pooler_errors
------------------
+### log_pooler_errors
Log error messages pooler sends to clients.
Default: 1
-stats_period
-------------
+### stats_period
Period for writing aggregated stats into log.
Default: 60
-verbose
--------
+### verbose
Increase verbosity. Mirrors "-v" switch on command line.
Using "-v -v" on command line is same as `verbose=2` in config.
Default: 0
-Console access control
-======================
+## Console access control
-admin_users
------------
+### admin_users
Comma-separated list of database users that are allowed to connect and
-run all commands on console. Ignored when `auth_type`_ is ``any``,
+run all commands on console. Ignored when `auth_type` is `any`,
in which case any username is allowed in as admin.
Default: empty
-stats_users
------------
+### stats_users
Comma-separated list of database users that are allowed to connect and
run read-only queries on console. That means all SHOW commands except
Default: empty.
-Connection sanity checks, timeouts
-==================================
+## Connection sanity checks, timeouts
-server_reset_query
-------------------
+### server_reset_query
Query sent 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``.
+progress so it should not include `ABORT` or `ROLLBACK`.
The query is supposed to clean any changes made to database session
so that next client gets connection in well-defined state. Default is
-``DISCARD ALL`` which cleans everything, but that leaves next client
-no pre-cached state. It can be made lighter, e.g. ``DEALLOCATE ALL``
+`DISCARD ALL` which cleans everything, but that leaves next client
+no pre-cached state. It can be made lighter, e.g. `DEALLOCATE ALL`
to just drop prepared statements, if application does not break when
some state is kept around.
-When transaction pooling is used, the `server_reset_query`_ is not used,
+When transaction pooling is used, the `server_reset_query` is not used,
as clients must not use any session-based features as each transaction
ends up in different connection and thus gets different session state.
Default: DISCARD ALL
-server_reset_query_always
--------------------------
+### server_reset_query_always
-Whether `server_reset_query`_ should be run in all pooling modes. When this
-setting is off (default), the `server_reset_query`_ will be run only in pools
+Whether `server_reset_query` should be run in all pooling modes. When this
+setting is off (default), the `server_reset_query` will be run only in pools
that are in sessions-pooling mode. Connections in transaction-pooling mode
should not have any need for reset query.
Default: 0
-server_check_delay
-------------------
+### server_check_delay
How long to keep released connections available for immediate re-use, without running
sanity-check queries on it. If 0 then the query is ran always.
Default: 30.0
-server_check_query
-------------------
+### server_check_query
Simple do-nothing query to check if the server connection is alive.
Default: SELECT 1;
-server_fast_close
------------------
+### server_fast_close
Disconnect a server in session pooling mode immediately or after the
end of the current transaction if it is in "close_needed" mode (set by
Default: 0
-server_lifetime
----------------
+### server_lifetime
The pooler will close an unused server connection that has been connected longer
than this. Setting it to 0 means the connection is to be used only once,
Default: 3600.0
-server_idle_timeout
--------------------
+### server_idle_timeout
If a server connection has been idle more than this many seconds it will be dropped.
If 0 then timeout is disabled. [seconds]
Default: 600.0
-server_connect_timeout
-----------------------
+### server_connect_timeout
If connection and login won't finish in this amount of time, the connection
will be closed. [seconds]
Default: 15.0
-server_login_retry
-------------------
+### server_login_retry
If login failed, because of failure from connect() or authentication that
pooler waits this much before retrying to connect. [seconds]
Default: 15.0
-client_login_timeout
---------------------
+### client_login_timeout
If a client connects but does not manage to login in this amount of time, it
will be disconnected. Mainly needed to avoid dead connections stalling
Default: 60.0
-autodb_idle_timeout
--------------------
+### autodb_idle_timeout
If the automatically created (via "*") database pools have
been unused this many seconds, they are freed. The negative
Default: 3600.0
-dns_max_ttl
------------
+### dns_max_ttl
How long the DNS lookups can be cached. If a DNS lookup returns
several answers, pgbouncer will robin-between them in the meantime.
Default: 15.0
-dns_nxdomain_ttl
-----------------
+### dns_nxdomain_ttl
How long error and NXDOMAIN DNS lookups can be cached. [seconds]
Default: 15.0
-
-dns_zone_check_period
----------------------
+### dns_zone_check_period
Period to check if zone serial has changed.
are looked up again. If any host IP changes, its connections
are invalidated.
-Works only with UDNS and c-ares backends (``--with-udns`` or ``--with-cares`` to configure).
+Works only with UDNS and c-ares backends (`--with-udns` or `--with-cares` to configure).
Default: 0.0 (disabled)
-TLS settings
-============
+## TLS settings
-client_tls_sslmode
-------------------
+### client_tls_sslmode
TLS mode to use for connections from clients. TLS connections
-are disabled by default. When enabled, `client_tls_key_file`_
-and `client_tls_cert_file`_ must be also configured to set up
+are disabled by default. When enabled, `client_tls_key_file`
+and `client_tls_cert_file` must be also configured to set up
key and cert PgBouncer uses to accept client connections.
disable
- Plain TCP. If client requests TLS, it's ignored. Default.
+: Plain TCP. If client requests TLS, it's ignored. Default.
allow
- If client requests TLS, it is used. If not, plain TCP is used.
+: If client requests TLS, it is used. If not, plain TCP is used.
If client uses client-certificate, it is not validated.
prefer
- Same as ``allow``.
+: Same as `allow`.
require
- Client must use TLS. If not, client connection is rejected.
+: Client must use TLS. If not, client connection is rejected.
If client uses client-certificate, it is not validated.
verify-ca
- Client must use TLS with valid client certificate.
+: Client must use TLS with valid client certificate.
verify-full
- Same as ``verify-ca``.
+: Same as `verify-ca`.
-client_tls_key_file
--------------------
+### client_tls_key_file
Private key for PgBouncer to accept client connections.
Default: not set.
-client_tls_cert_file
---------------------
+### client_tls_cert_file
Certificate for private key. Clients can validate it.
Default: not set.
-client_tls_ca_file
-------------------
+### client_tls_ca_file
Root certificate file to validate client certificates.
Default: unset.
-client_tls_protocols
---------------------
+### client_tls_protocols
-Which TLS protocol versions are allowed. Allowed values: ``tlsv1.0``, ``tlsv1.1``, ``tlsv1.2``.
-Shortcuts: ``all`` (tlsv1.0,tlsv1.1,tlsv1.2), ``secure`` (tlsv1.2), ``legacy`` (all).
+Which TLS protocol versions are allowed. Allowed values: `tlsv1.0`, `tlsv1.1`, `tlsv1.2`.
+Shortcuts: `all` (tlsv1.0,tlsv1.1,tlsv1.2), `secure` (tlsv1.2), `legacy` (all).
-Default: ``all``
+Default: `all`
-client_tls_ciphers
-------------------
+### client_tls_ciphers
-Default: ``fast``
+Default: `fast`
-client_tls_ecdhcurve
---------------------
+### client_tls_ecdhcurve
Elliptic Curve name to use for ECDH key exchanges.
-Allowed values: ``none`` (DH is disabled), ``auto`` (256-bit ECDH), curve name.
+Allowed values: `none` (DH is disabled), `auto` (256-bit ECDH), curve name.
-Default: ``auto``
+Default: `auto`
-client_tls_dheparams
---------------------
+### client_tls_dheparams
DHE key exchange type.
-Allowed values: ``none`` (DH is disabled), ``auto`` (2048-bit DH), ``legacy`` (1024-bit DH).
+Allowed values: `none` (DH is disabled), `auto` (2048-bit DH), `legacy` (1024-bit DH).
-Default: ``auto``
+Default: `auto`
-server_tls_sslmode
-------------------
+### server_tls_sslmode
TLS mode to use for connections to PostgreSQL servers.
TLS connections are disabled by default.
disable
- Plain TCP. TCP is not event requested from server. Default.
+: Plain TCP. TCP is not event requested from server. Default.
allow
- FIXME: if server rejects plain, try TLS?
+: FIXME: if server rejects plain, try TLS?
prefer
- TLS connection is always requested first from PostgreSQL,
+: TLS connection is always requested first from PostgreSQL,
when refused connection will be established over plain TCP.
Server certificate is not validated.
require
- Connection must go over TLS. If server rejects it,
+: Connection must go over TLS. If server rejects it,
plain TCP is not attempted. Server certificate is not validated.
verify-ca
- Connection must go over TLS and server certificate must be valid
- according to `server_tls_ca_file`_. Server host name is not checked
+: Connection must go over TLS and server certificate must be valid
+ according to `server_tls_ca_file`. Server host name is not checked
against certificate.
verify-full
- Connection must go over TLS and server certificate must be valid
- according to `server_tls_ca_file`_. Server host name must match
+: Connection must go over TLS and server certificate must be valid
+ according to `server_tls_ca_file`. Server host name must match
certificate info.
-server_tls_ca_file
-------------------
+### server_tls_ca_file
Root certificate file to validate PostgreSQL server certificates.
Default: unset.
-server_tls_key_file
--------------------
+### server_tls_key_file
Private key for PgBouncer to authenticate against PostgreSQL server.
Default: not set.
-server_tls_cert_file
---------------------
+### server_tls_cert_file
Certificate for private key. PostgreSQL server can validate it.
Default: not set.
-server_tls_protocols
---------------------
+### server_tls_protocols
-Which TLS protocol versions are allowed. Allowed values: ``tlsv1.0``, ``tlsv1.1``, ``tlsv1.2``.
-Shortcuts: ``all`` (tlsv1.0,tlsv1.1,tlsv1.2), ``secure`` (tlsv1.2), ``legacy`` (all).
+Which TLS protocol versions are allowed. Allowed values: `tlsv1.0`, `tlsv1.1`, `tlsv1.2`.
+Shortcuts: `all` (tlsv1.0,tlsv1.1,tlsv1.2), `secure` (tlsv1.2), `legacy` (all).
-Default: ``all``
+Default: `all`
-server_tls_ciphers
-------------------
+### server_tls_ciphers
-Default: ``fast``
+Default: `fast`
-Dangerous timeouts
-==================
+## Dangerous timeouts
Setting following timeouts cause unexpected errors.
-query_timeout
--------------
+### query_timeout
Queries running longer than that are canceled. This should be used only with
slightly smaller server-side statement_timeout, to apply only for network
Default: 0.0 (disabled)
-query_wait_timeout
-------------------
+### query_wait_timeout
Maximum time queries are allowed to spend waiting for execution. If the query
is not assigned to a server during that time, the client is disconnected. This
Default: 120
-client_idle_timeout
--------------------
+### client_idle_timeout
Client connections idling longer than this many seconds are closed. This should
be larger than the client-side connection lifetime settings, and only used
Default: 0.0 (disabled)
-idle_transaction_timeout
-------------------------
+### idle_transaction_timeout
If client has been in "idle in transaction" state longer,
it will be disconnected. [seconds]
Default: 0.0 (disabled)
-Low-level network settings
-==========================
+## Low-level network settings
-pkt_buf
--------
+### pkt_buf
Internal buffer size for packets. Affects size of TCP packets sent and general
memory usage. Actual libpq packets can be larger than this so, no need to set it
Default: 4096
-max_packet_size
----------------
+### max_packet_size
Maximum size for PostgreSQL packets that PgBouncer allows through. One packet
is either one query or one result set row. Full result set can be larger.
Default: 2147483647
-listen_backlog
---------------
+### listen_backlog
Backlog argument for listen(2). Determines how many new unanswered connection
attempts are kept in queue. When queue is full, further new connections are dropped.
Default: 128
-sbuf_loopcnt
-------------
+### sbuf_loopcnt
How many times to process data on one connection, before proceeding.
Without this limit, one connection with a big result set can stall
-PgBouncer for a long time. One loop processes one `pkt_buf`_ amount of data.
+PgBouncer for a long time. One loop processes one `pkt_buf` amount of data.
0 means no limit.
Default: 5
-suspend_timeout
----------------
+### suspend_timeout
How many seconds to wait for buffer flush during SUSPEND or reboot (-R).
Connection is dropped if flush does not succeed.
Default: 10
-tcp_defer_accept
-----------------
+### tcp_defer_accept
-For details on this and other tcp options, please see ``man 7 tcp``.
+For details on this and other tcp options, please see `man 7 tcp`.
Default: 45 on Linux, otherwise 0
-tcp_socket_buffer
------------------
+### tcp_socket_buffer
Default: not set
-tcp_keepalive
---------------
+### tcp_keepalive
Turns on basic keepalive with OS defaults.
Default: 1
-tcp_keepcnt
------------
+### tcp_keepcnt
Default: not set
-tcp_keepidle
-------------
+### tcp_keepidle
Default: not set
-tcp_keepintvl
--------------
+### tcp_keepintvl
Default: not set
-Section [databases]
-===================
+## Section [databases]
This contains key=value pairs where key will be taken as a database name and
value as a libpq connect-string style list of key=value pairs. As actual libpq is not
used, so not all features from libpq can be used (service=, .pgpass).
-Database name can contain characters ``_0-9A-Za-z`` without quoting.
+Database name can contain characters `_0-9A-Za-z` without quoting.
Names that contain other chars need to be quoted with standard SQL
ident quoting: double quotes where "" is taken as single quote.
"*" acts as fallback database: if the exact name does not exist,
its value is taken as connect string for requested database.
Such automatically created database entries are cleaned up
-if they stay idle longer then the time specified in `autodb_idle_timeout`_
+if they stay idle longer then the time specified in `autodb_idle_timeout`
parameter.
-dbname
-------
+### dbname
Destination database name.
Default: same as client-side database name.
-host
-----
+### host
Host name or IP address to connect to. Host names are resolved
-at connect time, the result is cached per ``dns_max_ttl`` parameter.
+at connect time, the result is cached per `dns_max_ttl` parameter.
When a host name's resolution changes, existing server connections are
automatically closed when they are released (according to the pooling
mode), and new server connections immediately use the new resolution.
Default: not set, meaning to use a Unix socket.
-port
-----
+### port
Default: 5432
-user, password
---------------
+### user, password
-If ``user=`` is set, all connections to the destination database will be
+If `user=` is set, all connections to the destination database will be
done with the specified user, meaning that there will be only one pool
for this database.
Otherwise PgBouncer tries to log into the destination database with client
username, meaning that there will be one pool per user.
-The length for ``password`` is limited to 128 characters maximum.
+The length for `password` is limited to 128 characters maximum.
-auth_user
----------
+### auth_user
-Override of the global ``auth_user`` setting, if specified.
+Override of the global `auth_user` setting, if specified.
-pool_size
----------
+### pool_size
Set maximum size of pools for this database. If not set,
the default_pool_size is used.
-reserve_pool
-------------
+### reserve_pool
+
Set additional connections for this database. If not set, reserve_pool_size is
used.
-connect_query
--------------
+### connect_query
Query to be executed after a connection is established, but before
allowing the connection to be used by any clients. If the query raises errors,
they are logged but ignored otherwise.
-pool_mode
----------
+### pool_mode
Set the pool mode specific to this database. If not set,
the default pool_mode is used.
-max_db_connections
-------------------
+### max_db_connections
Configure a database-wide maximum (i.e. all pools within the database will
not have more than this many server connections).
-client_encoding
----------------
+### client_encoding
-Ask specific ``client_encoding`` from server.
+Ask specific `client_encoding` from server.
-datestyle
----------
+### datestyle
-Ask specific ``datestyle`` from server.
+Ask specific `datestyle` from server.
-timezone
---------
+### timezone
Ask specific **timezone** from server.
-Section [users]
-===============
+## Section [users]
This contains key=value pairs where key will be taken as a user name and
value as a libpq connect-string style list of key=value pairs. As actual libpq is not
used, so not all features from libpq can be used.
-
-pool_mode
----------
+### pool_mode
Set the pool mode to be used for all connections from this user. If not set, the
database or default pool_mode is used.
-Include directive
-=================
+## Include directive
The PgBouncer config file can contain include directives, which specify
another config file to read and process. This allows for splitting the
configuration file into physically separate parts. The include directives look
-like this::
+like this:
- %include filename
+ %include filename
If the file name is not absolute path it is taken as relative to current
working directory.
-Authentication file format
-==========================
+
+## Authentication file format
PgBouncer needs its own user database. The users are loaded from a text
-file in following format::
+file in following format:
- "username1" "password" ...
- "username2" "md5abcdef012342345" ...
+ "username1" "password" ...
+ "username2" "md5abcdef012342345" ...
There should be at least 2 fields, surrounded by double quotes. The first
field is the username and the second is either a plain-text or a MD5-hidden
password. PgBouncer ignores the rest of the line.
-PostgreSQL MD5-hidden password format::
+PostgreSQL MD5-hidden password format:
- "md5" + md5(password + username)
+ "md5" + md5(password + username)
So user `admin` with password `1234` will have MD5-hidden password
`md545f2603610af569b6155c45067268c6b`.
`./etc/mkauth.py` for a sample script to generate the authentication
file from the `pg_shadow` system table.
-HBA file format
-===============
+
+## HBA file format
It follows the format of PostgreSQL pg_hba.conf file -
-http://www.postgresql.org/docs/9.4/static/auth-pg-hba-conf.html
+<http://www.postgresql.org/docs/9.4/static/auth-pg-hba-conf.html>
There are following differences:
Not supported: `gss`, `sspi`, `ident`, `ldap`, `radius`, `pam`.
Also username map (`map=`) parameter is not supported.
-Example
-=======
-Minimal config::
+## Example
+
+Minimal config:
- [databases]
- template1 = host=127.0.0.1 dbname=template1 auth_user=someuser
+ [databases]
+ template1 = host=127.0.0.1 dbname=template1 auth_user=someuser
- [pgbouncer]
- pool_mode = session
- listen_port = 6543
- listen_addr = 127.0.0.1
- auth_type = md5
- auth_file = users.txt
- logfile = pgbouncer.log
- pidfile = pgbouncer.pid
- admin_users = someuser
- stats_users = stat_collector
+ [pgbouncer]
+ pool_mode = session
+ listen_port = 6543
+ listen_addr = 127.0.0.1
+ auth_type = md5
+ auth_file = users.txt
+ logfile = pgbouncer.log
+ pidfile = pgbouncer.pid
+ admin_users = someuser
+ stats_users = stat_collector
-Database defaults::
+Database defaults:
- [databases]
+ [databases]
- ; foodb over Unix socket
- foodb =
+ ; foodb over Unix socket
+ foodb =
- ; redirect bardb to bazdb on localhost
- bardb = host=127.0.0.1 dbname=bazdb
+ ; redirect bardb to bazdb on localhost
+ bardb = host=127.0.0.1 dbname=bazdb
- ; access to destination database will go with single user
- forcedb = host=127.0.0.1 port=300 user=baz password=foo client_encoding=UNICODE datestyle=ISO
+ ; access to destination database will go with single user
+ forcedb = host=127.0.0.1 port=300 user=baz password=foo client_encoding=UNICODE datestyle=ISO
-Example of secure function for auth_query::
+Example of secure function for auth_query:
- CREATE OR REPLACE FUNCTION pgbouncer.user_lookup(in i_username text, out uname text, out phash text)
- RETURNS record AS $$
- BEGIN
- SELECT usename, passwd FROM pg_catalog.pg_shadow
- WHERE usename = i_username INTO uname, phash;
- RETURN;
- END;
- $$ LANGUAGE plpgsql SECURITY DEFINER;
- REVOKE ALL ON FUNCTION pgbouncer.user_lookup(text) FROM public, pgbouncer;
- GRANT EXECUTE ON FUNCTION pgbouncer.user_lookup(text) TO pgbouncer;
+ CREATE OR REPLACE FUNCTION pgbouncer.user_lookup(in i_username text, out uname text, out phash text)
+ RETURNS record AS $$
+ BEGIN
+ SELECT usename, passwd FROM pg_catalog.pg_shadow
+ WHERE usename = i_username INTO uname, phash;
+ RETURN;
+ END;
+ $$ LANGUAGE plpgsql SECURITY DEFINER;
+ REVOKE ALL ON FUNCTION pgbouncer.user_lookup(text) FROM public, pgbouncer;
+ GRANT EXECUTE ON FUNCTION pgbouncer.user_lookup(text) TO pgbouncer;
-See also
-========
+## See also
pgbouncer(1) - man page for general usage, console commands.
-https://pgbouncer.github.io/
+<https://pgbouncer.github.io/>
-https://wiki.postgresql.org/wiki/PgBouncer
+<https://wiki.postgresql.org/wiki/PgBouncer>
--- /dev/null
+local text = require('text')
+
+function Header(el)
+ -- drop level-1 header
+ if el.level == 1 then
+ return {}
+ else
+ -- decrease level of all headers by 1
+ el.level = el.level - 1
+ -- convert level-1 headers to uppercase
+ if el.level == 1 then
+ return pandoc.walk_block(el, {
+ Str = function(el)
+ return pandoc.Str(text.upper(el.text))
+ end })
+ end
+ end
+end
+++ /dev/null
---------------------------------
-configuration file for pgbouncer
---------------------------------
-
-:Date: 2018-08-13
-:Version: 1.9.0
-:Manual section: 5
-:Manual group: Databases
-
--- /dev/null
+% PGBOUNCER.INI(5) 1.9.0 | Databases
+
+## Name
+
+pgbouncer.ini - configuration file for pgbouncer
+++ /dev/null
---------------------------------------------
-lightweight connection pooler for PostgreSQL
---------------------------------------------
-
-:Date: 2018-08-13
-:Version: 1.9.0
-:Manual section: 1
-:Manual group: Databases
-
--- /dev/null
+% PGBOUNCER(1) 1.9.0 | Databases
+
+## Name
+
+pgbouncer - lightweight connection pooler for PostgreSQL
* other per-user settings
* Maintenance order vs. lifetime_kill_gap:
- http://lists.pgfoundry.org/pipermail/pgbouncer-general/2011-February/000679.html
+ <http://lists.pgfoundry.org/pipermail/pgbouncer-general/2011-February/000679.html>
* per_loop_maint/per_loop_activate take too much time in case
of moderate load and lots of pools. Perhaps active_pool_list
+# pgbouncer
-pgbouncer
-#########
-Synopsis
-========
+## Synopsis
-::
+ pgbouncer [-d][-R][-v][-u user] <pgbouncer.ini>
+ pgbouncer -V|-h
- pgbouncer [-d][-R][-v][-u user] <pgbouncer.ini>
- pgbouncer -V|-h
+On Windows computers, the options are:
-On Windows computers, the options are::
+ pgbouncer.exe [-v][-u user] <pgbouncer.ini>
+ pgbouncer.exe -V|-h
- pgbouncer.exe [-v][-u user] <pgbouncer.ini>
- pgbouncer.exe -V|-h
+Additional options for setting up a Windows service:
-Additional options for setting up a Windows service::
+ pgbouncer.exe --regservice <pgbouncer.ini>
+ pgbouncer.exe --unregservice <pgbouncer.ini>
- pgbouncer.exe --regservice <pgbouncer.ini>
- pgbouncer.exe --unregservice <pgbouncer.ini>
-
-DESCRIPTION
-===========
+## Description
**pgbouncer** is a PostgreSQL connection pooler. Any target application
can be connected to **pgbouncer** as if it were a PostgreSQL server,
rotating connections:
Session pooling
- Most polite method. When client connects, a server connection will
+
+: Most polite method. When client connects, a server connection will
be assigned to it for the whole duration the client stays connected. When
the client disconnects, the server connection will be put back into the pool.
This is the default method.
Transaction pooling
- A server connection is assigned to client only during a transaction.
+
+: A server connection is assigned to client only during a transaction.
When PgBouncer notices that transaction is over, the server connection
will be put back into the pool.
Statement pooling
- Most aggressive method. The server connection will be put back into
+
+: Most aggressive method. The server connection will be put back into
pool immediately after a query completes. Multi-statement
transactions are disallowed in this mode as they would break.
The administration interface of **pgbouncer** consists of some new
-``SHOW`` commands available when connected to a special 'virtual'
+``SHOW`` commands available when connected to a special "virtual"
database **pgbouncer**.
-Quick-start
-===========
+## Quick-start
Basic setup and usage as following.
-1. Create a pgbouncer.ini file. Details in **pgbouncer(5)**. Simple example::
+1. Create a pgbouncer.ini file. Details in **pgbouncer(5)**. Simple example:
+
+ [databases]
+ template1 = host=127.0.0.1 port=5432 dbname=template1
- [databases]
- template1 = host=127.0.0.1 port=5432 dbname=template1
-
- [pgbouncer]
- listen_port = 6543
- listen_addr = 127.0.0.1
- auth_type = md5
- auth_file = users.txt
- logfile = pgbouncer.log
- pidfile = pgbouncer.pid
- admin_users = someuser
+ [pgbouncer]
+ listen_port = 6543
+ listen_addr = 127.0.0.1
+ auth_type = md5
+ auth_file = users.txt
+ logfile = pgbouncer.log
+ pidfile = pgbouncer.pid
+ admin_users = someuser
-2. Create ``users.txt`` file that contains users allowed in::
+2. Create ``users.txt`` file that contains users allowed in:
- "someuser" "same_password_as_in_server"
+ "someuser" "same_password_as_in_server"
-3. Launch **pgbouncer**::
+3. Launch **pgbouncer**:
- $ pgbouncer -d pgbouncer.ini
+ $ pgbouncer -d pgbouncer.ini
4. Have your application (or the **psql** client) connect to
- **pgbouncer** instead of directly to PostgreSQL server::
+ **pgbouncer** instead of directly to PostgreSQL server:
- $ psql -p 6543 -U someuser template1
+ $ psql -p 6543 -U someuser template1
5. Manage **pgbouncer** by connecting to the special administration
- database **pgbouncer** and issuing ``show help;`` to begin::
+ database **pgbouncer** and issuing ``show help;`` to begin:
- $ psql -p 6543 -U someuser pgbouncer
- pgbouncer=# show help;
- NOTICE: Console usage
- DETAIL:
- SHOW [HELP|CONFIG|DATABASES|FDS|POOLS|CLIENTS|SERVERS|SOCKETS|LISTS|VERSION|...]
- SET key = arg
- RELOAD
- PAUSE
- SUSPEND
- RESUME
- SHUTDOWN
- [...]
+ $ psql -p 6543 -U someuser pgbouncer
+ pgbouncer=# show help;
+ NOTICE: Console usage
+ DETAIL:
+ SHOW [HELP|CONFIG|DATABASES|FDS|POOLS|CLIENTS|SERVERS|SOCKETS|LISTS|VERSION|...]
+ SET key = arg
+ RELOAD
+ PAUSE
+ SUSPEND
+ RESUME
+ SHUTDOWN
+ [...]
-6. If you made changes to the pgbouncer.ini file, you can reload it with::
+6. If you made changes to the pgbouncer.ini file, you can reload it with:
- pgbouncer=# RELOAD;
+ pgbouncer=# RELOAD;
-Command line switches
-=====================
+## Command line switches
-d
- Run in background. Without it the process will run in foreground.
+: Run in background. Without it the process will run in foreground.
Note: Does not work on Windows, **pgbouncer** need to run as service there.
-R
- Do an online restart. That means connecting to the running process,
+: Do an online restart. That means connecting to the running process,
loading the open sockets from it, and then using them. If there
is no active process, boot normally.
Note: Works only if OS supports Unix sockets and the `unix_socket_dir`
Does not work with TLS connections, they are dropped.
-u user
- Switch to the given user on startup.
+: Switch to the given user on startup.
-v
- Increase verbosity. Can be used multiple times.
+: Increase verbosity. Can be used multiple times.
-q
- Be quiet - do not log to stdout. Note this does not affect
+: Be quiet - do not log to stdout. Note this does not affect
logging verbosity, only that stdout is not to be used.
For use in init.d scripts.
-V
- Show version.
+: Show version.
-h
- Show short help.
+: Show short help.
--regservice
- Win32: Register pgbouncer to run as Windows service. The **service_name**
+: Win32: Register pgbouncer to run as Windows service. The **service_name**
config parameter value is used as name to register under.
--unregservice
- Win32: Unregister Windows service.
+: Win32: Unregister Windows service.
-Admin console
-=============
+## Admin console
The console is available by connecting as normal to the
-database **pgbouncer**::
+database **pgbouncer**:
- $ psql -p 6543 pgbouncer
+ $ psql -p 6543 pgbouncer
Only users listed in configuration parameters **admin_users** or **stats_users**
are allowed to login to the console. (Except when `auth_type=any`, then
if the login comes via Unix socket and the client has same Unix user UID
as the running process.
-Show commands
-~~~~~~~~~~~~~
+### Show commands
The **SHOW** commands output information. Each command is described below.
-SHOW STATS;
------------
+#### SHOW STATS;
Shows statistics.
database
- Statistics are presented per database.
+: Statistics are presented per database.
total_xact_count
- Total number of SQL transactions pooled by **pgbouncer**.
+: Total number of SQL transactions pooled by **pgbouncer**.
total_query_count
- Total number of SQL queries pooled by **pgbouncer**.
+: Total number of SQL queries pooled by **pgbouncer**.
total_received
- Total volume in bytes of network traffic received by **pgbouncer**.
+: Total volume in bytes of network traffic received by **pgbouncer**.
total_sent
- Total volume in bytes of network traffic sent by **pgbouncer**.
+: Total volume in bytes of network traffic sent by **pgbouncer**.
total_xact_time
- Total number of microseconds spent by **pgbouncer** when connected
+: Total number of microseconds spent by **pgbouncer** when connected
to PostgreSQL in a transaction, either idle in transaction or
executing queries.
total_query_time
- Total number of microseconds spent by **pgbouncer** when actively
+: Total number of microseconds spent by **pgbouncer** when actively
connected to PostgreSQL, executing queries.
total_wait_time
- Time spent by clients waiting for a server in microseconds.
+: Time spent by clients waiting for a server in microseconds.
avg_xact_count
- Average transactions per second in last stat period.
+: Average transactions per second in last stat period.
avg_query_count
- Average queries per second in last stat period.
+: Average queries per second in last stat period.
avg_recv
- Average received (from clients) bytes per second.
+: Average received (from clients) bytes per second.
avg_sent
- Average sent (to clients) bytes per second.
+: Average sent (to clients) bytes per second.
avg_xact_time
- Average transaction duration in microseconds.
+: Average transaction duration in microseconds.
avg_query_time
- Average query duration in microseconds.
+: Average query duration in microseconds.
avg_wait_time
- Time spent by clients waiting for a server in microseconds (average
+: Time spent by clients waiting for a server in microseconds (average
per second).
-SHOW STATS_TOTALS;
-------------------
+#### SHOW STATS_TOTALS;
-Subset of **SHOW STATS** showing the total values (**total\_**).
+Subset of **SHOW STATS** showing the total values (**total_**).
-SHOW STATS_AVERAGES;
---------------------
+#### SHOW STATS_AVERAGES;
-Subset of **SHOW STATS** showing the average values (**avg\_**).
+Subset of **SHOW STATS** showing the average values (**avg_**).
-SHOW SERVERS;
--------------
+#### SHOW SERVERS;
type
- S, for server.
+: S, for server.
user
- User name **pgbouncer** uses to connect to server.
+: User name **pgbouncer** uses to connect to server.
database
- Database name.
+: Database name.
state
- State of the pgbouncer server connection, one of **active**, **used** or
+: State of the pgbouncer server connection, one of **active**, **used** or
**idle**.
addr
- IP address of PostgreSQL server.
+: IP address of PostgreSQL server.
port
- Port of PostgreSQL server.
+: Port of PostgreSQL server.
local_addr
- Connection start address on local machine.
+: Connection start address on local machine.
local_port
- Connection start port on local machine.
+: Connection start port on local machine.
connect_time
- When the connection was made.
+: When the connection was made.
request_time
- When last request was issued.
+: When last request was issued.
wait
- Current waiting time in seconds.
+: Current waiting time in seconds.
wait_us
- Microsecond part of the current waiting time.
+: Microsecond part of the current waiting time.
close_needed
- 1 if the connection will be closed as soon as possible,
+: 1 if the connection will be closed as soon as possible,
because a configuration file reload or DNS update changed the
connection information or **RECONNECT** was issued.
ptr
- Address of internal object for this connection.
+: Address of internal object for this connection.
Used as unique ID.
link
- Address of client connection the server is paired with.
+: Address of client connection the server is paired with.
remote_pid
- PID of backend server process. In case connection is made over
+: PID of backend server process. In case connection is made over
Unix socket and OS supports getting process ID info, its
OS PID. Otherwise it's extracted from cancel packet server sent,
which should be PID in case server is PostgreSQL, but it's a random
number in case server it is another PgBouncer.
tls
- A string with TLS connection information, or empty if not using TLS.
+: A string with TLS connection information, or empty if not using TLS.
-SHOW CLIENTS;
--------------
+#### SHOW CLIENTS;
type
- C, for client.
+: C, for client.
user
- Client connected user.
+: Client connected user.
database
- Database name.
+: Database name.
state
- State of the client connection, one of **active**, **used**, **waiting**
+: State of the client connection, one of **active**, **used**, **waiting**
or **idle**.
addr
- IP address of client.
+: IP address of client.
port
- Port client is connected to.
+: Port client is connected to.
local_addr
- Connection end address on local machine.
+: Connection end address on local machine.
local_port
- Connection end port on local machine.
+: Connection end port on local machine.
connect_time
- Timestamp of connect time.
+: Timestamp of connect time.
request_time
- Timestamp of latest client request.
+: Timestamp of latest client request.
wait
- Current waiting time in seconds.
+: Current waiting time in seconds.
wait_us
- Microsecond part of the current waiting time.
+: Microsecond part of the current waiting time.
close_needed
- not used for clients
+: not used for clients
ptr
- Address of internal object for this connection.
+: Address of internal object for this connection.
Used as unique ID.
link
- Address of server connection the client is paired with.
+: Address of server connection the client is paired with.
remote_pid
- Process ID, in case client connects over Unix socket
+: Process ID, in case client connects over Unix socket
and OS supports getting it.
tls
- A string with TLS connection information, or empty if not using TLS.
+: A string with TLS connection information, or empty if not using TLS.
-SHOW POOLS;
------------
+#### SHOW POOLS;
A new pool entry is made for each couple of (database, user).
database
- Database name.
+: Database name.
user
- User name.
+: User name.
cl_active
- Client connections that are linked to server connection and can process queries.
+: Client connections that are linked to server connection and can process queries.
cl_waiting
- Client connections have sent queries but have not yet got a server connection.
+: Client connections have sent queries but have not yet got a server connection.
sv_active
- Server connections that linked to client.
+: Server connections that linked to client.
sv_idle
- Server connections that unused and immediately usable for client queries.
+: Server connections that unused and immediately usable for client queries.
sv_used
- Server connections that have been idle more than `server_check_delay`,
+: Server connections that have been idle more than `server_check_delay`,
so they need `server_check_query` to run on them before they can be used.
sv_tested
- Server connections that are currently running either `server_reset_query`
+: Server connections that are currently running either `server_reset_query`
or `server_check_query`.
sv_login
- Server connections currently in logging in process.
+: Server connections currently in logging in process.
maxwait
- How long the first (oldest) client in queue has waited, in seconds.
+: How long the first (oldest) client in queue has waited, in seconds.
If this starts increasing, then the current pool of servers does
not handle requests quick enough. Reason may be either overloaded
server or just too small of a **pool_size** setting.
maxwait_us
- Microsecond part of the maximum waiting time.
+: Microsecond part of the maximum waiting time.
pool_mode
- The pooling mode in use.
+: The pooling mode in use.
-SHOW LISTS;
------------
+#### SHOW LISTS;
Show following internal information, in columns (not rows):
databases
- Count of databases.
+: Count of databases.
users
- Count of users.
+: Count of users.
pools
- Count of pools.
+: Count of pools.
free_clients
- Count of free clients.
+: Count of free clients.
used_clients
- Count of used clients.
+: Count of used clients.
login_clients
- Count of clients in **login** state.
+: Count of clients in **login** state.
free_servers
- Count of free servers.
+: Count of free servers.
used_servers
- Count of used servers.
+: Count of used servers.
dns_names
- Count of DNS names in the cache.
+: Count of DNS names in the cache.
dns_zones
- Count of DNS zones in the cache.
+: Count of DNS zones in the cache.
dns_queries
- Count of in-flight DNS queries.
+: Count of in-flight DNS queries.
dns_pending
- not used
+: not used
-SHOW USERS;
------------
+#### SHOW USERS;
name
- The user name
+: The user name
pool_mode
- The user's override pool_mode, or NULL if the default will be used instead.
+: The user's override pool_mode, or NULL if the default will be used instead.
-SHOW DATABASES;
----------------
+#### SHOW DATABASES;
name
- Name of configured database entry.
+: Name of configured database entry.
host
- Host pgbouncer connects to.
+: Host pgbouncer connects to.
port
- Port pgbouncer connects to.
+: Port pgbouncer connects to.
database
- Actual database name pgbouncer connects to.
+: Actual database name pgbouncer connects to.
force_user
- When user is part of the connection string, the connection between
+: When user is part of the connection string, the connection between
pgbouncer and PostgreSQL is forced to the given user, whatever the
client user.
pool_size
- Maximum number of server connections.
+: Maximum number of server connections.
reserve_pool
- Maximum number of additional connections for this database.
+: Maximum number of additional connections for this database.
pool_mode
- The database's override pool_mode, or NULL if the default will be used instead.
+: The database's override pool_mode, or NULL if the default will be used instead.
max_connections
- Maximum number of allowed connections for this database, as set by
+: Maximum number of allowed connections for this database, as set by
**max_db_connections**, either globally or per database.
current_connections
- Current number of connections for this database.
+: Current number of connections for this database.
paused
- 1 if this database is currently paused, else 0.
+: 1 if this database is currently paused, else 0.
disabled
- 1 if this database is currently disabled, else 0.
+: 1 if this database is currently disabled, else 0.
-SHOW FDS;
----------
+#### SHOW FDS;
Internal command - shows list of file descriptors in use with internal state attached to them.
while PgBouncer is in use.
fd
- File descriptor numeric value.
+: File descriptor numeric value.
task
- One of **pooler**, **client** or **server**.
+: One of **pooler**, **client** or **server**.
user
- User of the connection using the FD.
+: User of the connection using the FD.
database
- Database of the connection using the FD.
+: Database of the connection using the FD.
addr
- IP address of the connection using the FD, **unix** if a Unix socket
+: IP address of the connection using the FD, **unix** if a Unix socket
is used.
port
- Port used by the connection using the FD.
+: Port used by the connection using the FD.
cancel
- Cancel key for this connection.
+: Cancel key for this connection.
link
- fd for corresponding server/client. NULL if idle.
+: fd for corresponding server/client. NULL if idle.
-SHOW CONFIG;
-------------
+#### SHOW CONFIG;
Show the current configuration settings, one per row, with following
columns:
key
- Configuration variable name
+: Configuration variable name
value
- Configuration value
+: Configuration value
changeable
- Either **yes** or **no**, shows if the variable can be changed while running.
+: Either **yes** or **no**, shows if the variable can be changed while running.
If **no**, the variable can be changed only at boot time. Use
**SET** to change a variable at run time.
-SHOW DNS_HOSTS;
----------------
+#### SHOW DNS_HOSTS;
Show host names in DNS cache.
hostname
- Host name.
+: Host name.
ttl
- How many seconds until next lookup.
+: How many seconds until next lookup.
addrs
- Comma separated list of addresses.
+: Comma separated list of addresses.
-SHOW DNS_ZONES;
----------------
+#### SHOW DNS_ZONES;
Show DNS zones in cache.
zonename
- Zone name.
+: Zone name.
serial
- Current serial.
+: Current serial.
count
- Host names belonging to this zone.
+: Host names belonging to this zone.
-Process controlling commands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+### Process controlling commands
-PAUSE [db];
------------
+#### PAUSE [db];
PgBouncer tries to disconnect from all servers, first waiting for all queries
to complete. The command will not return before all queries are finished. To be used
New client connections to a paused database will wait until **RESUME**
is called.
-DISABLE db;
------------
+#### DISABLE db;
Reject all new client connections on the given database.
-ENABLE db;
-----------
+#### ENABLE db;
Allow new client connections after a previous **DISABLE** command.
-RECONNECT [db];
----------------
+#### RECONNECT [db];
Close each open server connection for the given database, or all
databases, after it is released (according to the pooling mode), even
example, in emergency failover rather than gradual switchover
scenarios), also consider **KILL**.
-KILL db;
---------
+#### KILL db;
Immediately drop all client and server connections on given database.
New client connections to a killed database will wait until **RESUME**
is called.
-SUSPEND;
---------
+#### SUSPEND;
All socket buffers are flushed and PgBouncer stops listening for data on them.
The command will not return before all buffers are empty. To be used at the time
New client connections to a suspended database will wait until
**RESUME** is called.
-RESUME [db];
-------------
+#### RESUME [db];
Resume work from previous **KILL**, **PAUSE**, or **SUSPEND** command.
-SHUTDOWN;
----------
+#### SHUTDOWN;
The PgBouncer process will exit.
-RELOAD;
--------
+#### RELOAD;
The PgBouncer process will reload its configuration file and update
changeable settings.
server connections will immediately use the updated connection
parameters.
-WAIT_CLOSE [<db>];
-------------------
+#### WAIT_CLOSE [<db>];
Wait until all server connections, either of the specified database or
of all databases, have cleared the "close_needed" state (see **SHOW
wait until the respective configuration change has been fully
activated, for example in switchover scripts.
-Other commands
-~~~~~~~~~~~~~~
+### Other commands
-SET key = arg;
---------------
+#### SET key = arg;
-Changes a configuration setting (see also **SHOW CONFIG**). For example::
+Changes a configuration setting (see also **SHOW CONFIG**). For example:
SET log_connections = 1;
SET server_check_query = 'select 2';
PgBouncer settings. A **SET** command run on another database will be
passed to the PostgreSQL backend like any other SQL command.)
-Signals
-~~~~~~~
+### Signals
SIGHUP
- Reload config. Same as issuing the command **RELOAD;** on the console.
+: Reload config. Same as issuing the command **RELOAD;** on the console.
SIGINT
- Safe shutdown. Same as issuing **PAUSE;** and **SHUTDOWN;** on the console.
+: Safe shutdown. Same as issuing **PAUSE;** and **SHUTDOWN;** on the console.
SIGTERM
- Immediate shutdown. Same as issuing **SHUTDOWN;** on the console.
+: Immediate shutdown. Same as issuing **SHUTDOWN;** on the console.
SIGUSR1
- Same as issuing **PAUSE;** on the console.
+: Same as issuing **PAUSE;** on the console.
SIGUSR2
- Same as issuing **RESUME;** on the console.
-
-Libevent settings
-~~~~~~~~~~~~~~~~~
+: Same as issuing **RESUME;** on the console.
-From libevent docs::
+### Libevent settings
- It is possible to disable support for epoll, kqueue, devpoll, poll
- or select by setting the environment variable EVENT_NOEPOLL,
- EVENT_NOKQUEUE, EVENT_NODEVPOLL, EVENT_NOPOLL or EVENT_NOSELECT,
- respectively.
+From libevent docs:
- By setting the environment variable EVENT_SHOW_METHOD, libevent
- displays the kernel notification method that it uses.
+> It is possible to disable support for epoll, kqueue, devpoll, poll
+> or select by setting the environment variable EVENT_NOEPOLL,
+> EVENT_NOKQUEUE, EVENT_NODEVPOLL, EVENT_NOPOLL or EVENT_NOSELECT,
+> respectively.
+>
+> By setting the environment variable EVENT_SHOW_METHOD, libevent
+> displays the kernel notification method that it uses.
-See also
-========
+## See also
pgbouncer(5) - man page of configuration settings descriptions.
-https://pgbouncer.github.io/
+<https://pgbouncer.github.io/>
-https://wiki.postgresql.org/wiki/PgBouncer
+<https://wiki.postgresql.org/wiki/PgBouncer>
# Check if all options in main.c are defined in sample ini and docs
sources="src/main.c"
-targets="doc/config.rst etc/pgbouncer.ini"
+targets="doc/config.md etc/pgbouncer.ini"
status=0
projects / pgbouncer / commitdiff