git.8kb.co.uk Git - slony-i/pgbouncer_follower/blob - README.md

   1 #PgBouncer Slony-I replication set & WAL replication follower
   2
   3 This script is a command-line utility to monitor the nodes in a Slony-I cluster
   4 and reconfigure pgbouncer to follow an origin or subscriber of replication sets.
   5 Additionally the script can be used to follow WAL streaming primary/secondary
   6 databases.
   7
   8 The idea is pretty simple; periodically poll the slony schema to identify origin
   9 and subscriber nodes and repoint an existing pgbouncer instance to follow either
  10 the origin for read-write or a subscriber for read-only operation. For binary WAL
  11 replication we instead periodically poll pg_*() functions on all servers to get a
  12 picture of replication status (pg_is_in_recovery(),pg_last_xlog_receive_location(),
  13 pg_current_xlog_location() and pg_last_xact_replay_timestamp()).
  14
  15 Side note:
  16 >Support for binary/WAL replication is an afterthought, so binary replicas are
  17 >considered followers of the primary if they're on the same timeline. In future
  18 >it should be possible to improve this for replicas using replication slots
  19 >and pull all information required from the primary by looking at pg_replication_slots/
  20 >pg_stat_replication.  It would also hopefully be possible to support following
  21 >logical replication origins similar to how we follow slony origins.
  22
  23 The script takes a template pgbouncer.ini file containing all the desired settings except
  24 for the target database and will write a copy with the target database and reload
  25 pgbouncer.  In 'ro' mode for slony replicas (not WAL replicas currently) the script
  26 will try and choose a subscriber node closest to pgbouncer host if IPv4 addressing
  27 has been used for the slony conninfos.
  28
  29 ##Example usage
  30
  31 The script can be either run on a schedule or as a daemon with the "D" flag:
  32
  33 ```bash
  34 $ pgbouncer_follower.pl -f <config file> [-D]
  35 ```
  36
  37 To run as a daemon in debian:
  38
  39 ```bash
  40 $ sudo cp init.debian /etc/init.d/pgbouncer_follower_rw
  41 $ cp pgbouncer_follower.pl /var/slony/pgbouncer_follower/pgbouncer_follower.pl
  42 $ cp pgbouncer_follower_rw.conf /var/slony/pgbouncer_follower/pgbouncer_follower_rw.conf
  43 $ sudo chmod +x /etc/init.d/pgbouncer_follower_rw
  44 $ sudo update-rc.d pgbouncer_follower_rw start 99 2 3 4 5 . stop 24 0 1 6
  45 $ sudo invoke-rc.d pgbouncer_follower_rw start
  46 ```
  47
  48 ##Configuration options
  49
  50 | Section     | Parameter              | Type    | Default                                     | Comment
  51 |:------------|:-----------------------|:--------|:--------------------------------------------|:-----------------------------------
  52 | Replication | replication_user       | text    | *'slony'*                                   | Username used to connect to PostgreSQL and select from slony schema tables
  53 | Replication | replication_pass       | text    | *''*                                        | Recommended to leave blank and use .pgpass file
  54 | Replication | replication_method     | text    | *'slony'*                                   | Specifies replication method in use, possible values 'slony' or 'wal'
  55 | Slony       | slony_cluster_name     | text    | *'replication'*                             | Name of slony cluster (without leading underscore of schema name)
  56 | Server      | server_conninfo        | text    | *null*                                      | Conninfo string for server, can be specified multiple times.  For slony only one conninfo is required (but all nodes recommended), for WAL replication all servers required
  57 | pgBouncer   | debug                  | boolean | *false*                                     | Churn out debugging info to log file / stdout
  58 | pgBouncer   | follower_poll_interval | integer | *1000*                                      | Interval to poll slony cluster state when in daemon mode
  59 | pgBouncer   | sets_to_follow         | text    | *1*                                         | Comma separated list of sets to follow or 'all' to follow all sets
  60 | pgBouncer   | pool_mode              | 'ro/rw' | *'rw'*                                      | Select a read-only subscriber or the origin for read-write
  61 | pgBouncer   | pool_all_databases     | boolean | *'false'*                                   | If true uses wildcard for database name in pgbouncer.ini, false uses slony database
  62 | pgBouncer   | auth_user              | text    | *''*                                        | If set auth_user will be appended to conninfo written in [databases] section
  63 | pgBouncer   | only_follow_origins    | boolean | *'false'*                                   | If true pgbouncer will only be reconfigured and reloaded when sets move origin
  64 | pgBouncer   | status_file            | text    | *'/tmp/pgbouncer_follower_%mode.status'*    | File used to store a hash depicting the state of the cluster
  65 | pgBouncer   | log_file               | text    | *'/tmp/pgbouncer_follower_%mode.log'*       | Log file for the script
  66 | pgBouncer   | pid_file               | text    | *'/tmp/pgbouncer_follower_%mode.log'*       | PID file for the script when run as a daemon
  67 | pgBouncer   | pool_conf_template     | text    | *'/etc/pgbouncer/pgbouncer_%mode.template'* | Template pgbouncer.ini file with your settings and a blank [databases] section
  68 | pgBouncer   | pool_conf_target       | text    | *'/etc/pgbouncer/pgbouncer_%mode.ini'*      | Target pgbouncer.ini file to write a copy of pool_conf_template with a [databases] section to
  69 | pgBouncer   | pool_reload_command    | text    | *'/etc/init.d/pgbouncer_%mode reload"'*     | System command to execute to reload pgbouncer instance
  70 | pgBouncer   | max_ro_lag             | integer | *0*                                         | Maximum lag in seconds allowed for subscriber nodes when running in ro mode. 0 = don't monitor lag.
  71
  72 The status_file, log_file, pid_file, pool_conf_template, pool_conf_target and
  73 pool_reload_command parameters can contain the following special values:
  74
  75     %mode - Pool Mode
  76     %clname - Slony cluster name