Basic Replication

If you’re feeling overwhelmed, try setting up a slave to see how easy it is! We’ll assume that you have a running PostgreSQL installation on the IP 10.0.0.10 and that you’re setting up a slave at 10.0.0.11, with both running PostgreSQL 9.5.4.

Master Setup

First, have a look at the master’s settings (postgresql.conf) and update them if needed (and restart the server for changes to take effect):

# The WAL level should be hot_standby or logical.
wal_level = hot_standby

# Allow up to 8 standbys and backup processes to connect at a time.
max_wal_senders = 8

# Retain 1GB worth of WAL files. Adjust this depending on your transaction rate.
max_wal_size = 1GB

Next, we need to create a user. This streaming replication client in the slave node will connect to the master as this user.

$ sudo -u postgres psql

postgres=# create user rep superuser password '111111'; 
postgres=# \q #(ctrl+d)

In pg_hba.conf, allow this user to connect for replication.

# TYPE  DATABASE        USER            ADDRESS                 METHOD
host    replication     rep        　　10.0.0.11/32         　　　　md5

The user repluser is a regular Postgres user, so feel free to use your standard authentication practices. Remember to reload (sudo systemctl reload postgresql) for changes to take effect.

Slave Setup

We need to initialize the slave with a backup of the master’s databases. We’ll do this directly from the slave. Note that this process will wipe all the data on the slave.

First, let’s stop the slave:

$ sudo systemctl stop postgresql

Next, we’ll take the backup:

$ ./pg_basebackup -h 10.0.0.10 -U rep -F p -x -P -R -D /var/lib/pgsql/9.6/db/ -l replbackup

This will connect to the master as the user we just created, and take a backup of the master’s databases and write it to /var/lib/pgsql/9.6/db/. Now let’s restore this:

We need to create a file called recovery.conf in the data directory of the slave. This will tell the slave how to connect to the master.

And finally, we’ll enable the slave to serve as a read replica. To do this, enable hot_standby in postgresql.conf:

hot_standby = on

Now we’re ready to start the slave:

$sudo -u postgres ./pg_ctl  start -D /var/lib/pgsql/9.6/db/ #https://www.postgresql.org/docs/9.5/static/app-pg-ctl.html

The slave should startup, init the streaming replication and get into hot standby mode.

Congratulations! You have now setup a slave node that uses streaming replication to stay in sync with the master.

Here is how the slave behaves when you try to make changes:

postgres=# select pg_is_in_recovery();
 pg_is_in_recovery
-------------------
 t
(1 row)

postgres=# create database testme;
ERROR:  cannot execute CREATE DATABASE in a read-only transaction

Multiple Slaves

You can repeat the steps for the slave setup on another node, to bring up another slave. Ensure that max_wal_senders is high enough to accomodate all the slaves and the occasional backup or administrative process that connects to the master.

Synchronous Replication

To enable synchronous replication with one more more standby’s, first ensure that each standby has a name. You can specify the name as application_name in the primary_conninfo parameter in the standby’s recovery.conf, like this:

# In the file /var/lib/postgresql/9.6/db/recovery.conf, include the
# application name in the primary_conninfo:

standby_mode = 'on'
primary_conninfo = 'user=rep password=111111 host=10.0.0.10 port=5432 sslmode=prefer sslcompression=1 krbsrvname=postgres  application_name=kzwr'

Once each standby has a name that the master can refer to, you can edit the master’s postgresql.conf:

# Wait for standbys to finish writing out WALs to disk, before returning from
# the commit.
synchronous_commit = remote_write

# These are the standbys that need to acknowledge the write. You can also use
# '*' to indicate all the standbys.
synchronous_standby_names = 'kzwr'

Naturally, synchronous commits take more time to complete, but provide increased safety against crashes of the master server.

Cascading Replication

Rather than replicating two slaves off the same master, you can replicate one slave off another. This is usually called “cascading replication”.

A hot standby can serve as a master itself, and permit replicating off it. Nothing extra needs to be configured, other than the master settings like max_wal_senders and pg_hba.conf authentication.

Cascading replication is always asynchronous.

Slave Promotion

Slaves can be promoted to be a master. This can be done by running the command:

$ sudo pg_ctlcluster 9.5 main promote

You can also specify a file name (called a “trigger file”) in recovery.conf:

# In the file /var/lib/postgresql/9.5/main/recovery.conf, include a
# trigger file name:

trigger_file = '/tmp/pg-trigger-failover-now'

Postgres will do a failover and promote the slave if it finds that this file has been created.

After a failover, the recovery.conf file will be renamed to recovery.done. The contents of the file will not be read and considered by Postgres after that.

Before attempting the failover, ensure that the slave node has an identical configuration (including pb_hba.conf with the proper IPs) to the existing master. Also, after a successful failover, the old master should be taken out of service (“shoot the other node in the head”). Applications should not attempt to talk to the retired master.