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
  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 PgBouncer does host name lookups at connect time instead of just once
  41 at configuration load time.  This requires an asynchronous DNS
  42 implementation.  The following table shows supported backends and
  43 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-glibc                      |
  51 | getaddrinfo, libc          | no       | yes (3)   | yes        | no             | N/A on Windows, requires pthreads     |
  52
  53 1. EDNS0 is required to have more than 8 addresses behind one host name.
  54 2. SOA lookup is needed to re-check host names on zone serial change.
  55 3. To enable EDNS0, add `options edns0` to `/etc/resolv.conf`.
  56
  57 c-ares is the most fully-featured implementation and is recommended
  58 for most uses and binary packaging (if a sufficiently new version is
  59 available).  libevent's built-in evdns is also suitable for many uses,
  60 with the listed restrictions.  The other backends are mostly legacy
  61 options at this point and don't receive much testing anymore.
  62
  63 By default, c-ares is used if it can be found.  Its use can be forced
  64 with `configure --with-cares` or disabled with `--without-cares`.  If
  65 c-ares is not used (not found or disabled), then specify `--with-udns`
  66 to pick udns, else libevent is used.  Specify `--disable-evdns` to
  67 disable the use of libevent's evdns and fall back to a libc-based
  68 implementation.
  69
  70 PAM authentication
  71 ------------------
  72
  73 To enable PAM authentication `./configure` has a flag `--with-pam` (default value is no). When compiled with
  74 PAM support new global authentication type `pam` appears which can be used to validate users through PAM.
  75
  76 Building from Git
  77 -----------------
  78
  79 Building PgBouncer from Git requires that you fetch libusual
  80 submodule and generate the header and config files before
  81 you can run configure:
  82
  83         $ git clone https://github.com/pgbouncer/pgbouncer.git
  84         $ cd pgbouncer
  85         $ git submodule init
  86         $ git submodule update
  87         $ ./autogen.sh
  88         $ ./configure ...
  89         $ make
  90         $ make install
  91
  92 Additional packages required: autoconf, automake, libtool, pandoc
  93
  94 Building on Windows
  95 -------------------
  96
  97 The only supported build environment on Windows is MinGW.  Cygwin and
  98 Visual $ANYTHING are not supported.
  99
 100 To build on MinGW, do the usual:
 101
 102         $ ./configure ...
 103         $ make
 104
 105 If cross-compiling from Unix:
 106
 107         $ ./configure --host=i586-mingw32msvc ...
 108
 109 Running on Windows
 110 ------------------
 111
 112 Running from command-line goes as usual, except that the -d (daemonize),
 113 -R (reboot) and -u (switch user) switches will not work.
 114
 115 To run pgbouncer as a Windows service, you need to configure the
 116 `service_name` parameter to set name for service.  Then:
 117
 118         $ pgbouncer -regservice config.ini
 119
 120 To uninstall service:
 121
 122         $ pgbouncer -unregservice config.ini
 123
 124 To use Windows Event Log, set "syslog = 1" in config file.
 125 But before you need to register pgbevent.dll:
 126
 127         $ regsvr32 pgbevent.dll
 128
 129 To unregister it, do:
 130
 131         $ regsvr32 /u pgbevent.dll