From: Marko Kreen Date: Mon, 27 Aug 2007 21:45:00 +0000 (+0000) Subject: asciidoc manpages from Dimitri Fontaine. X-Git-Tag: pgbouncer_1_1~38 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=ef54512f5971ba3726767522dd9c6ce6fc4db984;p=pgbouncer asciidoc manpages from Dimitri Fontaine. --- diff --git a/doc/Makefile b/doc/Makefile index 68b19e1..9a6e93a 100644 --- a/doc/Makefile +++ b/doc/Makefile @@ -2,7 +2,10 @@ wiki = https://developer.skype.com/SkypeGarage/DbProjects/PgBouncer web = mkz@shell.pgfoundry.org:/home/pgfoundry.org/groups/pgbouncer/htdocs/ -all: +all: man + +man: pgbouncer.1 pgbouncer.5 +html: pgbouncer.config.html pgbouncer.cmdline.html upload: devupload.sh overview.txt $(wiki) @@ -10,3 +13,21 @@ upload: devupload.sh usage.txt $(wiki)/UsageInfo devupload.sh config.txt $(wiki)/ConfigFile +pgbouncer.1: pgbouncer.cmdline.xml + xmlto man $< + +pgbouncer.5: pgbouncer.config.xml + xmlto man $< + +%.xml: %.txt + asciidoc -b docbook -d manpage $< + +%.html: %.txt + asciidoc $< + +manpage.xml: manpage.txt + asciidoc8 -d manpage -b docbook $< + +clean: + rm -f pgbouncer.8 manpage.xml *.[1-9] *.html *.xml + diff --git a/doc/pgbouncer.cmdline.txt b/doc/pgbouncer.cmdline.txt new file mode 100644 index 0000000..3c454ff --- /dev/null +++ b/doc/pgbouncer.cmdline.txt @@ -0,0 +1,429 @@ += pgbouncer(1) = + +== NAME == + +pgbouncer - Lightweight connection pooler for PostgreSQL. + +== SYNOPSIS == + + pgbouncer [-d][-R][-v] + pgbouncer -V|-h + +== DESCRIPTION == + ++pgbouncer+ is a PostgreSQL connection pooler. Any target application +can be connected to +pgbouncer+ as if it were a PostgreSQL server, +and +pgbouncer+ will manage to connect to the server, or to +reuse one of its existing connections. + +The aim of +pgbouncer+ is to lower the performance impact of opening +new connections to PostgreSQL. + +In order not to compromise transaction semantics for connection +pooling, +pgbouncer+ supports several levels of brutality when +rotating connections: + +Session pooling:: + Most polite method. When client connects, a server connection will + be assigned to it for the whole duration it stays connected. When + client disconnects, the server connection will be put back into pool. + +Transaction pooling:: + Server connection is assigned to client only during a transaction. + When PgBouncer notices that transaction is over, the server will + be put back into pool. + +Statement pooling:: + Most aggressive method. The server connection will be put back into + pool immidiately after a query completes. Multi-statement + transactions are disallowed in this mode as they would break. + +The administration interface of +pgbouncer+ consists of some new ++SHOW+ commands available when connected to a special 'virtual' +database +pgbouncer+. + +== QUICK-START == + +Basic setup and usage as following. + +This example assumes the +postgres+ user is given administrative +permissions from +pgbouncer.ini+ and that +pgbouncer+ is configured to +be listening on +localhost:6543+. + + 1. Create config file. Details in +pgbouncer(5)+. Simplest: + + [databases] + template1 = host=127.0.0.1 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 + + 2. Create users.txt file: + + "someuser" "same_password_as_in_server" + + 3. Launch +pgbouncer+: + + $ pgbouncer -d pgbouncer.ini + + 4. have your application (or the +psql+ client) connect to + +pgbouncer+ instead of directly to PostgreSQL server. + + $ psql -h 127.0.0.1 -p 6543 -U someuser template1 + + 5. manage +pgbouncer+ by connecting to special administration + database +pgbouncer+ and issue +show help;+ to begin: + + $ psql -h 127.0.0.1 -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 change some changeable configuration settings in the + configuration file, you can reload the file with: + + pgbouncer=# RELOAD; + +== COMMAND LINE SWITCHES == + +-d:: + Run in background. Without it the process will run in foreground. + +-R:: + Do a online restart. That means connecting to running process, loading + open sockets from it and using them. + +-v:: + Increase verbosity. + +-V:: + Show version. + +-h:: + Show short help. + + +== ADMIN CONSOLE == + +Console is available by connecting into standard listen_addr/listen_port +and specifying string +pgbouncer+ as database. + + $ psql -h 127.0.0.1 -p 6543 pgbouncer + +=== SHOW COMMANDS === + +There is always a extra database available: "pgbouncer". When +connecected to it, there is possible to look and change pooler +settings. + +The +SHOW+ commands output some rows, the columns contained are +described here. + +==== SHOW STATS; ==== + +Shows statistics. + +database:: + Statistics are presented per database. + +total_requests:: + Total number of +SQL+ requests pooled by +pgbouncer+. + +total_received:: + Total volume in bytes of network trafic received by +pgbouncer+. + +total_sent:: + Total volume in bytes of network trafic sent by +pgbouncer+. + +total_query_time:: + Total number of milliseconds spent by +pgloader+ when actively + connected to PostgreSQL. + +avg_req:: + Average requests per second in last stat period. + +avg_recv:: + Average received (from clients) bytes per second. + +avg_sent:: + Average sent (to clients) bytes per second. + +avg_query:: + Average query duration in milliseconds. + +==== SHOW SERVERS; ==== + +type:: + S, for server. + +user:: + +pgbouncer+ connected user. + +database:: + database name. + +state:: + State of the pgbouncer server connection, one of +active+, +used+ or + +idle+. + +addr:: + IP address of PostgreSQL server. + +port:: + Port of PostgreSQL server. + +connect_time:: + When the connection was made. + +request_time:: + When last request was issued. + +==== SHOW CLIENTS; ==== + +type:: + C, for client. + +user:: + Client connected user. + +database:: + database name. + +state:: + State of the client connection, one of +active+, +used+, +waiting+ + or +idle+. + +addr:: + IP address of client. + +port:: + port client is connected to. + +connect_time:: + Timestamp of later client connection. + +request_time:: + Timestamp of later client request. + + +==== SHOW POOLS; ==== + +A new pool entry is made for each couple of (database, user). + +database:: + database name. + +user:: + username. + +cl_active:: + Count of currently +active+ client connections. + +cl_waiting:: + Count of currently +waiting+ client connections. + +sv_active:: + Count of currently +active+ server connections. + +sv_idle:: + Count of currently +idle+ server connections. + +sv_used:: + Count of currently +used+ server connections. + +sv_tested:: + Count of currently +tested+ server connections. + +sv_login:: + Count of server connections currently +login+ to PostgreSQL. + +maxwait:: + How long has first (oldest) client in queue waited, in second. + If this start increasing, then current pool of servers does + not handle requests quick enough. Reason may be either overloaded + server or just too small pool_size. + + +==== SHOW LISTS; ==== + +Show following internal information, in columns (not rows): + +databases:: + Count of databases. + +users:: + Count of users. + +pools:: + Count of pools. + +free_clients:: + Count of free clients. + +used_clients:: + Count of used clients. + +login_clients:: + Count of clients in +login+ state. + +free_servers:: + Count of free servers. + +used_servers:: + Count of used servers. + +==== SHOW USERS; ==== + +Show one line per user, under the +name+ column name. + +==== SHOW DATABASES; ==== + +name:: + name of configured database entry. + +host:: + Host pgbouncer connects to. + +port:: + Port pgbouncer connects to. + +database:: + Actual database name pgbouncer connects to. + +force_user:: + 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. + +==== SHOW FDS; ==== + +Shows list of fds in use. When the connected user has username +"pgbouncer", connects thru unix socket and has same UID as running +process, the actual fds are passed over connection. This mechanism is +used to do online restart. + +fd:: + File descriptor numeric value. + +task:: + One of +pooler+, +client+ or +server+. + +user:: + User of the connection using the FD. + +database:: + database of the connection using the FD. + +addr:: + IP address of the connection using the FD, +unix+ if a unix socket + is used. + +port:: + port used by the connection using the FD. + +cancel:: + cancel key for this connection. + +link:: + fd for corresponding server/client. NULL if idle. + +==== SHOW CONFIG; ==== + +Show the current configuration settings, one per row, with following +columns: + +key:: + configuration variable name + +value:: + configures value + +changeable:: + Either +yes+ or +no+, shows if the variable is changeable when running. + If +no+, the variable can be changed only boot-time. + +=== PROCESS CONTROLING COMMANDS === + +==== PAUSE; ==== + +PgBouncer tries to disconnect from all servers, first waiting for all queries +to complete. The command will not return before all is done. + +==== SUSPEND; ==== + +All socket buffers are flushed and PgBouncer stops listening data on them. The +command will not return before all is done. + +==== RESUME; ==== + +Resume work from previous +PAUSE+ or +SUSPEND+ command. + +==== SHUTDOWN; ==== + +The PgBouncer process will exit. + +==== RELOAD; ==== + +The PgBouncer process will reload its configuration file and update +changeable settings. + +=== SIGNALS === + +SIGHUP:: + Reload config. Same as issuing command +RELOAD;+ on console. + +SIGINT:: + Safe shutdown. Same as issuing +PAUSE;+ and +SHUTDOWN;+ on console. + +SIGTERM:: + Immediate shutdown. Same as issuing +SHUTDOWN;+ on console. + +=== LIBEVENT SETTINGS === + +From libevent docs: + + 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. + +=== AUTHENTICATION FILE FORMAT === + +PgBouncer needs its own user database. The users are loaded from text +file that should be in same format as PostgreSQL's +pg_auth/pg_pwd+ +file. + + "username1" "password" ... + "username2" "md12342345234" ... + +There shoud be at least 2 fields, surrounded by double quotes. First +is username and second either plain-text or md5-hashed +password. PgBouncer ignores rest of the line. + +Such file format allows to direct PgBouncer directly to PostgreSQL +user file under data directory. + +== SEE ALSO == + +pgbouncer(5) - configuration settings descriptions. + +https://developer.skype.com/SkypeGarage/DbProjects/PgBouncer[] diff --git a/doc/pgbouncer.config.txt b/doc/pgbouncer.config.txt new file mode 100644 index 0000000..0a1268b --- /dev/null +++ b/doc/pgbouncer.config.txt @@ -0,0 +1,327 @@ += pgbouncer(5) = + +== NAME == + +pgbouncer - Lightweight connection pooler for PostgreSQL. + +== SYNOPSIS == + + [databases] + db = ... + + [pgbouncer] + ... + +== DESCRIPTION == + +Config file is in "ini" format. Section names are between " and +". Lines starting with ";" or "#" are taken as comment and +ignored. The characters ";" and "#" are not recognized when they +appear later in the line. + +== Section pgbouncer === + +=== Generic settings === + +==== logfile ==== + +Specifies log file. Logging is done by open/write/close, so it can be safely +rotasted, without informing pooler. + +Default: not set. + +==== pidfile ==== + +Specifies pid file. Without pidfile, the daemonization is not allowed. + +Default: not set. + +==== listen_addr ==== + +Specifies IPv4 address, where to listen for TCP connections. Or +++"*"+++ +meaning 'listen on all addresses'. When not set, only unix socket +connections are allowed. + +Default: not set. + +==== listen_port ==== + +On which port to listen on. Applies to both TCP and Unix sockets. + +Default: 6000 + +==== unix_socket_dir ==== + +Specifies location for Unix sockets. Applies to both listening socket and +server connections. If set to empty string, Unix sockets are disabled. + +Default: +/tmp+ + +==== auth_file ==== + +Load user names and passwords from this file. File format used is same as for +PostgreSQL pg_auth/pg_pwd file, so can be pointed directly to backend file. + +Default: not set. + +==== auth_type ==== + +How to authenticate users. + +md5:: + Use MD5-based password check. auth_file may contain both md5-encrypted + or plain-text passwords. Default. + +crypt:: + Use crypt(3) based bassword check. auth_file must contain plain-text + passwords. + +plain:: + Clear-text password is sent over wire. + +trust:: + No authentication is done. Username must still exists in auth_file. + +any:: + Like trust but username given is ignored. Requires that all databases + have configured to log in as specific user. + +==== pool_mode ==== + +Specifies when server connection is tagged as reusable for other clients. + +session:: + Server is released back to pool after client disconnects. Default. + +transaction:: + Server is released back to pool after transaction finishes. + +statement:: + Server is released back to pool after query finishes. Long transactions + spanning multiple statements are disallowed in this mode. + +==== max_client_conn ==== + +Maximum number of client connections allowed. + +==== default_pool_size ==== + +How many server connection to allow per user/database pair. Can be overrided in +per-database config. + +=== Log settings === + +==== log_connections ==== + +Log successful logins. + +Default: 1 + +==== log_disconnections ==== + +Log disconnections with reasons. + +Default: 1 + +==== log_pooler_errors ==== + +Log error messaged pooler sends to clients. + +Default: 1 + +=== Console access control === + +==== admin_users ==== + +List of users that are allowed to run all commands on console. + +==== stats_users ==== + +List of users that are allowed to run read-only queries on console. Thats means +all SHOW commands except SHOW FDS. + +=== Connection sanity checks, timeouts === + +==== server_check_delay ==== + +How long to keep released immidiately available, without running sanity-check +query on it. If 0 then the query is ran always. + +==== server_check_query ==== + +Good variants are +SELECT 1;+, to just see if connection is alive and ++ABORT; RESET ALL; SET SESSION AUTHORIZATION DEFAULT+ to do full +reset. + +If empty string, then sanity checking is disabled. + +==== server_lifetime ==== + +Pooler tries to close server connections that are been connected longer than +this. + +==== server_idle_timeout ==== + +If server connection has been idle more than this then there's too many +connections in the pool and this on can be dropped. + +==== server_connect_timeout ==== + +If connection and login wont finish in this time, the connection will be +closed. + +==== server_login_retry ==== + +If login failed, because of failure from connect() or authentication that +pooler waits this much before retrying to connect. + +==== 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 +problems. + +Default: 0 (disabled) + +==== client_idle_timeout ==== + +Client connections idling longer than that are closed. This should be larger +then client-side connection lifetime settings, to apply only for network +problems. + +Default: 0 (disabled) + +==== client_login_timeout ==== + +If client connect but does not manage to login in this time, it will be +disconnected. Mainly needed to avoid dead connections stalling SUSPEND and thus +online restart. + +Default: 0 (disabled) + +=== Low-level network settings === + +==== 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 +large. + +Default: 2048 + +==== tcp_defer_accept ==== + +Details about following options shouldbe looked from man 7 tcp + +Default: 45 on Linux, otherwise 0 + +==== tcp_socket_buffer ==== + +Default: not set + +==== tcp_keepalive ==== + +Default: Not set + +==== tcp_keepcnt ==== + +Default: not set + +==== tcp_keepidle ==== + +Default: not set + +==== tcp_keepintvl ==== + +Default: not set + +== Section [databases] == + +This contains key=value pairs where key will be taken as database name and +value as libpq-connstring style list of key=value pairs. As actual libpq is not +used, so not all features from libpq can be used (service=, quoting). + +=== Location parameters === + +==== dbname ==== + +Destination database name. + +Default: same as client-side database name. + +==== host ==== + +IP-address to connect to. + +Default: not set, meaning to use unix-socket. + +==== port ==== + +Default: 5432 + +==== user, password ==== + +If +user=+ is set, all connections to destination database will be +done with that user, meaning that there will be only one pool for this +database. + +Otherwise pgbouncer tries to log into destination database with client +username, meaning that there will be one pool per user. + +=== Extra parameters === + +They allow setting default parameters on server connection. + +Note that since version 1.1 PgBouncer honours client +changes for there values, so their use in pgbouncer.ini +is deprecated. + +==== client_encoding ==== + +Ask specific +client_encoding+ from server. + +==== datestyle ==== + +Ask specific +datestyle+ from server. + +==== timezone ==== + +Ask specific +timezone+ from server. + +== Example == + +=== Minimal config === + + [databases] + template1 = host=127.0.0.1 dbname=template1 + + [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 === + + [databases] + + ; foodb over unix socket + foodb = + + ; redirect bardb to bazdb on localhost + bardb = host=127.0.0.1 dbname=bazdb + + ; acceess to dest database will go with single user + forcedb = host=127.0.0.1 port=300 user=baz password=foo client_encoding=UNICODE datestyle=ISO + +== SEE ALSO == + +pgbouncer(1) + +https://developer.skype.com/SkypeGarage/DbProjects/PgBouncer[] +