How to authenticate users.
-``hba``
+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.
-``cert``
+cert
Client must connect over TLS connection with valid client cert.
Username is then taken from CommonName field from certificate.
-``md5``
+md5
Use MD5-based password check. `auth_file`_ may contain both MD5-encrypted
or plain-text passwords. This is the default authentication method.
-``crypt``
+crypt
Use crypt(3) based password check. `auth_file`_ must contain plain-text
passwords. Deprecated, removed in PostgreSQL 8.4.
-``plain``
+plain
Clear-text password is sent over wire. Deprecated.
-``trust``
+trust
No authentication is done. Username must still exist in `auth_file`_.
-``any``
+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
database allows any user to log in as admin.
Specifies when a server connection can be reused by other clients.
-``session``
+session
Server is released back to pool after client disconnects. Default.
-``transaction``
+transaction
Server is released back to pool after transaction finishes.
-``statement``
+statement
Server is released back to pool after query finishes. Long transactions
spanning multiple statements are disallowed in this mode.
and `client_tls_cert_file`_ must be also configured to set up
key and cert PgBouncer uses to accept client connections.
-``disabled``
+disabled
Plain TCP. If client requests TLS, it's ignored. Default.
-``allow``
+allow
If client requests TLS, it is used. If not, plain TCP is used.
If client uses client-certificate, it is not validated.
-``prefer``
+prefer
Same as ``allow``.
-``require``
+require
Client must use TLS. If not, client connection is rejected.
If client uses client-certificate, it is not validated.
-``verify-ca``
+verify-ca
Client must use TLS with valid client certificate.
-``verify-full``
+verify-full
Same as ``verify-ca``.
client_tls_key_file
TLS mode to use for connections to PostgreSQL servers.
TLS connections are disabled by default.
-``disabled``
+disabled
Plain TCP. TCP is not event requested from server. Default.
-``allow``
+allow
FIXME: if server rejects plain, try TLS?
-``prefer``
+prefer
TLS connection is always requested first from PostgreSQL,
when refused connection will be establised over plain TCP.
Server certificate is not validated.
-``require``
+require
Connection must go over TLS. If server rejects it,
plain TCP is not attempted. Server certificate is not validated.
-``verify-ca``
+verify-ca
Connection must go over TLS and server certificate must be valid
according to `server_tls_ca_file`_. Server hostname is not checked
against certificate.
-``verify-full``
+verify-full
Connection must go over TLS and server certificate must be valid
according to `server_tls_ca_file`_. Server hostname must match
certificate info.
DESCRIPTION
===========
-+pgbouncer+ is a PostgreSQL connection pooler. Any target application
+**pgbouncer** is a PostgreSQL connection pooler. Any target application
can be connected to +pgbouncer+ as if it were a PostgreSQL server,
and +pgbouncer+ will create a connection to the actual server, or it
will reuse one of its existing connections.
Command line switches
=====================
-``-d``
+-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.
-``-R``
+-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.
is not disabled in config. Does not work on Windows machines.
Does not work with TLS connections, they are dropped.
-``-u user``
+-u user
Switch to the given user on startup.
-``-v``
+-v
Increase verbosity. Can be used multiple times.
-``-q``
+-q
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``
+-V
Show version.
-``-h``
+-h
Show short help.
-``--regservice``
+--regservice
Win32: Register pgbouncer to run as Windows service. The +service_name+
config parameter value is used as name to register under.
-``--unregservice``
+--unregservice
Win32: Unregister Windows service.
Admin console
Shows statistics.
-``database``
+database
Statistics are presented per database.
-``total_requests``
+total_requests
Total number of +SQL+ requests pooled by +pgbouncer+.
-``total_received``
+total_received
Total volume in bytes of network traffic received by +pgbouncer+.
-``total_sent``
+total_sent
Total volume in bytes of network traffic sent by +pgbouncer+.
-``total_query_time``
+total_query_time
Total number of microseconds spent by +pgbouncer+ when actively
connected to PostgreSQL.
-``avg_req``
+avg_req
Average requests per second in last stat period.
-``avg_recv``
+avg_recv
Average received (from clients) bytes per second.
-``avg_sent``
+avg_sent
Average sent (to clients) bytes per second.
-``avg_query``
+avg_query
Average query duration in microseconds.
SHOW SERVERS;
-------------
-``type``
+type
S, for server.
-``user``
+user
Username +pgbouncer+ uses to connect to server.
-``database``
+database
Database name.
-``state``
+state
State of the pgbouncer server connection, one of +active+, +used+ or
+idle+.
-``addr``
+addr
IP address of PostgreSQL server.
-``port``
+port
Port of PostgreSQL server.
-``local_addr``
+local_addr
Connection start address on local machine.
-``local_port``
+local_port
Connection start port on local machine.
-``connect_time``
+connect_time
When the connection was made.
-``request_time``
+request_time
When last request was issued.
-``ptr``
+ptr
Address of internal object for this connection.
Used as unique ID.
-``link``
+link
Address of client connection the server is paired with.
-``remote_pid``
+remote_pid
Pid of backend server process. In case connection is made over
unix socket and OS supports getting process ID info, it's
OS pid. Otherwise it's extracted from cancel packet server sent,
SHOW CLIENTS;
-------------
-``type``
+type
C, for client.
-``user``
+user
Client connected user.
-``database``
+database
Database name.
-``state``
+state
State of the client connection, one of +active+, +used+, +waiting+
or +idle+.
-``addr``
+addr
IP address of client.
-``port``
+port
Port client is connected to.
-``local_addr``
+local_addr
Connection end address on local machine.
-``local_port``
+local_port
Connection end port on local machine.
-``connect_time``
+connect_time
Timestamp of connect time.
-``request_time``
+request_time
Timestamp of latest client request.
-``ptr``
+ptr
Address of internal object for this connection.
Used as unique ID.
-``link``
+link
Address of server connection the client is paired with.
-``remote_pid``
+remote_pid
Process ID, in case client connects over UNIX socket
and OS supports getting it.
A new pool entry is made for each couple of (database, user).
-``database``
+database
Database name.
-``user``
+user
User name.
-``cl_active``
+cl_active
Client connections that are linked to server connection and can process queries.
-``cl_waiting``
+cl_waiting
Client connections have sent queries but have not yet got a server connection.
-``sv_active``
+sv_active
Server connections that linked to client.
-``sv_idle``
+sv_idle
Server connections that unused and immediately usable for client queries.
-``sv_used``
+sv_used
Server connections that have been idle more than `server_check_delay`,
so they needs `server_check_query` to run on it before it can be used.
-``sv_tested``
+sv_tested
Server connections that are currently running either `server_reset_query`
or `server_check_query`.
-``sv_login``
+sv_login
Server connections currently in logging in process.
-``maxwait``
+maxwait
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.
-``pool_mode``
+pool_mode
The pooling mode in use.
SHOW LISTS;
Show following internal information, in columns (not rows):
-``databases``
+databases
Count of databases.
-``users``
+users
Count of users.
-``pools``
+pools
Count of pools.
-``free_clients``
+free_clients
Count of free clients.
-``used_clients``
+used_clients
Count of used clients.
-``login_clients``
+login_clients
Count of clients in +login+ state.
-``free_servers``
+free_servers
Count of free servers.
-``used_servers``
+used_servers
Count of used servers.
SHOW USERS;
-----------
-``name``
+name
The user name
-``pool_mode``
+pool_mode
The user's override pool_mode, or NULL if the default will be used instead.
SHOW DATABASES;
---------------
-``name``
+name
Name of configured database entry.
-``host``
+host
Host pgbouncer connects to.
-``port``
+port
Port pgbouncer connects to.
-``database``
+database
Actual database name pgbouncer connects to.
-``force_user``
+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``
+pool_size
Maximum number of server connections.
-``pool_mode``
+pool_mode
The database's override pool_mode, or NULL if the default will be used instead.
SHOW FDS;
This command also blocks internal event loop, so it should not be used
while PgBouncer is in use.
-``fd``
+fd
File descriptor numeric value.
-``task``
+task
One of +pooler+, +client+ or +server+.
-``user``
+user
User of the connection using the FD.
-``database``
+database
Database of the connection using the FD.
-``addr``
+addr
IP address of the connection using the FD, +unix+ if a unix socket
is used.
-``port``
+port
Port used by the connection using the FD.
-``cancel``
+cancel
Cancel key for this connection.
-``link``
+link
fd for corresponding server/client. NULL if idle.
SHOW CONFIG;
Show the current configuration settings, one per row, with following
columns:
-``key``
+key
Configuration variable name
-``value``
+value
Configuration value
-``changeable``
+changeable
Either +yes+ or +no+, shows if the variable can be changed while running.
If +no+, the variable can be changed only boot-time.
Show hostnames in DNS cache.
-``hostname``
+hostname
Host name.
-``ttl``
+ttl
How meny seconds until next lookup.
-``addrs``
+addrs
Comma separated list of addresses.
SHOW DNS_ZONES
Show DNS zones in cache.
-``zonename``
+zonename
Zone name.
-``serial``
+serial
Current serial.
-``count``
+count
Hostnames belonging to this zone.
Signals
~~~~~~~
-``SIGHUP``
+SIGHUP
Reload config. Same as issuing command +RELOAD;+ on console.
-``SIGINT``
+SIGINT
Safe shutdown. Same as issuing +PAUSE;+ and +SHUTDOWN;+ on console.
-``SIGTERM``
+SIGTERM
Immediate shutdown. Same as issuing +SHUTDOWN;+ on console.
Libevent settings
projects / pgbouncer.git / commitdiff