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.
+and "#" are not recognized as special when they appear later in the line.
## Generic settings
### logfile
-Specifies log file. Log file is kept open so after rotation `kill -HUP`
+Specifies the log file. The 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.
+On Windows, the service must be stopped and started.
-Default: not set.
+Default: not set
### pidfile
-Specifies the pid file. Without a pidfile, daemonization is not allowed.
+Specifies the PID file. Without `pidfile` set, daemonization is not allowed.
-Default: not set.
+Default: not set
### listen_addr
-Specifies list of addresses, where to listen for TCP connections.
+Specifies a list of addresses where to listen for TCP connections.
You may also use `*` meaning "listen on all addresses". When not set,
-only Unix socket connections are allowed.
+only Unix socket connections are accepted.
Addresses can be specified numerically (IPv4/IPv6) or by name.
Specifies location for Unix sockets. Applies to both listening socket and
server connections. If set to an empty string, Unix sockets are disabled.
Required for online reboot (-R) to work.
-Note: Not supported on Windows machines.
+Not supported on Windows.
Default: /tmp
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.
-
-Note: Not supported on Windows machines.
+Not supported on Windows.
Default: not set
The name of the file to load user names and passwords from. See
section [Authentication file format](#authentication-file-format) below about details.
-Default: not set.
+Default: not set
### auth_hba_file
HBA configuration file to use when `auth_type` is `hba`.
-Supported from version 1.7 onwards.
Default: not set
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 "pgbouncer". Also, `pam` is still not supported in HBA configuration file.
+ compatible with databases using the `auth_user` option. The service name reported to
+ PAM is "pgbouncer". `pam` is not supported in the HBA configuration file.
hba
-: 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
- must use TLS. Supported from version 1.7 onwards.
+: The actual authentication type is loaded from `auth_hba_file`. This allows different
+ authentication methods for different access paths, for example: connections
+ over Unix socket use the `peer` auth method, connections over TCP
+ must use TLS.
cert
-: Client must connect over TLS connection with valid client cert.
- Username is then taken from CommonName field from certificate.
+: Client must connect over TLS connection with a valid client certificate.
+ The user name is then taken from the CommonName field from the certificate.
md5
: Use MD5-based password check. This is the default authentication
- method. `auth_file` may contain both MD5-encrypted or plain-text
+ method. `auth_file` may contain both MD5-encrypted and plain-text
passwords. If `md5` is configured and a user has a SCRAM secret,
then SCRAM authentication is used automatically instead.
connections, use plain-text passwords.
plain
-: Clear-text password is sent over wire. Deprecated.
+: The clear-text password is sent over the wire. Deprecated.
trust
-: No authentication is done. Username must still exist in `auth_file`.
+: No authentication is done. The user name must still exist in `auth_file`.
any
-: 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
+: Like the `trust` method, but the user name given is ignored. Requires that all
+ databases are configured to log in as a specific user. Additionally, the console
database allows any user to log in as admin.
### auth_query
Query to load user's password from database.
Direct access to pg_shadow requires admin rights. It's preferable to
-use non-admin user that calls SECURITY DEFINER function instead.
+use a non-superuser that calls a 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.
+Note that the query is run inside the 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
-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, then any user not specified in `auth_file` will be
+queried through the `auth_query` query from pg_shadow in the database,
+using `auth_user`. The password of `auth_user` 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.
+use a non-superuser that calls a SECURITY DEFINER function instead.
-Default: not set.
+Default: not set
### pool_mode
: 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. Transactions
spanning multiple statements are disallowed in this mode.
### 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:
+descriptor limits should also be increased. Note that the actual number of file
+descriptors used is more than `max_client_conn`. The theoretical maximum used is:
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),
+if each user connects under its own user name to the server. If a database user
+is specified in the connection string (all users connect under the same user name),
the theoretical maximum is:
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
+crafts a 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.
Add more server connections to pool if below this number.
Improves behavior when usual load comes suddenly back after period
-of total inactivity.
+of total inactivity. The value is effectively capped at the pool size.
Default: 0 (disabled)
### reserve_pool_size
-How many additional connections to allow to a pool. 0 disables.
+How many additional connections to allow to a pool (see `reserve_pool_timeout`). 0 disables.
Default: 0 (disabled)
### 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.
+If a client has not been serviced in this many seconds,
+use additional connections from the reserve pool. 0 disables.
Default: 5.0
### max_db_connections
-Do not allow more than this many connections per-database (regardless of pool - i.e.
+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
to one pool will not immediately allow a server connection to be established for
another pool, because the server connection for the first pool is still open.
### max_user_connections
-Do not allow more than this many connections per-user (regardless of pool - i.e.
+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
to one pool will not immediately allow a server connection to be established for
another pool, because the server connection for the first pool is still open.
### server_round_robin
-By default, pgbouncer reuses server connections in LIFO (last-in, first-out) manner,
+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
a single server serving a database. But if there is TCP round-robin behind a database
-IP, then it is better if pgbouncer also uses connections in that manner, thus
+IP address, then it is better if PgBouncer also uses connections in that manner, thus
achieving uniform load.
Default: 0
### 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.
+specified here, so that PgBouncer knows that they are handled by the admin and it can ignore them.
Default: empty
Disable Simple Query protocol (PQexec). Unlike Extended Query protocol, Simple Query
allows multiple queries in one packet, which allows some classes of SQL-injection
attacks. Disabling it can improve security. Obviously this means only clients that
-exclusively use Extended Query protocol will stay working.
+exclusively use the Extended Query protocol will stay working.
Default: 0
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
-only on start of connection, if application_name is later changed with SET,
-pgbouncer does not change it again.
+only on start of connection. If `application_name` is later changed with SET,
+PgBouncer does not change it again.
Default: 0
Show location of current config file. Changing it will make PgBouncer use another
config file for next `RELOAD` / `SIGHUP`.
-Default: file from command line.
+Default: file from command line
### service_name
### syslog
-Toggles syslog on/off
-As for windows environment, eventlog is used instead.
+Toggles syslog on/off.
+On Windows, the event log is used instead.
Default: 0
### log_pooler_errors
-Log error messages pooler sends to clients.
+Log error messages the pooler sends to clients.
Default: 1
### verbose
-Increase verbosity. Mirrors "-v" switch on command line.
-Using "-v -v" on command line is same as `verbose=2` in config.
+Increase verbosity. Mirrors the "-v" switch on the command line.
+Using "-v -v" on the command line is the same as `verbose=2`.
Default: 0
### 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`,
-in which case any username is allowed in as admin.
+run all commands on the console. Ignored when `auth_type` is `any`,
+in which case any user name is allowed in as admin.
Default: empty
### 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
+run read-only queries on the console. That means all SHOW commands except
SHOW FDS.
-Default: empty.
+Default: empty
## Connection sanity checks, timeouts
available to other clients. At that moment no transaction is in
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
+The query is supposed to clean any changes made to the database session
+so that the next client gets the connection in a well-defined state. The default is
+`DISCARD ALL` which cleans everything, but that leaves the 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
+to just drop prepared statements, if the application does not break when
some state is kept around.
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.
+ends up in a different connection and thus gets a different session state.
Default: DISCARD ALL
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.
+should not have any need for a reset query.
-It is workaround for broken setups that run apps that use session features
-over transaction-pooled pgbouncer. Is changes non-deterministic breakage
-to deterministic breakage - client always lose their state after each
+This setting is for working around broken setups that run applications that use session features
+over a transaction-pooled PgBouncer. It changes non-deterministic breakage
+to deterministic breakage: Clients always lose their state after each
transaction.
Default: 0
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
-**RECONNECT**, **RELOAD** that changes connection settings, or DNS
+`RECONNECT`, `RELOAD` that changes connection settings, or DNS
change), rather than waiting for the session end. In statement or
transaction pooling mode, this has no effect since that is the default
behavior there.
### client_login_timeout
-If a client connects but does not manage to login in this amount of time, it
+If a client connects but does not manage to log in in this amount of time, it
will be disconnected. Mainly needed to avoid dead connections stalling
SUSPEND and thus online restart. [seconds]
### 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.
-Actual DNS TTL is ignored. [seconds]
+several answers, PgBouncer will robin-between them in the meantime.
+The actual DNS TTL is ignored. [seconds]
Default: 15.0
### dns_zone_check_period
-Period to check if zone serial has changed.
+Period to check if a zone serial has changed.
PgBouncer can collect DNS zones from host names (everything after first dot)
-and then periodically check if zone serial changes.
+and then periodically check if the zone serial changes.
If it notices changes, all host names under that zone
are looked up again. If any host IP changes, its connections
are invalidated.
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
-key and cert PgBouncer uses to accept client connections.
+the key and certificate PgBouncer uses to accept client connections.
disable
: 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 uses client-certificate, it is not validated.
+ If the client presents a client certificate, it is not validated.
prefer
: Same as `allow`.
require
-: Client must use TLS. If not, client connection is rejected.
- If client uses client-certificate, it is not validated.
+: Client must use TLS. If not, the client connection is rejected.
+ If the client presents a client certificate, it is not validated.
verify-ca
: Client must use TLS with valid client certificate.
Private key for PgBouncer to accept client connections.
-Default: not set.
+Default: not set
### client_tls_cert_file
Certificate for private key. Clients can validate it.
-Default: not set.
+Default: not set
### client_tls_ca_file
Root certificate file to validate client certificates.
-Default: unset.
+Default: not set
### client_tls_protocols
TLS connections are disabled by default.
disable
-: Plain TCP. TCP is not event requested from server. Default.
+: Plain TCP. TCP is not even requested from the server. Default.
allow
: FIXME: if server rejects plain, try TLS?
verify-full
: Connection must go over TLS and server certificate must be valid
according to `server_tls_ca_file`. Server host name must match
- certificate info.
+ certificate information.
### server_tls_ca_file
Root certificate file to validate PostgreSQL server certificates.
-Default: unset.
+Default: not set
### server_tls_key_file
Private key for PgBouncer to authenticate against PostgreSQL server.
-Default: not set.
+Default: not set
### server_tls_cert_file
Certificate for private key. PostgreSQL server can validate it.
-Default: not set.
+Default: not set
### server_tls_protocols
## Dangerous timeouts
-Setting following timeouts cause unexpected errors.
+Setting the following timeouts can cause unexpected errors.
### query_timeout
is not assigned to a server during that time, the client is disconnected. This
is used to prevent unresponsive servers from grabbing up connections. [seconds]
-It also helps when server is down or database rejects connections for any reason.
-If this is disabled, clients will be queued infinitely.
+It also helps when the server is down or database rejects connections for any reason.
+If this is disabled, clients will be queued indefinitely.
Default: 120
### idle_transaction_timeout
-If client has been in "idle in transaction" state longer,
+If a client has been in "idle in transaction" state longer,
it will be disconnected. [seconds]
Default: 0.0 (disabled)
### suspend_timeout
How many seconds to wait for buffer flush during SUSPEND or reboot (-R).
-Connection is dropped if flush does not succeed.
+A connection is dropped if the flush does not succeed.
Default: 10
### 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
+memory usage. Actual libpq packets can be larger than this, so no need to set it
large.
Default: 4096
### 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.
+attempts are kept in queue. When the queue is full, further new connections are dropped.
Default: 128
### 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
Turns on basic keepalive with OS defaults.
-On Linux, the system defaults are **tcp_keepidle=7200**, **tcp_keepintvl=75**,
-**tcp_keepcnt=9**. They are probably similar on other OS-es.
+On Linux, the system defaults are tcp_keepidle=7200, tcp_keepintvl=75,
+tcp_keepcnt=9. They are probably similar on other operating systems.
Default: 1
## 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).
+This contains key=value pairs where the key will be taken as a database name and the
+value as a libpq connection string style list of key=value pairs.
+Not all features known from libpq can be used (service=, .pgpass), since the actual
+libpq is not used.
-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.
+The database name can contain characters `_0-9A-Za-z` without quoting.
+Names that contain other characters need to be quoted with standard SQL
+identifier quoting: double quotes, with "" for a single instance of a double quote.
-"*" acts as fallback database: if the exact name does not exist,
-its value is taken as connect string for requested database.
+"*" acts as a fallback database: if the exact name does not exist,
+its value is taken as connection 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 than the time specified by the `autodb_idle_timeout`
parameter.
### dbname
Destination database name.
-Default: same as client-side database name.
+Default: same as client-side database name
### 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 connection 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.
If DNS returns several results, they are used in round-robin
manner.
-Default: not set, meaning to use a Unix socket.
+Default: not set, meaning to use a Unix socket
### port
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.
+Otherwise, PgBouncer logs into the destination database with the client
+user name, meaning that there will be one pool per user.
### password
### pool_size
-Set maximum size of pools for this database. If not set,
-the default_pool_size is used.
+Set the maximum size of pools for this database. If not set,
+the `default_pool_size` is used.
### reserve_pool
-Set additional connections for this database. If not set, reserve_pool_size is
+Set additional connections for this database. If not set, `reserve_pool_size` is
used.
### connect_query
### pool_mode
Set the pool mode specific to this database. If not set,
-the default pool_mode is used.
+the default `pool_mode` is used.
### max_db_connections
### timezone
-Ask specific **timezone** from server.
+Ask specific `timezone` from server.
## Section [users]
This contains key=value pairs where the key will be taken as a user name and
-the value as a libpq connect-string style list of key=value pairs of
+the value as a libpq connection string style list of key=value pairs of
configuration settings specific for this user. Only a few settings
are available here.
### 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.
+database or default `pool_mode` is used.
### max_user_connections
## Include directive
-The PgBouncer config file can contain include directives, which specify
-another config file to read and process. This allows for splitting the
+The PgBouncer configuration file can contain include directives, which specify
+another configuration file to read and process. This allows splitting the
configuration file into physically separate parts. The include directives look
like this:
## Authentication file format
PgBouncer needs its own user database. The users are loaded from a text
-file in following format:
+file in the following format:
"username1" "password" ...
"username2" "md5abcdef012342345" ...
"username2" "SCRAM-SHA-256$<iterations>:<salt>$<storedkey>:<serverkey>"
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, a MD5-hidden
+field is the user name and the second is either a plain-text, a MD5-hashed
password, or a SCRAM secret. PgBouncer ignores the rest of the line.
-PostgreSQL MD5-hidden password format:
+PostgreSQL MD5-hashed password format:
"md5" + md5(password + username)
-So user `admin` with password `1234` will have MD5-hidden password
+So user `admin` with password `1234` will have MD5-hashed password
`md545f2603610af569b6155c45067268c6b`.
PostgreSQL SCRAM secret format:
* Supported record types: `local`, `host`, `hostssl`, `hostnossl`.
* Database field: Supports `all`, `sameuser`, `@file`, multiple names. Not supported: `replication`, `samerole`, `samegroup`.
-* Username field: Supports `all`, `@file`, multiple names. Not supported: `+groupname`.
+* User name field: Supports `all`, `@file`, multiple names. Not supported: `+groupname`.
* Address field: Supported IPv4, IPv6. Not supported: DNS names, domain prefixes.
* Auth-method field: Only methods supported by PgBouncer's `auth_type`
are supported, except `any` and `pam`, which only work globally.
- Username map (`map=`) parameter is not supported.
+ User name map (`map=`) parameter is not supported.
## Example
[pgbouncer]
pool_mode = session
- listen_port = 6543
+ listen_port = 6432
listen_addr = 127.0.0.1
auth_type = md5
auth_file = users.txt
## See also
-pgbouncer(1) - man page for general usage, console commands.
+pgbouncer(1) - man page for general usage, console commands
<https://pgbouncer.github.io/>
pgbouncer [-d][-R][-v][-u user] <pgbouncer.ini>
pgbouncer -V|-h
-On Windows computers, the options are:
+On Windows, the options are:
pgbouncer.exe [-v][-u user] <pgbouncer.ini>
pgbouncer.exe -V|-h
Session pooling
-: Most polite method. When client connects, a server connection will
+: Most polite method. When a 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 a 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 the
pool immediately after a query completes. Multi-statement
transactions are disallowed in this mode as they would break.
## Quick-start
-Basic setup and usage as following.
+Basic setup and usage is as follows.
1. Create a pgbouncer.ini file. Details in **pgbouncer(5)**. Simple example:
template1 = host=127.0.0.1 port=5432 dbname=template1
[pgbouncer]
- listen_port = 6543
+ listen_port = 6432
listen_addr = 127.0.0.1
auth_type = md5
auth_file = userlist.txt
pidfile = pgbouncer.pid
admin_users = someuser
-2. Create `userlist.txt` file that contains users allowed in:
+2. Create a `userlist.txt` file that contains the users allowed in:
"someuser" "same_password_as_in_server"
$ 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 the PostgreSQL server:
- $ psql -p 6543 -U someuser template1
+ $ psql -p 6432 -U someuser template1
5. Manage **pgbouncer** by connecting to the special administration
database **pgbouncer** and issuing `SHOW HELP;` to begin:
- $ psql -p 6543 -U someuser pgbouncer
+ $ psql -p 6432 -U someuser pgbouncer
pgbouncer=# SHOW HELP;
NOTICE: Console usage
DETAIL:
## Command line switches
-d
-: Run in background. Without it the process will run in foreground.
- Note: Does not work on Windows, **pgbouncer** need to run as service there.
+: Run in the background. Without it, the process will run in the 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,
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`
- is not disabled in config. Does not work on Windows machines.
+ is not disabled in configuration. Does not work on Windows.
Does not work with TLS connections, they are dropped.
-u user
: 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. This does not affect
logging verbosity, only that stdout is not to be used.
For use in init.d scripts.
--regservice
: Win32: Register pgbouncer to run as Windows service. The **service_name**
- config parameter value is used as name to register under.
+ configuration parameter value is used as the name to register under.
--unregservice
: Win32: Unregister Windows service.
The console is available by connecting as normal to the
database **pgbouncer**:
- $ psql -p 6543 pgbouncer
+ $ psql -p 6432 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
+Only users listed in the configuration parameters **admin_users** or **stats_users**
+are allowed to log in to the console. (Except when `auth_type=any`, then
any user is allowed in as a stats_user.)
-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
+Additionally, the user name **pgbouncer** is allowed to log in without password,
+if the login comes via the Unix socket and the client has same Unix user UID
as the running process.
### Show commands
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 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
remote_pid
: 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.
+ OS PID. Otherwise it's extracted from cancel packet the server sent,
+ which should be the PID in case the server is PostgreSQL, but it's a random
+ number in case the server it is another PgBouncer.
tls
: A string with TLS connection information, or empty if not using TLS.
: 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 that have sent queries but have not yet got a server connection.
sv_active
-: Server connections that linked to client.
+: Server connections that are linked to a client.
sv_idle
-: Server connections that unused and immediately usable for client queries.
+: Server connections that are unused and immediately usable for client queries.
sv_used
-: 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.
+: Server connections that have been idle for more than `server_check_delay`,
+ so they need `server_check_query` to run on them before they can be used again.
sv_tested
: 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 the process of logging in.
maxwait
-: How long the first (oldest) client in queue has waited, in seconds.
+: How long the first (oldest) client in the 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
+ not handle requests quickly enough. The reason may be either an overloaded
server or just too small of a **pool_size** setting.
maxwait_us
: Actual database name pgbouncer connects to.
force_user
-: When user is part of the connection string, the connection between
+: When the user is part of the connection string, the connection between
pgbouncer and PostgreSQL is forced to the given user, whatever the
client user.
Internal command - shows list of file descriptors in use with internal state attached to them.
-When the connected user has user name "pgbouncer", connects through Unix socket
-and has same UID as the running process, the actual FDs are passed over the connection.
+When the connected user has the user name "pgbouncer", connects through the Unix socket
+and has same the UID as the running process, the actual FDs are passed over the connection.
This mechanism is used to do an online restart.
-Note: This does not work on Windows machines.
+Note: This does not work on Windows.
This command also blocks the internal event loop, so it should not be used
while PgBouncer is in use.
#### SHOW CONFIG
-Show the current configuration settings, one per row, with following
+Show the current configuration settings, one per row, with the following
columns:
key
### Libevent settings
-From libevent docs:
+From the Libevent documentation:
> It is possible to disable support for epoll, kqueue, devpoll, poll
> or select by setting the environment variable EVENT_NOEPOLL,
## See also
-pgbouncer(5) - man page of configuration settings descriptions.
+pgbouncer(5) - man page of configuration settings descriptions
<https://pgbouncer.github.io/>
projects / pgbouncer / commitdiff