|
1 | | -# Postgres Multimaster |
| 1 | +# `mmts` |
| 2 | + |
| 3 | +An implementation of synchronous multi-master replication based on **logical decoding** and **xtm**. |
| 4 | + |
| 5 | +## Usage |
| 6 | + |
| 7 | +1. Install `contrib/raftable` and `contrib/mmts` on each instance. |
| 8 | +1. Add these required options to the `postgresql.conf` of each instance in the cluster. |
| 9 | + ```sh |
| 10 | + max_prepared_transactions = 200 # should be > 0, because all |
| 11 | + # transactions are implicitly two-phase |
| 12 | + max_connections = 200 |
| 13 | + max_worker_processes = 100 # at least (2 * n + p + 1) |
| 14 | + # this figure is calculated as: |
| 15 | + # 1 raftable worker |
| 16 | + # n-1 receiver |
| 17 | + # n-1 sender |
| 18 | + # 1 mtm-sender |
| 19 | + # 1 mtm-receiver |
| 20 | + # p workers in the pool |
| 21 | + max_parallel_degree = 0 |
| 22 | + wal_level = logical # multimaster is build on top of |
| 23 | + # logical replication and will not work otherwise |
| 24 | + max_wal_senders = 10 # at least the number of nodes |
| 25 | + wal_sender_timeout = 0 |
| 26 | + default_transaction_isolation = 'repeatable read' |
| 27 | + max_replication_slots = 10 # at least the number of nodes |
| 28 | + shared_preload_libraries = 'raftable,multimaster' |
| 29 | + multimaster.workers = 10 |
| 30 | + multimaster.queue_size = 10485760 # 10mb |
| 31 | + multimaster.node_id = 1 # the 1-based index of the node in the cluster |
| 32 | + multimaster.conn_strings = 'dbname=... host=....0.0.1 port=... raftport=..., ...' |
| 33 | + # comma-separated list of connection strings |
| 34 | + multimaster.use_raftable = true |
| 35 | + multimaster.heartbeat_recv_timeout = 1000 |
| 36 | + multimaster.heartbeat_send_timeout = 250 |
| 37 | + multimaster.ignore_tables_without_pk = true |
| 38 | + multimaster.twopc_min_timeout = 2000 |
| 39 | + ``` |
| 40 | +1. Allow replication in `pg_hba.conf`. |
| 41 | + |
| 42 | +## Status functions |
| 43 | + |
| 44 | +`create extension mmts;` to gain access to these functions: |
| 45 | + |
| 46 | +* `mtm.get_nodes_state()` -- show status of nodes on cluster |
| 47 | +* `mtm.get_cluster_state()` -- show whole cluster status |
| 48 | +* `mtm.get_cluster_info()` -- print some debug info |
| 49 | +* `mtm.make_table_local(relation regclass)` -- stop replication for a given table |
2 | 50 |
|
3 | 51 | ## Testing |
4 | 52 |
|
5 | | -The testing process involves multiple modules that perform different tasks. The |
6 | | -modules and their APIs are listed below. |
7 | | - |
8 | | -### Modules |
9 | | - |
10 | | -#### `combineaux` |
11 | | - |
12 | | -Governs the whole testing process. Runs different workloads during different |
13 | | -troubles. |
14 | | - |
15 | | -#### `stresseaux` |
16 | | - |
17 | | -Puts workloads against the database. Writes logs that are later used by |
18 | | -`valideaux`. |
19 | | - |
20 | | -* `start(id, workload, cluster)` - starts a `workload` against the `cluster` |
21 | | -and call it `id`. |
22 | | -* `stop(id)` - stops a previously started workload called `id`. |
23 | | - |
24 | | -#### `starteaux` |
25 | | - |
26 | | -Manages the database nodes. |
27 | | - |
28 | | -* `deploy(driver, ...)` - deploys a cluster using the specified `driver` and |
29 | | -other parameters specific to that driver. Returns a `cluster` instance that is |
30 | | -used in other methods. |
31 | | -* `cluster->up(id)` - adds a node named `id` to the `cluster`. |
32 | | -* `cluster->down(id)` - removes a node named `id` from the `cluster`. |
33 | | -* `cluster->drop(src, dst, ratio)` - drop `ratio` packets flowing from node |
34 | | -`src` to node `dst`. |
35 | | -* `cluster->delay(src, dst, msec)` - delay packets flowing from node `src` to |
36 | | -node `dst` by `msec` milliseconds. |
37 | | - |
38 | | -#### `troubleaux` |
39 | | - |
40 | | -This is the troublemaker that messes with the network, nodes and time. |
41 | | - |
42 | | -* `cause(cluster, trouble, ...)` - causes the specified `trouble` in the |
43 | | -specified `cluster` with some trouble-specific parameters. |
44 | | -* `fix(cluster)` - fixes all troubles caused in the `cluster`. |
45 | | - |
46 | | -#### `valideaux` |
47 | | - |
48 | | -Validates the logs of stresseaux. |
49 | | - |
50 | | -#### `reporteaux` |
51 | | - |
52 | | -Generates reports on the test results. This is usually a table that with |
53 | | -`trouble` vs `workload` axes. |
| 53 | +* `make -C contrib/mmts check` to run TAP-tests. |
| 54 | +* `make -C contrib/mmts xcheck` to run blockade tests. The blockade tests require `docker`, `blockade`, and some other packages installed, see [requirements.txt](tests2/requirements.txt) for the list. |
0 commit comments