From cb9a1511a48f7f5fb3ddf258055c698c8004f00f Mon Sep 17 00:00:00 2001 From: Peter Eisentraut Date: Thu, 7 Feb 2019 13:47:56 +0100 Subject: [PATCH] Convert documentation from rst to Markdown It seems that many contributors already submit patches thinking that rst is Markdown, which leads to incorrect and inconsistent formatting, since the two are similar but not compatible. By using the more well known Markdown, we can perhaps hope to achieve better formatted documentation contributions. Also, since the web site uses Markdown as its source format, by using Markdown here we can avoid the fragile conversion process altogether. --- .gitattributes | 5 - .travis.yml | 4 +- Makefile | 6 +- NEWS.rst => NEWS.md | 266 ++-------------- README.rst => README.md | 55 ++-- config.mak.in | 2 +- configure.ac | 3 +- debian/control | 2 +- doc/Makefile | 12 +- doc/{config.rst => config.md} | 580 ++++++++++++++-------------------- doc/filter.lua | 18 ++ doc/frag-config-man | 9 - doc/frag-config-man.md | 5 + doc/frag-usage-man | 9 - doc/frag-usage-man.md | 5 + doc/{todo.rst => todo.md} | 2 +- doc/{usage.rst => usage.md} | 469 +++++++++++++-------------- etc/optscan.sh | 2 +- 18 files changed, 544 insertions(+), 910 deletions(-) rename NEWS.rst => NEWS.md (95%) rename README.rst => README.md (62%) rename doc/{config.rst => config.md} (65%) create mode 100644 doc/filter.lua delete mode 100644 doc/frag-config-man create mode 100644 doc/frag-config-man.md delete mode 100644 doc/frag-usage-man create mode 100644 doc/frag-usage-man.md rename doc/{todo.rst => todo.md} (96%) rename doc/{usage.rst => usage.md} (52%) diff --git a/.gitattributes b/.gitattributes index 5deca1a..4822ed3 100644 --- a/.gitattributes +++ b/.gitattributes @@ -1,10 +1,5 @@ -*.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 diff --git a/.travis.yml b/.travis.yml index 9d93659..4d9531b 100644 --- a/.travis.yml +++ b/.travis.yml @@ -9,7 +9,9 @@ addons: - 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 diff --git a/Makefile b/Makefile index cd5a50c..2e13d00 100644 --- a/Makefile +++ b/Makefile @@ -51,7 +51,7 @@ AM_FEATURES = libusual 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 @@ -149,8 +149,8 @@ tags: 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: diff --git a/NEWS.rst b/NEWS.md similarity index 95% rename from NEWS.rst rename to NEWS.md index 57fc703..9a9d185 100644 --- a/NEWS.rst +++ b/NEWS.md @@ -7,47 +7,27 @@ PgBouncer 1.9.x **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 @@ -56,49 +36,32 @@ 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 `_) - + ([#118](https://github.com/pgbouncer/pgbouncer/issues/118)) * Several other hba parsing fixes. - * Fix race condition when canceling query. - (`#141 `_) - + ([#141](https://github.com/pgbouncer/pgbouncer/issues/141)) - Cleanups - * `auth_user` setting is now also allowed globally, not only per database. - (`#142 `_) - + ([#142](https://github.com/pgbouncer/pgbouncer/issues/142)) * Set console client and server encoding to `UTF8`. PgBouncer 1.7.x @@ -107,27 +70,19 @@ 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 `_) - + ([#113](https://github.com/pgbouncer/pgbouncer/issues/113)) - Cleanups - * Make build reproducible by dropping DBGVER handling. - (`#112 `_) - + ([#112](https://github.com/pgbouncer/pgbouncer/issues/112)) * Antimake: Sort file list from $(wildcard), newer gmake does not sort it anymore. - (`#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"** @@ -143,91 +98,64 @@ Debian/wheezy which has 600k overhead per connection (without leaking) 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 `_) - + ([#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 `_) - + ([#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 `_) - + ([#101](https://github.com/pgbouncer/pgbouncer/issues/101)) * Fix various issues with Windows build. - (`#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 `_) - + ([#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 `_ + [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 `_. - + [#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. @@ -237,7 +165,6 @@ PgBouncer 1.6.x **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 @@ -247,12 +174,11 @@ PgBouncer 1.6.x 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 `_ + [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. @@ -320,21 +246,14 @@ PgBouncer 1.6.x - 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) @@ -342,36 +261,24 @@ PgBouncer 1.6.x * 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 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) @@ -381,26 +288,18 @@ PgBouncer 1.5.x **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"** @@ -415,14 +314,13 @@ PgBouncer 1.5.x - by '*' in [databases] section - the database name can come from network thus making remote shutdown possible. - `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. @@ -431,16 +329,13 @@ PgBouncer 1.5.x * 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. @@ -449,37 +344,26 @@ PgBouncer 1.5.x **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"** @@ -492,11 +376,9 @@ To enable it for libc, add 'options edns0' to /etc/resolv.conf. 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 @@ -504,56 +386,37 @@ GNU Make 3.81+ is required for building. 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. @@ -565,22 +428,15 @@ PgBouncer 1.4.x 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. - * : Ignore system htoX/Xtoh defines. There may be only subset of macros defined. - * : Separate compat sigval from compat sigevent - * : Include to get iovec - * : Better function autodetection on win32 - * : Remove duplicate sigval/sigevent declaration **2011-04-01 - PgBouncer 1.4.1 - "It Was All An Act"** @@ -589,10 +445,8 @@ Affected OS-es: \*BSD, Solaris, Win32. * 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 @@ -630,42 +484,28 @@ Affected OS-es: \*BSD, Solaris, Win32. * 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) - * : 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"** @@ -701,13 +541,11 @@ Affected OS-es: \*BSD, Solaris, Win32. - 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 @@ -716,47 +554,33 @@ 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"** @@ -802,32 +626,23 @@ PgBouncer 1.3.x **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. @@ -851,19 +666,19 @@ PgBouncer 1.3.x 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. @@ -922,7 +737,6 @@ PgBouncer 1.2.x **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) @@ -935,7 +749,6 @@ Thanks to Devrim GÜNDÜZ and Bjoern Metzdorf for problem reports and testing. **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. @@ -943,19 +756,14 @@ Thanks to Devrim GÜNDÜZ and Bjoern Metzdorf for problem reports and testing. **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 for 'struct iovec'. * Cancel shutdown (from SIGINT) on RESUME/SIGUSR2, otherwise it will trigger on next PAUSE. @@ -1053,50 +861,38 @@ PgBouncer 1.1.x **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: @@ -1132,11 +928,8 @@ PgBouncer 1.0.x **2007-06-18 - PgBouncer 1.0.8 - "Undead Shovel Jutsu"** - Fixes - * Fix crash in cancel packet handling. (^C from psql) - - Features - * PAUSE ; RESUME ; works now. * Cleanup of console command parsing. * Disable expensive in-list assert check. @@ -1144,7 +937,6 @@ PgBouncer 1.0.x **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. @@ -1158,7 +950,6 @@ PgBouncer 1.0.x **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, requires there. @@ -1167,7 +958,6 @@ PgBouncer 1.0.x **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() @@ -1176,7 +966,6 @@ PgBouncer 1.0.x **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. @@ -1184,14 +973,12 @@ PgBouncer 1.0.x **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 @@ -1200,7 +987,6 @@ PgBouncer 1.0.x **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 @@ -1209,7 +995,6 @@ PgBouncer 1.0.x **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. @@ -1218,7 +1003,6 @@ PgBouncer 1.0.x * 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. diff --git a/README.rst b/README.md similarity index 62% rename from README.rst rename to README.md index b14b35a..008847b 100644 --- a/README.rst +++ b/README.md @@ -4,30 +4,28 @@ PgBouncer Lightweight connection pooler for PostgreSQL. -Homepage - https://pgbouncer.github.io +Homepage: -Sources, bugtracking - https://github.com/pgbouncer/pgbouncer +Sources, bugtracking: 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 @@ -44,21 +42,14 @@ time instead just once at config load time. This requires proper 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 @@ -78,7 +69,7 @@ Building from Git 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 @@ -89,7 +80,7 @@ you can run configure:: $ make $ make install -Additional packages required: autoconf, automake, libtool, python-docutils +Additional packages required: autoconf, automake, libtool, pandoc Building for WIN32 ------------------ @@ -98,12 +89,12 @@ At the moment only build env tested is MINGW32 / MSYS. Cygwin 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 ... @@ -114,19 +105,19 @@ Running from command-line goes as usual, except -d (daemonize), -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 diff --git a/config.mak.in b/config.mak.in index 9c5dd1d..ef6db32 100644 --- a/config.mak.in +++ b/config.mak.in @@ -59,7 +59,7 @@ TLS_CPPFLAGS = @TLS_CPPFLAGS@ TLS_LDFLAGS = @TLS_LDFLAGS@ TLS_LIBS = @TLS_LIBS@ -RST2MAN = @RST2MAN@ +PANDOC = @PANDOC@ DLLWRAP = @DLLWRAP@ DLLTOOL = @DLLTOOL@ WINDRES = @WINDRES@ diff --git a/configure.ac b/configure.ac index 185bf5c..cbcd8d0 100644 --- a/configure.ac +++ b/configure.ac @@ -13,8 +13,7 @@ AC_USUAL_PROGRAM_CHECK 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 diff --git a/debian/control b/debian/control index eabe3c0..c7931cf 100644 --- a/debian/control +++ b/debian/control @@ -3,7 +3,7 @@ Section: database Priority: extra Maintainer: Marko Kreen 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 diff --git a/doc/Makefile b/doc/Makefile index 0c0c84f..9849ef8 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -4,8 +4,8 @@ manpages = pgbouncer.1 pgbouncer.5 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) @@ -15,11 +15,11 @@ abs_top_srcdir ?= $(CURDIR)/.. 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 diff --git a/doc/config.rst b/doc/config.md similarity index 65% rename from doc/config.rst rename to doc/config.md index 86b2c67..d7d8f87 100644 --- a/doc/config.rst +++ b/doc/config.md @@ -1,54 +1,46 @@ +# 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. @@ -57,22 +49,19 @@ Note: Not supported on Windows machines. 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. @@ -81,60 +70,55 @@ Note: Not supported on Windows machines. 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. @@ -144,71 +128,64 @@ use non-admin user that calls SECURITY DEFINER function instead. 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 @@ -216,23 +193,20 @@ of total inactivity. 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 @@ -243,8 +217,7 @@ will immediately be opened for the waiting pool. 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 @@ -253,8 +226,7 @@ another pool, because the server connection for the first pool is still open. 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 @@ -264,19 +236,17 @@ achieving uniform load. 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 @@ -285,8 +255,7 @@ exclusively use Extended Query protocol will stay working. 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 @@ -295,83 +264,71 @@ pgbouncer does not change it again. 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. @@ -379,20 +336,17 @@ 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 @@ -401,34 +355,31 @@ SHOW FDS. 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. @@ -439,16 +390,14 @@ transaction. 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. @@ -456,8 +405,7 @@ If an empty string, then sanity checking is disabled. 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 @@ -480,8 +428,7 @@ interrupted, only idle sessions. 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, @@ -489,32 +436,28 @@ then closed. [seconds] 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 @@ -522,8 +465,7 @@ SUSPEND and thus online restart. [seconds] 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 @@ -531,8 +473,7 @@ aspect of that is that their statistics are also forgotten. [seconds] 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. @@ -540,16 +481,13 @@ Actual DNS TTL is ignored. [seconds] 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. @@ -559,167 +497,150 @@ If it notices changes, all host names under that zone 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 @@ -727,8 +648,7 @@ problems. [seconds] 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 @@ -739,8 +659,7 @@ If this is disabled, clients will be queued infinitely. 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 @@ -748,8 +667,7 @@ for network problems. [seconds] 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] @@ -757,11 +675,9 @@ 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 @@ -769,54 +685,47 @@ large. 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. @@ -825,51 +734,45 @@ On Linux, the system defaults are **tcp_keepidle=7200**, **tcp_keepintvl=75**, 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. @@ -878,118 +781,104 @@ manner. 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`. @@ -999,11 +888,11 @@ to generate it from some other list of users and passwords. See `./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 + There are following differences: @@ -1015,57 +904,56 @@ 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://wiki.postgresql.org/wiki/PgBouncer + diff --git a/doc/filter.lua b/doc/filter.lua new file mode 100644 index 0000000..7b18c55 --- /dev/null +++ b/doc/filter.lua @@ -0,0 +1,18 @@ +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 diff --git a/doc/frag-config-man b/doc/frag-config-man deleted file mode 100644 index bf73345..0000000 --- a/doc/frag-config-man +++ /dev/null @@ -1,9 +0,0 @@ --------------------------------- -configuration file for pgbouncer --------------------------------- - -:Date: 2018-08-13 -:Version: 1.9.0 -:Manual section: 5 -:Manual group: Databases - diff --git a/doc/frag-config-man.md b/doc/frag-config-man.md new file mode 100644 index 0000000..f345856 --- /dev/null +++ b/doc/frag-config-man.md @@ -0,0 +1,5 @@ +% PGBOUNCER.INI(5) 1.9.0 | Databases + +## Name + +pgbouncer.ini - configuration file for pgbouncer diff --git a/doc/frag-usage-man b/doc/frag-usage-man deleted file mode 100644 index ab5600e..0000000 --- a/doc/frag-usage-man +++ /dev/null @@ -1,9 +0,0 @@ --------------------------------------------- -lightweight connection pooler for PostgreSQL --------------------------------------------- - -:Date: 2018-08-13 -:Version: 1.9.0 -:Manual section: 1 -:Manual group: Databases - diff --git a/doc/frag-usage-man.md b/doc/frag-usage-man.md new file mode 100644 index 0000000..45dc650 --- /dev/null +++ b/doc/frag-usage-man.md @@ -0,0 +1,5 @@ +% PGBOUNCER(1) 1.9.0 | Databases + +## Name + +pgbouncer - lightweight connection pooler for PostgreSQL diff --git a/doc/todo.rst b/doc/todo.md similarity index 96% rename from doc/todo.rst rename to doc/todo.md index c8b5135..a447304 100644 --- a/doc/todo.rst +++ b/doc/todo.md @@ -23,7 +23,7 @@ Problems / cleanups * other per-user settings * Maintenance order vs. lifetime_kill_gap: - 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 diff --git a/doc/usage.rst b/doc/usage.md similarity index 52% rename from doc/usage.rst rename to doc/usage.md index 7f14f07..1442477 100644 --- a/doc/usage.rst +++ b/doc/usage.md @@ -1,27 +1,22 @@ +# pgbouncer -pgbouncer -######### -Synopsis -======== +## Synopsis -:: + pgbouncer [-d][-R][-v][-u user] + pgbouncer -V|-h - pgbouncer [-d][-R][-v][-u user] - pgbouncer -V|-h +On Windows computers, the options are: -On Windows computers, the options are:: + pgbouncer.exe [-v][-u user] + pgbouncer.exe -V|-h - pgbouncer.exe [-v][-u user] - pgbouncer.exe -V|-h +Additional options for setting up a Windows service: -Additional options for setting up a Windows service:: + pgbouncer.exe --regservice + pgbouncer.exe --unregservice - pgbouncer.exe --regservice - pgbouncer.exe --unregservice - -DESCRIPTION -=========== +## Description **pgbouncer** is a PostgreSQL connection pooler. Any target application can be connected to **pgbouncer** as if it were a PostgreSQL server, @@ -36,86 +31,87 @@ pooling, **pgbouncer** supports several types of pooling when 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` @@ -123,36 +119,35 @@ Command line switches 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 @@ -162,336 +157,325 @@ Additionally, the username **pgbouncer** is allowed to log in without password, 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. @@ -504,81 +488,76 @@ This command also blocks the internal event loop, so it should not be used 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 @@ -589,18 +568,15 @@ If database name is given, only that database will be paused. 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 @@ -626,16 +602,14 @@ recommended instead. To close server connections without waiting (for 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 @@ -644,18 +618,15 @@ of PgBouncer online reboot. 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. @@ -667,8 +638,7 @@ connection is next released (according to the pooling mode), and new server connections will immediately use the updated connection parameters. -WAIT_CLOSE []; ------------------- +#### WAIT_CLOSE []; Wait until all server connections, either of the specified database or of all databases, have cleared the "close_needed" state (see **SHOW @@ -676,13 +646,11 @@ SERVERS**). This can be called after a **RECONNECT** or **RELOAD** to 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'; @@ -691,42 +659,39 @@ Changes a configuration setting (see also **SHOW CONFIG**). For example:: 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://wiki.postgresql.org/wiki/PgBouncer + diff --git a/etc/optscan.sh b/etc/optscan.sh index 6f40564..938e016 100755 --- a/etc/optscan.sh +++ b/etc/optscan.sh @@ -3,7 +3,7 @@ # 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 -- 2.40.0