How to Quickly Set Up a PostgreSQL Streaming Replication Cluster with Bitnami Docker

In a PostgreSQL replication cluster you have one master server (read‑write) and one or more slave servers (read‑only). Enabling replication lets the master handle writes while slaves serve reads, improving performance.

Replication‑related environment variables

POSTGRESQL_REPLICATION_MODE

: set to master or slave (no default). POSTGRESQL_REPLICATION_USER and POSTGRESQL_REPLICATION_PASSWORD: credentials for the replication user (no defaults). POSTGRESQL_MASTER_HOST and POSTGRESQL_MASTER_PORT_NUMBER: host/IP and port of the master (default port 5432). POSTGRESQL_REPLICATION_PASSWORD_FILE: path to a file containing the replication password, overriding the password variable.

Create the replication master

$ docker run --name postgresql-master \
  -e POSTGRESQL_REPLICATION_MODE=master \
  -e POSTGRESQL_USERNAME=my_user \
  -e POSTGRESQL_PASSWORD=password123 \
  -e POSTGRESQL_DATABASE=my_database \
  -e POSTGRESQL_REPLICATION_USER=my_repl_user \
  -e POSTGRESQL_REPLICATION_PASSWORD=my_repl_password \
  bitnami/postgresql:latest

The POSTGRESQL_REPLICATION_MODE=master flag configures the container as the master. The replication user and password are supplied via POSTGRESQL_REPLICATION_USER and POSTGRESQL_REPLICATION_PASSWORD.

Create the replication slave

$ docker run --name postgresql-slave \
  --link postgresql-master:master \
  -e POSTGRESQL_REPLICATION_MODE=slave \
  -e POSTGRESQL_MASTER_HOST=master \
  -e POSTGRESQL_MASTER_PORT_NUMBER=5432 \
  -e POSTGRESQL_REPLICATION_USER=my_repl_user \
  -e POSTGRESQL_REPLICATION_PASSWORD=my_repl_password \
  bitnami/postgresql:latest

The slave container links to the master, uses POSTGRESQL_MASTER_HOST and POSTGRESQL_MASTER_PORT_NUMBER to connect, and pulls the initial database copy using the replication credentials.

Note: The cluster fully replicates the master, including all users and databases.

Failover

If the master fails, promote a slave by creating the trigger file /tmp/postgresql.trigger.5432 inside the slave container:

$ docker exec postgresql-slave touch /tmp/postgresql.trigger.5432

Note: After promotion, update the remaining slaves to point to the new master (e.g., restart them with --link postgresql-slave:master ).

Docker Compose configuration

version: '2'
services:
  postgresql-master:
    image: 'bitnami/postgresql:latest'
    ports:
      - '5432'
    volumes:
      - 'postgresql_master_data:/bitnami/postgresql'
    environment:
      - POSTGRESQL_REPLICATION_MODE=master
      - POSTGRESQL_REPLICATION_USER=repl_user
      - POSTGRESQL_REPLICATION_PASSWORD=repl_password
      - POSTGRESQL_USERNAME=my_user
      - POSTGRESQL_PASSWORD=my_password
      - POSTGRESQL_DATABASE=my_database
  postgresql-slave:
    image: 'bitnami/postgresql:latest'
    ports:
      - '5432'
    depends_on:
      - postgresql-master
    environment:
      - POSTGRESQL_REPLICATION_MODE=slave
      - POSTGRESQL_REPLICATION_USER=repl_user
      - POSTGRESQL_REPLICATION_PASSWORD=repl_password
      - POSTGRESQL_MASTER_HOST=postgresql-master
      - POSTGRESQL_PASSWORD=my_password
      - POSTGRESQL_MASTER_PORT_NUMBER=5432
volumes:
  postgresql_master_data:

Scaling slaves

Increase the number of slaves with:

$ docker-compose up --detach --scale postgresql-master=1 --scale postgresql-slave=3

The command adds three slave containers; you can similarly scale down. Do not scale the master – only one master should run.

Synchronous commit

By default slaves use asynchronous replication. To enforce higher data safety, set the following variables: POSTGRESQL_SYNCHRONOUS_COMMIT_MODE: options on, remote_apply, remote_write, local, off. Default is on. POSTGRESQL_NUM_SYNCHRONOUS_REPLICAS: number of replicas that must acknowledge a commit (cannot exceed the number of slaves).

Example Docker Compose snippet enabling synchronous commit with one synchronous replica:

environment:
      - POSTGRESQL_SYNCHRONOUS_COMMIT_MODE=on
      - POSTGRESQL_NUM_SYNCHRONOUS_REPLICAS=1

In this setup, a transaction is considered committed only after it is written to both the master and one slave. Other slaves continue to replicate asynchronously.

Check replication status with the following SQL query:

postgres=# SELECT application_name AS server, state, sync_priority AS priority, sync_state
FROM pg_stat_replication;

Note: For advanced setups, define POSTGRESQL_CLUSTER_APP_NAME to set a custom application_name and create distinct replication groups.