granicus.if.org Git - pgbouncer/blob - README.md

   1
   2 PgBouncer
   3 =========
   4
   5 Lightweight connection pooler for PostgreSQL.
   6
   7 Homepage: <https://pgbouncer.github.io>
   8
   9 Sources, bugtracking: <https://github.com/pgbouncer/pgbouncer>
  10
  11 Building
  12 ---------
  13
  14 PgBouncer depends on few things to get compiled:
  15
  16 * [GNU Make] 3.81+
  17 * [libevent] 2.0
  18 * [pkg-config]
  19 * [OpenSSL] 1.0.1 for TLS support.
  20 * (optional) [c-ares] as alternative to libevent's evdns.
  21
  22 [GNU Make]: https://www.gnu.org/software/make/
  23 [libevent]: http://libevent.org/
  24 [pkg-config]: https://www.freedesktop.org/wiki/Software/pkg-config/
  25 [OpenSSL]: https://www.openssl.org/
  26 [c-ares]: http://c-ares.haxx.se/
  27
  28 When dependencies are installed just run:
  29
  30     $ ./configure --prefix=/usr/local --with-libevent=libevent-prefix
  31     $ make
  32     $ make install
  33
  34 If you are building from Git, or are building for Windows, please see
  35 separate build instructions below.
  36
  37 DNS lookup support
  38 ------------------
  39
  40 Starting from PgBouncer 1.4, it does hostname lookups at connect
  41 time instead just once at config load time.  This requires proper
  42 async DNS implementation.  Following list shows supported backends
  43 and their probing order:
  44
  45 | backend                    | parallel | EDNS0 (1) | /etc/hosts | SOA lookup (2) | note                                  |
  46 |----------------------------|----------|-----------|------------|----------------|---------------------------------------|
  47 | c-ares                     | yes      | yes       | yes        | yes            | ipv6+CNAME buggy in <=1.10            |
  48 | udns                       | yes      | yes       | no         | yes            | ipv4-only                             |
  49 | evdns, libevent 2.x        | yes      | no        | yes        | no             | does not check /etc/hosts updates     |
  50 | getaddrinfo_a, glibc 2.9+  | yes      | yes (3)   | yes        | no             | N/A on non-linux                      |
  51 | getaddrinfo, libc          | no       | yes (3)   | yes        | no             | N/A on win32, requires pthreads       |
  52 | evdns, libevent 1.x        | yes      | no        | no         | no             | buggy                                 |
  53
  54 1. EDNS0 is required to have more than 8 addresses behind one hostname.
  55 2. SOA lookup is needed to re-check hostnames on zone serial change
  56 3. To enable EDNS0, add `options edns0` to /etc/resolv.conf
  57
  58 `./configure` also has flags `--enable-evdns` and `--disable-evdns` which
  59 turn off automatic probing and force use of either `evdns` or `getaddrinfo_a()`.
  60
  61 PAM authorization
  62 -----------------
  63
  64 To enable PAM authorization `./configure` has a flag `--with-pam` (default value is no). When compiled with
  65 PAM support new global authorization type `pam` appears which can be used to validate users through PAM.
  66
  67 Building from Git
  68 -----------------
  69
  70 Building PgBouncer from Git requires that you fetch libusual
  71 submodule and generate the header and config files before
  72 you can run configure:
  73
  74         $ git clone https://github.com/pgbouncer/pgbouncer.git
  75         $ cd pgbouncer
  76         $ git submodule init
  77         $ git submodule update
  78         $ ./autogen.sh
  79         $ ./configure ...
  80         $ make
  81         $ make install
  82
  83 Additional packages required: autoconf, automake, libtool, pandoc
  84
  85 Building for WIN32
  86 ------------------
  87
  88 At the moment only build env tested is MINGW32 / MSYS.  Cygwin
  89 and Visual $ANYTHING are untested.  Libevent 2.x is required
  90 for DNS hostname lookup.
  91
  92 Then do the usual:
  93
  94         $ ./configure ...
  95         $ make
  96
  97 If cross-compiling from Unix:
  98
  99         $ ./configure --host=i586-mingw32msvc ...
 100
 101 Running on WIN32
 102 ----------------
 103
 104 Running from command-line goes as usual, except -d (daemonize),
 105 -R (reboot) and -u (switch user) switches will not work.
 106
 107 To run pgbouncer as a Windows service, you need to configure
 108 `service_name` parameter to set name for service.  Then:
 109
 110         $ pgbouncer -regservice config.ini
 111
 112 To uninstall service:
 113
 114         $ pgbouncer -unregservice config.ini
 115
 116 To use Windows Event Log, set "syslog = 1" in config file.
 117 But before you need to register pgbevent.dll:
 118
 119         $ regsvr32 pgbevent.dll
 120
 121 To unregister it, do:
 122
 123         $ regsvr32 /u pgbevent.dll