Use this repository to launch a streaming replication enabled TimescaleDB
cluster with 1 primary and 1 replica. It is based off of the latest-pg10
TimescaleDB docker image.
The Dockerfile takes advantage of PostgreSQL's init script
hooks
and runs replication.sh after the database has been initialized to configure
the replication settings. replication.sh uses the variables defined in
primary.env and replica.env, which are meant to be configured depending on
your desired replication settings, credentials, and networking preferences.
WARNING: While replication.sh gets run as the postgres user since it is
part of a PostgreSQL entrypoint script, the current TimescaleDB image logs in as
root by default. Be careful if making changes through docker exec or similar
commands, as making permissions changes with root will likely break things for
the postgres user. We recommend either running docker exec with
--user=postgres or running su postgres inside of the interactive shell.
The containers can either be created through regular Docker commands or through
Docker Swarm / Docker Compose using the stack.yml file.
start_containers.sh creates a Docker network bridge to connect the primary and
replica then uses the Dockerfile to run replication.sh against both database
instances.
After ensuring the variables in primary.env and replica.env match your
desired configuration, simply run:
./start_containers.shThis will create and run 2 replication-ready containers named
timescale-primary and timescale-replica.
Provided you already have a swarm intialized, you can deploy the stack using
stack.yml after building the image:
docker build -t timescale-replication .
docker stack deploy replication --compose-file stack.ymlstack.yml uses primary.env and replica.env for its environment variables,
so make changes in those files to tweak the settings.
NOTE: The stack.yml file sets the REPLICATION_SUBNET on the primary to
10.0.0.0/24 by default, allowing all traffic within the service's internal
network to connect as the replica user. To tweak this ACL, change the
REPLICATION_SUBNET variable in stack.yml. Note, however, that the technique
we use for the regular Docker setup (using getent to resolve the Docker
hostname to an exact IP -- see replication.sh) does not work inside of
Swarm. The Docker hostname resolves to Docker's service IP, which points to
the same container, but the container itself connects from a separate internal
IP, which will render any /32 subnet on the primary ineffective.
To run with Docker Compose, run:
docker build -t timescale-replication .
docker-compose -f stack.yml upNOTE: By default stack.yml sets the REPLICATION_SUBNET (used by pg_hba
to authorize IPs for replication) to 10.0.0.0/24 for compatibility with
Docker Swarm (see above). Depending on your network configuration this may
not work with Docker Compose. Either overwrite it with an appropriate subnet
setting (172.0.0.0/8 will allow all containers on the default Docker network
bridge to connect as replicas) or remove the variable altogether to force the
replication.sh to use the full IP of the replica, which should work with
Docker Compose, but will not work with Docker Swarm.
Configure various replication settings via the primary.env and replica.env
files. Whether the replication is synchronous or asynchronous (and to what
degree) can be tuned using the SYNCRHONOUS_COMMIT variable in primary.env.
The setting defaults to off, enabling fully asynchronous streaming
replication. The other valid values are on, local, remote_write, and
remote_apply. Consult our [documentation][timescale-streamrep-docs] for
further details about trade-offs (i.e., performance vs. lag time, etc).