git.rot13.org Git - pgpool-online-recovery/blob - README.md

   1 pgpool-online-recovery
   2 ======================
   3
   4 This simple project aims to automate and make easy the online recovery process of a failed pgpool's backend node in master/slave mode.
   5
   6 Requirements
   7 ============
   8
   9 There are two requirements to these scripts to work.
  10
  11 * The first one is [pgpool2](http://www.pgpool.net) (v3.1.3) available in [Debian Wheezy](http://packages.debian.org/stable/database/pgpool2). We assume that pgpool2 is installed, set up in master/slave mode with loadbalacing and manageable via PCP interface.
  12 * The second one is obviously Postgres server (v9.1) also available in Wheezy packages repository.
  13
  14 There are several tutorials about setting up pgpool2 and postgres servers with [Streaming Replication](http://wiki.postgresql.org/wiki/Streaming_Replication) and this readme is far to be a howto for configuring both of them. You can check out [this tutorial](https://aricgardner.com/databases/postgresql/pgpool-ii-3-0-5-with-streaming-replication/) which describes really all the steps needed.
  15
  16 Installation and configuration
  17 ==============================
  18 What about the given scripts and config files ?
  19
  20 **pgpool.conf** : This is a sample config file for pgpool that activates master/slave mode, loadbalancing, backends health check, failover, ...
  21
  22 **postgresql.conf.master** : A config file for postgres master node.
  23
  24 **postgresql.conf.slave** : A config file for postgres slave node.
  25
  26 **recovery.conf** : A config file used by postgres slave for streaming replication process.
  27
  28 **failover.sh** : This script will be executed automatically when a pgpool's backend node (postgres node) fall down. It'll switch the standby node (slave) to master (new master).
  29
  30 **online-recovery.sh** : This is the bash script which you'll execute manually in order to :
  31 * Reboot, sync and reattach slave node to pgpool if it fails.
  32 * Setup new master and new slave, sync and reattach them to pgpool if current master fails.
  33 This script will invoque remotely the script streaming-replication.sh (in the new slave node) to start the [online recovery process](http://www.postgresql.org/docs/8.1/static/backup-online.html) within the standby node.
  34 PS : When a node (master or slave) fails, pgpool still running and DBs remain available. Otherwise, pgpool will detach this node for data consistancy reasons.
  35
  36 **streaming-replication.sh** : This script can be executed manually to synchronize a slave node with a given master node (master name/ip must be passed as argument to streaming-replication.sh). Otherwise, this same script is triggred be online-recovery.sh via ssh during failback process.
  37
  38 Installation
  39 ------------
  40
  41 The installation steps are simple. You just need to copy provided bash scripts and config files as follow.
  42
  43 **In pgpool node** :
  44 * Copy pgpool.conf to /etc/pgpool2/. This is an optional operation and in this case you have to edit the default pgpool.conf file in order to looks like the config file we provided.
  45 * Copy failover.sh into /usr/local/bin/ and online-recovery.sh to your home or another directory that will be easily accessible.
  46
  47 **In the master and slave postgres nodes** :
  48 * Copy streaming-replication.sh script into /var/lib/postgresql/ (postgres homedir).
  49 * Copy postgresql.conf.master and postgresql.conf.slave files to /etc/postgresql/9.1/main/.
  50 * Finally copy recovery.conf into /var/lib/postgresql/9.1/main/.
  51
  52 PS : All similar old files must be backed up to be able to rollback in case of risk (e.g: cp -p /etc/pgpool2/pgpool.conf /etc/pgpool2/pgpool.conf.backup).
  53 Make sure that :
  54 - All scripts are executable and owned by the proper users.
  55 - /var/lib/postgresql/9.1/archive directory is created (used to archive WAL files). This directory must be owned by postgres user !
  56
  57 Not enough ! It remains only the configuration steps and we'll be done :)
  58
  59 Configuration
  60 -------------
  61
  62 To do, just follow these steps :
  63
  64 1- First of all make sure you have created a postgres user in pgpool node with SSH access to all Postgres nodes. All cluster's nodes have to be able to ssh each other. You can put "config" file with "StrictHostKeyChecking=no" option under .ssh/ directory of postgres user. This is a best practice (essencially when automating a bunch of operations) that allows postgres to ssh remote machine for the first time without prompting and validating Yes/No authorization question.
  65
  66 2- In Pgpool node set up pgpool.conf file for instance the parameters :
  67
  68         # Controls various backend behavior for instance master and slave(s).
  69         backend_hostname0='master.foo.bar'
  70         backend_port0 = 5432
  71         backend_weight0 = 1
  72         backend_data_directory0 = '/var/lib/postgres/9.1/main/'
  73         backend_flag0 = 'ALLOW_TO_FAILOVER'
  74         backend_hostname1='slave.foo.bar'
  75         backend_port1 = 5432
  76         backend_weight1 = 1
  77         backend_data_directory1 = '/var/lib/postgres/9.1/main/'
  78         backend_flag1 = 'ALLOW_TO_FAILOVER'
  79         # Pool size
  80         num_init_children = 32
  81         max_pool = 4
  82         # Master/Slave and load balancing (replication mode must be off)
  83         load_balance_mode = on
  84         master_slave_mode = on
  85         master_slave_sub_mode = 'stream'
  86         #Health check (must be set up to detecte postgres server status up/down)
  87         health_check_period = 30
  88         health_check_user = 'postgres'
  89         health_check_password = 'postgrespass'
  90         # Failover command
  91         failover_command = '/path/to/failover.sh %d %H %P /tmp/trigger_file'
  92 3- In failover.sh script, specify the proper ssh private key to postgres user to access new master  node via SSH.
  93
  94         ssh -i /var/lib/postgresql/.ssh/id_rsa postgres@$new_master "touch $trigger_file"
  95
  96 4- Idem for online-recovery.sh you have juste to change if needed the postgres's private key, the rest of params is set automatically when the script runs. Magic hein ! :)
  97
  98 5- Change the primary_conninfo access parameters (to master) in recovery.conf file in slave side :
  99
 100         primary_conninfo = 'host=master-or-slave.foo.bar port=5432 user=postgres password=nopass'
 101
 102 6- Rename recovery.conf to recovery.done in master side.
 103
 104 7- Setup postgres master node (after backup of postgresql.conf) :
 105
 106         cp -p postgresql.conf.master postgresql.conf
 107         /etc/init.d/postgresql restart
 108
 109 8- Setup postgres slave node (after backup of postgresql.conf) :
 110
 111         cp -p postgresql.conf.slave postgresql.conf
 112
 113 9- Start first slave synchronisation with master by executing streaming-replication.sh as postgres user :
 114
 115         su postgres
 116         cd ~
 117         ./streaming-replication.sh master.foo.bar
 118
 119 10- Restart pgpool :
 120
 121         /etc/init.d/pgpool2 restart
 122
 123 At his stage slave node is connected to master and both of them are connected to pgpool. If the master fails down, pgpool detach it from the pool and perform failover process (slave become master) automatically.
 124
 125 Tests
 126 =====
 127 Test PCP interface:
 128
 129         pcp_node_info
 130         pcp_detach_node
 131         pcp_attach_node
 132
 133 After starting the postgres master node you should see the following log message in /var/log/postgresql/postgresql-9.1-main.log :
 134
 135 In the postgres master log file you should see :
 136
 137 We assume that pgpool log file is /var/log/pgpool2/pgpool.log. After setting up it's convenient config file and restarting it out shoud see this message in log file :
 138