Fix #90 and replace references to slave with replicant

(Slave is a pejorative term)
pull/94/head
Tim Sutton 2018-03-22 09:06:45 +02:00 zatwierdzone przez GitHub
rodzic d9d6cd34a7
commit 240f45414f
Nie znaleziono w bazie danych klucza dla tego podpisu
ID klucza GPG: 4AEE18F83AFDEB23
1 zmienionych plików z 31 dodań i 22 usunięć

Wyświetl plik

@ -159,39 +159,48 @@ for the docker process to read / write it.
## Postgres Replication Setup
This image were provided with replication abilities. In some sense, we can
categorize an instance of the container as `master` or `slave`. A `master`
Replication allows you to maintain two or more synchronised copies of a database, with a
single **master** copy and one or more **replicant** copies. The animation below illustrates
this - the layer with the red boundary is accessed from the master database and the layer
with the green fill is accessed from the replicant database. When edits to the master
layer are saved, they are automatically propogated to the replicant. Note also that the
replicant is read-only.
![qgis](https://user-images.githubusercontent.com/178003/37755610-dd3b774a-2dae-11e8-9fa1-4877e2034675.gif)
This image is provided with replication abilities. We can
categorize an instance of the container as `master` or `replicant`. A `master`
instance means that a particular container have a role as a single point of
database write. A `slave` instance means that a particular container will
database write. A `replicant` instance means that a particular container will
mirror database content from a designated master. This replication scheme allows
us to sync database. However a `slave` is only of read-only transaction, thus
us to sync database. However a `replicant` is only of read-only transaction, thus
we can't write new data on it.
To experiment with the replication abilities, you can see a (docker-compose.yml)[sample/replication/docker-compose.yml]
sample provided. There are several environment variables that you can set, such as:
Master settings:
- ALLOW_IP_RANGE: A pg_hba.conf domain format which will allow certain host
- **ALLOW_IP_RANGE**: A pg_hba.conf domain format which will allow certain host
to connect into the container. This is needed to allow `slave` to connect
into `master`, so specifically this settings should allow `slave` address.
- Both POSTGRES_USER and POSTGRES_PASS will be used as credentials for slave to
connect, so make sure you changed this into something secure.
Slave settings:
- REPLICATE_FROM: This should be the domain name, or ip address of `master`
- **REPLICATE_FROM**: This should be the domain name, or ip address of `master`
instance. It can be anything from docker resolved name like written in the sample,
or the IP address of the actual machine where you expose `master`. This is
useful to create cross machine replication, or cross stack/server.
- REPLICATE_PORT: This should be the port number of `master` postgres instance.
- **REPLICATE_PORT**: This should be the port number of `master` postgres instance.
Will default to 5432 (default postgres port), if not specified.
- DESTROY_DATABASE_ON_RESTART: Default is `True`. Set to otherwise to prevent
this behaviour. A slave will always destroy its current database on
- **DESTROY_DATABASE_ON_RESTART**: Default is `True`. Set to otherwise to prevent
this behaviour. A replicant will always destroy its current database on
restart, because it will try to sync again from `master` and avoid inconsistencies.
- PROMOTE_MASTER: Default none. If set to any value, then the current slave
- **PROMOTE_MASTER**: Default none. If set to any value, then the current replicant
will be promoted to master.
In some cases when `master` container has failed, we might want to use our `slave`
as `master` for a while. However promoted slave will break consistencies and
is not able to revert to slave anymore, unless the were destroyed and resynced
In some cases when `master` container has failed, we might want to use our `replicant`
as `master` for a while. However promoted replicant will break consistencies and
is not able to revert to replicant anymore, unless the were destroyed and resynced
with the new master.
To run sample replication, do the following instructions:
@ -224,7 +233,7 @@ make slave-log
You can try experiment with several scenarios to see how replication works
### Sync changes from master to slave
### Sync changes from master to replicant
You can use any postgres database tools to create new tables in master, by
connecting using POSTGRES_USER and POSTGRES_PASS credentials using exposed port.
@ -237,9 +246,9 @@ make master-shell
Then made any database changes using psql.
After that, you can see that slave follows the changes by inspecting
After that, you can see that replicant follows the changes by inspecting
slave database. You can, again, uses database management tools using connection
credentials, hostname, and ports for slave. Or you can do it via command line,
credentials, hostname, and ports for replicant. Or you can do it via command line,
by entering the shell:
```
@ -248,22 +257,22 @@ make slave-shell
Then view your changes using psql.
### Promoting slave to master
### Promoting replicant to master
You will notice that you cannot make changes in slave, because it was read-only.
You will notice that you cannot make changes in replicant, because it was read-only.
If somehow you want to promote it to master, you can specify `PROMOTE_MASTER: 'True'`
into slave environment and set `DESTROY_DATABASE_ON_RESTART: 'False'`.
After this, you can make changes to your slave, but master and slave will not
be in sync anymore. This is useful if slave needs to take over a failover master.
After this, you can make changes to your replicant, but master and replicant will not
be in sync anymore. This is useful if replicant needs to take over a failover master.
However it was recommended to take additional action, such as creating backup from
slave, so a dedicated master can be created again.
### Preventing slave database destroy on restart
### Preventing replicant database destroy on restart
You can optionally set `DESTROY_DATABASE_ON_RESTART: 'False'` after successful sync
to prevent the database from destroyed on restart. With this settings, you can
shutdown your slave and restart it later and it will continue to sync using existing
shutdown your replicant and restart it later and it will continue to sync using existing
database (as long as there is no consistencies conflicts).
However, you should note that this option doesn't mean anything if you didn't