user
----
-If set, specifies the Unix user to change to after startup. Works only if
+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.
How to authenticate users.
``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.
+ 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``
- 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 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
- or plain-text passwords. This is the default authentication method.
+ Use MD5-based password check. `auth_file`_ may contain both MD5-encrypted
+ or plain-text passwords. This is the default authentication method.
``crypt``
- Use crypt(3) based password check. `auth_file`_ must contain plain-text
- passwords. Deprecated, removed in PostgreSQL 8.4.
+ Use crypt(3) based password check. `auth_file`_ must contain plain-text
+ passwords. Deprecated, removed in PostgreSQL 8.4.
``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
- databases are configured to log in as specific user. Additionally, the console
- database allows any user to log in as admin.
+ 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
----------
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
- spanning multiple statements are disallowed in this mode.
+ Server is released back to pool after query finishes. Long transactions
+ spanning multiple statements are disallowed in this mode.
max_client_conn
---------------
key and cert PgBouncer uses to accept client connections.
``disabled``
- 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 uses client-certificate, it is not validated.
+ 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.
- If client uses client-certificate, it is not validated.
+ 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
-------------------
TLS connections are disabled by default.
``disabled``
- 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,
- when refused connection will be establised over plain TCP.
- Server certificate is not validated.
+ TLS connection is always requested first from PostgreSQL,
+ when refused connection will be establised over plain TCP.
+ Server certificate is not validated.
``require``
- Connection must go over TLS. If server rejects it,
- plain TCP is not attempted. Server certificate is not validated.
+ 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 hostname is not checked
- against certificate.
+ 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``
- Connection must go over TLS and server certificate must be valid
- according to `server_tls_ca_file`_. Server hostname must match
- certificate info.
+ Connection must go over TLS and server certificate must be valid
+ according to `server_tls_ca_file`_. Server hostname must match
+ certificate info.
server_tls_ca_file
------------------
+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
+and +pgbouncer+ will create a connection to the actual server, or it
will reuse one of its existing connections.
The aim of +pgbouncer+ is to lower the performance impact of opening
rotating connections:
Session pooling
- 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.
+ 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.
- When PgBouncer notices that transaction is over, the server connection
- will be put back into the pool.
+ 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
- pool immediately after a query completes. Multi-statement
- transactions are disallowed in this mode as they would break.
+ 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'
logfile = pgbouncer.log
pidfile = pgbouncer.pid
admin_users = someuser
-
+
2. Create a users.txt file::
"someuser" "same_password_as_in_server"
=====================
``-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 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,
- 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.
- Does not work with TLS connections, they are dropped.
+ 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.
+ 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
- logging verbosity, only that stdout is not to be used.
- For use in init.d scripts.
+ 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+
- config parameter value is used as name to register under.
+ 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
=============
-The console is available by connecting as normal to the
+The console is available by connecting as normal to the
database +pgbouncer+::
$ psql -p 6543 pgbouncer
Shows statistics.
``database``
- Statistics are presented per database.
+ Statistics are presented per database.
``total_requests``
- Total number of +SQL+ requests pooled by +pgbouncer+.
+ Total number of +SQL+ requests 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_query_time``
- Total number of microseconds spent by +pgbouncer+ when actively
- connected to PostgreSQL.
+ Total number of microseconds spent by +pgbouncer+ when actively
+ connected to PostgreSQL.
``avg_req``
- Average requests per second in last stat period.
+ Average requests 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_query``
- Average query duration in microseconds.
+ Average query duration in microseconds.
SHOW SERVERS;
-------------
``type``
- S, for server.
+ S, for server.
``user``
- Username +pgbouncer+ uses to connect to server.
+ Username +pgbouncer+ uses to connect to server.
``database``
- Database name.
+ Database name.
``state``
- State of the pgbouncer server connection, one of +active+, +used+ or
- +idle+.
+ State of the pgbouncer server connection, one of +active+, +used+ or
+ +idle+.
``addr``
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.
``ptr``
- Address of internal object for this connection.
- Used as unique ID.
+ 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
- unix socket and OS supports getting process ID info, it's
- OS pid. Otherwise it's extracted from cancel packet server sent,
- which should be PID in case server is Postgres, but it's a random
- number in case server it another PgBouncer.
+ 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,
+ which should be PID in case server is Postgres, but it's a random
+ number in case server it another PgBouncer.
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+
- or +idle+.
+ 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.
``ptr``
- Address of internal object for this connection.
- Used as unique ID.
+ 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
- and OS supports getting it.
+ Process ID, in case client connects over UNIX socket
+ and OS supports getting it.
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`,
- so they needs `server_check_query` to run on it before it can be 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``
- Server connections that are currently running either `server_reset_query`
- or `server_check_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.
- 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.
+ 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``
- The pooling mode in use.
+ The pooling mode in use.
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.
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;
---------------
``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
- pgbouncer and PostgreSQL is forced to the given user, whatever the
- client 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.
+ Maximum number of server connections.
``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.
SHOW FDS;
---------
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
- is used.
+ 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;
------------
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.
- If +no+, the variable can be changed only boot-time.
+ Either +yes+ or +no+, shows if the variable can be changed while running.
+ If +no+, the variable can be changed only boot-time.
SHOW DNS_HOSTS;
---------------
Show hostnames in DNS cache.
``hostname``
- Host name.
+ Host name.
``ttl``
- How meny seconds until next lookup.
+ How meny seconds until next lookup.
``addrs``
- Comma separated list of addresses.
+ Comma separated list of addresses.
SHOW DNS_ZONES
--------------
Show DNS zones in cache.
``zonename``
- Zone name.
+ Zone name.
``serial``
- Current serial.
+ Current serial.
``count``
- Hostnames belonging to this zone.
+ Hostnames belonging to this zone.
Process controlling commands
~~~~~~~
``SIGHUP``
- Reload config. Same as issuing command +RELOAD;+ on console.
+ Reload config. Same as issuing command +RELOAD;+ on console.
``SIGINT``
- Safe shutdown. Same as issuing +PAUSE;+ and +SHUTDOWN;+ on console.
+ Safe shutdown. Same as issuing +PAUSE;+ and +SHUTDOWN;+ on console.
``SIGTERM``
- Immediate shutdown. Same as issuing +SHUTDOWN;+ on console.
+ Immediate shutdown. Same as issuing +SHUTDOWN;+ on console.
Libevent settings
~~~~~~~~~~~~~~~~~
projects / pgbouncer.git / commitdiff