+++ /dev/null
-
-= PgBouncer FAQ =
-
-== How to connect to PgBouncer? ==
-
-PgBouncer acts as Postgres server, so simply point your client to PgBouncer port.
-
-== How to load-balance queries between several servers? ==
-
-1. Use a TCP connection load-balancer. Either http://www.linuxvirtualserver.org/[LVS]
-or http://haproxy.1wt.eu/[HAProxy] seem to be good choices. On PgBouncer
-side it may be good idea to make `server_lifetime` smaller and also
-turn `server_round_robin` on - by default idle connections are
-reused by LIFO algorithm which may work not so well when
-load-balancing is needed.
-
-2. DNS round-robin. Use several IPs behind one DNS name. PgBouncer does
-not look up DNS each time new connection is launched. Instead it caches
-all IPs and does round-robin internally. Note: if there is more than 8 IPs
-behind one name, the DNS backend must support EDNS0 protocol.
-See README for details.
-
-== How to use SSL connections with PgBouncer? ==
-
-Use http://www.stunnel.org/[Stunnel]. Since version 4.27 it
-supports PostgreSQL protocol for both client and server side.
-It is activated by setting `protocol=pgsql`.
-
-For older 4.2x versions the support code is available as patch:
-http://pgbouncer.projects.postgresql.org/patches/stunnel-postgres.diff[stunnel-postgres.diff]
-
-Alternative is to use Stunnel on both sides of connection,
-then the protocol support is not needed.
-
-
-== How to use prepared statements with session pooling? ==
-
-In session pooling mode, the reset query must clean old
-prepared statements.
-
-
-=== Cleaning prepared statements on PostgreSQL 8.3 and newer ===
-
-This is easy - just set `server_reset_query = DISCARD ALL;`
-or at least to `DEALLOCATE ALL;`
-
-=== Cleaning prepared statements on PostgreSQL 8.2 and older ===
-
-This is problematic as older versions of PostgreSQL do not allow
-easy way to drop prepared statements. Luckily there is system
-view that shows prepared plans in current session. So as a workaround
-following function can be created:
-
-----------------
-CREATE OR REPLACE FUNCTION deallocate_all()
-RETURNS void AS $$
-DECLARE
- sql record;
-BEGIN
- FOR sql IN
- SELECT 'deallocate ' || quote_ident(name) as stmt
- FROM pg_catalog.pg_prepared_statements
- LOOP
- EXECUTE sql.stmt;
- END LOOP;
-END;
-$$ LANGUAGE plpgsql;
-----------------
-
-Then the `server_reset_query` can be set to call it:
-
-----------------
-server_reset_query = RESET ALL; SET SESSION AUTHORIZATION DEFAULT; SELECT deallocate_all();
-----------------
-
-
-== How to use prepared statements with transaction pooling? ==
-
-To make prepared statements work in this mode would need PgBouncer
-to keep track of them internally, which it does not do. So only way to
-keep using PgBouncer in this mode is to disable prepared statements
-in the client.
-
-=== Disabling prepared statements in JDBC ===
-
-The proper way to do it for JDBC is adding `prepareThreshold=0`
-parameter to connect string. But current JDBC code ignores
-the setting for BEGIN/COMMIT/ROLLBACK statements and still
-tries to cache their plans. This can be fixed with following patch:
-
-http://treehou.se/~omar/postgresql-jdbc-8.4-701-pgbouncer_txn.patch[]
-
-described here:
-
-http://pgfoundry.org/pipermail/pgbouncer-general/2010-February/000507.html[]
-
-=== Disabling prepared statements in PHP/PDO ===
-
-To disable use of server-side prepared statements, the PDO attribute
-`PDO::ATTR_EMULATE_PREPARES` must be set to `true`. Either at connect-time:
-
-----------------
-$db = new PDO("dsn", "user", "pass", array(PDO::ATTR_EMULATE_PREPARES => true));
-----------------
-
-or later:
-
-----------------
-$db->setAttribute(PDO::ATTR_EMULATE_PREPARES, true);
-----------------
-
-
-
-== How to upgrade PgBouncer without dropping connections? ==
-
-This is as easy as launching new PgBouncer process with `-R` switch
-and same config:
-
-----------------
-$ pgbouncer -R -d config.ini
-----------------
-
-The `-R` (reboot) switch makes new process connect to console
-of the old process (dbname=pgbouncer) via unix socket
-and issue following commands:
-
-----------------
-SUSPEND;
-SHOW FDS;
-SHUTDOWN;
-----------------
-
-After that if new one notices old one gone it resumes work with
-old connections. The magic happens during `SHOW FDS` command which
-transports actual file descriptors to new process.
-
-If the takeover does not work for whatever reason, the new process
-can be simply killed, old one notices this and resumes work.
-
-
-== What should my server_reset_query be? ==
-
-This depends on pool mode. But in any case there is no need to put `ROLLBACK;`
-into it, as PgBouncer never re-uses connections where transaction was left open.
-If client went away in the middle of transaction, the associated server connection
-will be simply closed.
-
-=== Session pooling ===
-
-----------------
-server_reset_query = DISCARD ALL;
-----------------
-
-This will clean everything.
-
-=== Transaction pooling ===
-
-----------------
-server_reset_query =
-----------------
-
-Yes, empty. In transaction pooling mode the clients should not use
-any session-based features, so there is no need to clean anything.
-The `server_reset_query` would only add unnecessary round-trip between
-transactions and would drop various caches that the next transaction
-would unnecessarily need to fill again.
-
-== How to know which client is on which server connection? ==
-
-Use SHOW CLIENTS and SHOW SERVERS views on console.
-
-1. Use `ptr` and `link` to map local client connection to server connection.
-2. Use `addr` and `port` of client connection to identify TCP connection from client.
-3. Use `local_addr` and `local_port` to identify TCP connection to server.
-
-=== Overview of important fields in SHOW CLIENTS ===
-
-addr + port:: unique port on client host
-local_addr + local_port:: pgbouncer port
-ptr:: unique id for this connection
-link:: unique id for server connection this is currently linked to
-
-=== Overview of important fields in SHOW SERVERS ===
-
-addr + port:: server port this connects to
-local_addr + local_port:: unique port on pgbouncer host
-ptr:: unique id for this connection
-link:: unique id for client connection this is currently linked to
-
-== Should PgBouncer be installed on webserver or database server? ==
-
-It depends. Installing on webserver is good when short-connections are used,
-then the connection setup latency is minimised - TCP requires couple of packet
-roundtrips before connection is usable. Installing on database
-server is good when there are many different hosts (eg. webservers)
-connecting to it, then their connections can be optimised together.
-
-It is also possible to install PgBouncer on both webserver and database
-servers. Only negative aspect of that is that each PgBouncer hop
-adds small amount of latency to each query. So it's probably
-best to simply test whether the payoff is worth the cost.
-
+++ /dev/null
-
-= PgBouncer =
-
-Lightweight connection pooler for PostgreSQL.
-
-Downloads, bugtracker, CVS: http://pgfoundry.org/projects/pgbouncer
-
-== Features ==
-
- * 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. This is a hack as it breaks application
- expectations of backend connection. You can use it only when
- application cooperates with such usage by not using features
- that can break. See the table below for breaking features.
-
- Statement pooling::
- Most aggressive method. This is transaction pooling with a twist -
- multi-statement transactions are disallowed. This is meant to enforce
- "autocommit" mode on client, mostly targeted for PL/Proxy.
-
- * Low memory requirements (2k per connection by default). This is due
- to the fact that !PgBouncer does not need to see full packet at once.
-
- * It is not tied to one backend server, the destination databases can
- reside on different hosts.
-
- * Supports online reconfiguration for most of the settings.
-
- * Supports online restart/upgrade without dropping client connections.
-
- * Supports protocol V3 only, so backend version must be >= 7.4.
-
-== Docs ==
-
- * [http://pgbouncer.projects.postgresql.org/doc/usage.html Usage documentation]
- * [http://pgbouncer.projects.postgresql.org/doc/config.html Config file documentation]
- * [http://pgbouncer.projects.postgresql.org/doc/todo.html TODO list]
- * [http://pgbouncer.projects.postgresql.org/doc/faq.html FAQ]:
- Load-balancing, SSL, prepared statements, online restart.
-
-== SQL feature map for pooling modes ==
-
-Following table list various PostgreSQL features and whether they are
-compatible with !PgBouncer pooling modes. Note that 'transaction'
-pooling breaks client expectations of server and can be used only
-if application cooperates by not using non-working features.
-
-|| Feature || Session pooling || Transaction pooling ||
-|| Startup parameters || Yes [0] || Yes [0] ||
-|| SET/RESET || Yes || Never ||
-|| LISTEN/NOTIFY || Yes || Never ||
-|| WITHOUT HOLD CURSOR || Yes || Yes ||
-|| WITH HOLD CURSOR || Yes [1] || Never ||
-|| Protocol-level prepared plans || Yes [1] || No [2] ||
-|| PREPARE / DEALLOCATE || Yes [1] || Never ||
-|| ON COMMIT DROP temp tables || Yes || Yes ||
-|| PRESERVE/DELETE ROWS temp tables || Yes [1] || Never ||
-|| Cached plan reset || Yes [1] || Yes [1] ||
-|| LOAD statement || Yes || Never ||
-
- * [0] - Startup parameters are: `client_encoding`, `datestyle`, `timezone`
- and `standard_conforming_strings`. !PgBouncer can detect their changes
- so it can guarantee they remain consistent for client. Available
- from !PgBouncer 1.1.
- * [1] - Full transparency requires PostgreSQL 8.3 and !PgBouncer 1.1 with `server_reset_query = DISCARD ALL`
- * [2] - It is possible to add support for that into !PgBouncer.
projects / pgbouncer / commitdiff