From: Marko Kreen Date: Wed, 5 Aug 2015 17:22:39 +0000 (+0300) Subject: doc: remove faq & overview - they are on web now X-Git-Tag: pgbouncer_1_7_rc1~38 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=a71e164417c8713169da5411f0f68f08ee188480;p=pgbouncer doc: remove faq & overview - they are on web now its annoying to maintain things in two places --- diff --git a/doc/faq.txt b/doc/faq.txt deleted file mode 100644 index 2765165..0000000 --- a/doc/faq.txt +++ /dev/null @@ -1,202 +0,0 @@ - -= 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. - diff --git a/doc/overview.txt b/doc/overview.txt deleted file mode 100644 index d17fc72..0000000 --- a/doc/overview.txt +++ /dev/null @@ -1,76 +0,0 @@ - -= 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.