From: Marko Kreen Date: Thu, 6 Aug 2015 20:50:56 +0000 (+0300) Subject: doc: convert readme & todo also to rst X-Git-Tag: pgbouncer_1_7_rc1~31 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=42a26b5d427581a27d2ff6f8a920885dd8c33775;p=pgbouncer doc: convert readme & todo also to rst Now they look good directly on github. --- diff --git a/README.rst b/README.rst new file mode 100644 index 0000000..eaf284c --- /dev/null +++ b/README.rst @@ -0,0 +1,126 @@ + +PgBouncer +========= + +Lightweight connection pooler for PostgreSQL. + +Homepage + https://pgbouncer.github.io + +Sources, bugtracking + https://github.com/pgbouncer/pgbouncer + +Building +--------- + +PgBouncer depends on few things to get compiled: + +* `GNU Make`_ 3.81+ +* libevent_ 2.0 +* (optional) OpenSSL_ 1.0.1 for TLS support. +* (optional) `c-ares`_ as alternative to libevent's evdns. + +.. _GNU Make: https://www.gnu.org/software/make/ +.. _libevent: http://libevent.org/ +.. _OpenSSL: https://www.openssl.org/ +.. _`c-ares`: http://c-ares.haxx.se/ + +When dependencies are installed just run:: + + $ ./configure --prefix=/usr/local --with-libevent=libevent-prefix + $ make + $ make install + +If you are building from git, or are building for Windows, please see +separate build instructions below. + +DNS lookup support +------------------ + +Starting from PgBouncer 1.4, it does hostname lookups at connect +time instead just once at config load time. This requires proper +async DNS implementation. Following list shows supported backends +and their probing order: + ++----------------------------+----------+-----------+------------+----------------+---------------------------------------+ +| backend | parallel | EDNS0 (1) | /etc/hosts | SOA lookup (2) | note | ++============================+==========+===========+============+================+=======================================+ +| c-ares | yes | yes | yes | yes | ipv6+CNAME buggy in <=1.10 | ++----------------------------+----------+-----------+------------+----------------+---------------------------------------+ +| udns | yes | yes | no | yes | ipv4-only | ++----------------------------+----------+-----------+------------+----------------+---------------------------------------+ +| evdns, libevent 2.x | yes | no | yes | no | does not check /etc/hosts updates | ++----------------------------+----------+-----------+------------+----------------+---------------------------------------+ +| getaddrinfo_a, glibc 2.9+ | yes | yes (3) | yes | no | N/A on non-linux | ++----------------------------+----------+-----------+------------+----------------+---------------------------------------+ +| getaddrinfo, libc | no | yes (3) | yes | no | N/A on win32, requires pthreads | ++----------------------------+----------+-----------+------------+----------------+---------------------------------------+ +| evdns, libevent 1.x | yes | no | no | no | buggy | ++----------------------------+----------+-----------+------------+----------------+---------------------------------------+ + +1. EDNS0 is required to have more than 8 addresses behind one hostname. +2. SOA lookup is needed to re-check hostnames on zone serial change +3. To enable EDNS0, add `options edns0` to /etc/resolv.conf + +`./configure` also has flags `--enable-evdns` and `--disable-evdns` which +turn off automatic probing and force use of either `evdns` or `getaddrinfo_a()`. + +Building from GIT +----------------- + +Building PgBouncer from GIT requires that you fetch libusual +submodule and generate the header and config files before +you can run configure:: + + $ git clone https://github.com/pgbouncer/pgbouncer.git + $ cd pgbouncer + $ git submodule init + $ git submodule update + $ ./autogen.sh + $ ./configure ... + $ make + $ make install + +Additional packages required: autoconf, automake, libtool, +autoconf-archive, python-docutils, and pkg-config. + +Building for WIN32 +------------------ + +At the moment only build env tested is MINGW32 / MSYS. Cygwin +and Visual $ANYTHING are untested. Libevent 2.x is required +for DNS hostname lookup. + +Then do the usual:: + + $ ./configure ... + $ make + +If cross-compiling from Unix:: + + $ ./configure --host=i586-mingw32msvc ... + +Running on WIN32 +---------------- + +Running from command-line goes as usual, except -d (daemonize), +-R (reboot) and -u (switch user) switches will not work. + +To run pgbouncer as a Windows service, you need to configure +`service_name` parameter to set name for service. Then:: + + $ pgbouncer -regservice config.ini + +To uninstall service:: + + $ pgbouncer -unregservice config.ini + +To use Windows Event Log, set "syslog = 1" in config file. +But before you need to register pgbevent.dll:: + + $ regsvr32 pgbevent.dll + +To unregister it, do:: + + $ regsvr32 /u pgbevent.dll + diff --git a/doc/todo.rst b/doc/todo.rst new file mode 100644 index 0000000..9f8e608 --- /dev/null +++ b/doc/todo.rst @@ -0,0 +1,74 @@ +PgBouncer TODO list +=================== + +Highly visible missing features +------------------------------- + +Significant amount of users feel the need for those. + +* Protocol-level plan cache. + +* Load-balancing / failover. + +* LISTEN/NOTIFY. Requires strict SQL format. + +Waiting for contributors... + +Problems / cleanups +------------------- + +* other per-user settings + +* Maintenance order vs. lifetime_kill_gap: + http://lists.pgfoundry.org/pipermail/pgbouncer-general/2011-February/000679.html + +* per_loop_maint/per_loop_activate take too much time in case + of moderate load and lots of pools. Perhaps active_pool_list + would help, which contains only pools touched in current loop. + +* new states for clients: idle and in-query. That allows to apply + client_idle_timeout and query_timeout without walking all clients + on maintenance time. + +* check if SQL error codes are correct + +* removing user should work - kill connections + +* keep stats about error counts + +* cleanup of logging levels, to make log more useful + +* to test: + - signal flood + - no mem / no fds handling + +* fix high-freq maintenance timer - it's only needed when + PAUSE/RESUME/shutdown is issued. + +* Get rid of SBUF_SMALL_PKT logic - it makes processing code complex. + Needs a new sbuf_prepare_*() to notify sbuf about short data. + [Plain 'false' from handler postpones processing to next event loop.] + +* units for config parameters. + +Dubious/complicated features +---------------------------- + +* User-based route. Simplest would be to move db info to pool + and fill username into dns. + +* some preliminary notification that fd limit is full + +* Move all "look-at-full-packet" situations to SBUF_EV_PKT_CALLBACK + +* `pool_mode = plproxy` - use postgres in full-duplex mode for autocommit + queries, multiplexing several queries into one connection. Should result + in more efficient CPU usage of server. + +* SMP: spread sockets over per-cpu threads. Needs confirmation that + single-threadedness can be problem. It can also be that only + accept() + login handling of short connection is problem + that could be solved by just having threads for login handling, + which would be lot simpler or just deciding that it is not + worth fixing. +