pgbouncer [-d][-R][-v][-u user] <pgbouncer.ini>
pgbouncer -V|-h
-The windows environment serves as the following options.
+On Windows computers, the options are:
pgbouncer.exe [-v][-u user] <pgbouncer.ini>
pgbouncer.exe -V|-h
-Furthermore, this option is specially offered for windows-service.
+Additional options for setting up a Windows service:
- <windows service registration>
- -regservice [servicename]
- -unregservice [servicename]
- -listengines [servicename]
- -addengine [servicename] config.ini
- -delengine [servicename] config.ini
+ pgbouncer.exe -regservice <pgbouncer.ini>
+ pgbouncer.exe -unregservice <pgbouncer.ini>
== 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.
+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
new connections to PostgreSQL.
In order not to compromise transaction semantics for connection
-pooling, +pgbouncer+ supports several levels of brutality when
+pooling, +pgbouncer+ supports several types of pooling 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.
+ 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::
- 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.
+ 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 immidiately after a query completes. Multi-statement
+ 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
Basic setup and usage as following.
- 1. Create config file. Details in +pgbouncer(5)+. Simplest:
+ 1. Create a pgbouncer.ini file. Details in +pgbouncer(5)+. Simple example:
[databases]
template1 = host=127.0.0.1 port=5432 dbname=template1
pidfile = pgbouncer.pid
admin_users = someuser
- 2. Create users.txt file:
+ 2. Create a users.txt file:
"someuser" "same_password_as_in_server"
$ pgbouncer -d pgbouncer.ini
- 4. have your application (or the +psql+ client) connect to
+ 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
+ $ psql -p 6543 -U someuser template1
- 5. manage +pgbouncer+ by connecting to special administration
- database +pgbouncer+ and issue +show help;+ to begin:
+ 5. Manage +pgbouncer+ by connecting to the special administration
+ database +pgbouncer+ and issuing +show help;+ to begin:
- $ psql -h 127.0.0.1 -p 6543 -U someuser pgbouncer
+ $ psql -p 6543 -U someuser pgbouncer
pgbouncer=# show help;
NOTICE: Console usage
DETAIL:
RESUME
SHUTDOWN
- 6. If you change some changeable configuration settings in the
- configuration file, you can reload the file with:
+ 6. If you made changes to the pgbouncer.ini file, you can reload it with:
pgbouncer=# RELOAD;
-d::
Run in background. Without it the process will run in foreground.
- Note: The windows environment should use the special option for service
- operation.
+ Note: Does not work on Windows, +pgbouncer+ need to run as service there.
-R::
- Do a online restart. That means connecting to running process, loading
- open sockets from it and using them. If there is no active process,
- boot normally.
- Note: The windows environment is not equipped.
+ 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: Does not work on Windows machines.
-u user::
- Switch to user on startup.
+ Switch to the given user on startup.
-v::
Increase verbosity. Can be used multiple times.
-q::
- Be quiet - don't 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.
-h::
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.
+
+-unregservice::
+ Win32: Unregister Windows service.
== ADMIN CONSOLE ==
-Console is available by connecting into standard listen_addr/listen_port
-and specifying string +pgbouncer+ as database.
+The console is available by connecting as normal to the
+database +pgbouncer+
- $ psql -h 127.0.0.1 -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_mode=any`, then
-any user is allowed in as admin.)
+any user is allowed in as an admin.)
-Additionally, 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 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 ===
-The +SHOW+ commands output some rows, the columns contained are
-described here.
+The +SHOW+ commands output information. Each command is described below.
==== SHOW STATS; ====
Username +pgbouncer+ uses to connect to server.
database::
- database name on server.
+ Database name.
state::
State of the pgbouncer server connection, one of +active+, +used+ or
Client connected user.
database::
- database name.
+ Database name.
state::
State of the client connection, one of +active+, +used+, +waiting+
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 port on local machine.
connect_time::
- Timestamp of later client connection.
+ Timestamp of connect time.
request_time::
- Timestamp of later client request.
+ Timestamp of latest client request.
ptr::
Address of internal object for this connection.
A new pool entry is made for each couple of (database, user).
database::
- database name.
+ Database name.
user::
- username.
+ Username.
cl_active::
Count of currently +active+ client connections.
Count of currently +tested+ server connections.
sv_login::
- Count of server connections currently +login+ to PostgreSQL.
+ Count of server connections currently +logged in+ to PostgreSQL.
maxwait::
- How long has first (oldest) client in queue waited, in second.
- If this start increasing, then current pool of servers does
+ 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 pool_size.
+ server or just too small of a +pool_size+ setting.
==== SHOW LISTS; ====
==== SHOW USERS; ====
-Show one line per user, under the +name+ column name.
+Shows one line per user, under the +name+ column name.
==== SHOW DATABASES; ====
name::
- name of configured database entry.
+ Name of configured database entry.
host::
Host pgbouncer connects to.
==== 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.
-Note: The windows environment is not supported.
+"pgbouncer", connects through Unix socket and has same UID as 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.
fd::
File descriptor numeric value.
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.
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.
columns:
key::
- configuration variable name
+ Configuration variable name
value::
- configures value
+ Configuration value
changeable::
- Either +yes+ or +no+, shows if the variable is changeable when running.
+ Either +yes+ or +no+, shows if the variable can be changed while running.
If +no+, the variable can be changed only boot-time.
=== PROCESS CONTROLLING 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. To be used
+to complete. The command will not return before all queries are finished. To be used
at the time of database restart.
==== SUSPEND; ====
-All socket buffers are flushed and PgBouncer stops listening data on them. The
-command will not return before all is done. To be used at the time of
-PgBouncer restart.
+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
+of PgBouncer online reboot.
==== RESUME; ====
pgbouncer(5) - manpage of configuration settings descriptions.
+http://pgbouncer.projects.postgresql.org/doc/[]
+
https://developer.skype.com/SkypeGarage/DbProjects/PgBouncer[]
+
projects / pgbouncer / commitdiff