Add missing section on multi-node consistency model (github#597)

* Add missing section on multi-node consistency model The old docs had a section that briefly described the consistency model of multi-node, including how transactions work with 2PC. Add the missing section to the "about multi-node" section. * Update timescaledb/how-to-guides/multinode-timescaledb/about-multinode.md Co-authored-by: Lana Brindley <[email protected]> * Update timescaledb/how-to-guides/multinode-timescaledb/about-multinode.md Co-authored-by: Lana Brindley <[email protected]> * Update timescaledb/how-to-guides/multinode-timescaledb/about-multinode.md Co-authored-by: Lana Brindley <[email protected]> * Update timescaledb/how-to-guides/multinode-timescaledb/about-multinode.md Co-authored-by: Lana Brindley <[email protected]> Co-authored-by: Nuno Santos <[email protected]> Co-authored-by: Lana Brindley <[email protected]>
jnidzwetzki · Nov 23, 2021 · 3548b4b · 3548b4b
1 parent 6a0c3c2
commit 3548b4b
Showing 1 changed file with 27 additions and 0 deletions.
diff --git a/timescaledb/how-to-guides/multinode-timescaledb/about-multinode.md b/timescaledb/how-to-guides/multinode-timescaledb/about-multinode.md
@@ -89,7 +89,34 @@ ORDER BY hour
 LIMIT 100;
 ```
 
+### Transactions and consistency model
+Transactions that occur on distributed hypertables are atomic, just
+like those on regular hypertables. This means that a distributed 
+transaction that involves multiple data nodes is guaranteed to 
+either succeed on all nodes or on none of them. This guarantee
+is provided by the [two-phase commit protocol][2pc], which
+is used to implement distributed transactions in TimescaleDB.
+
+However, the read consistency of a distributed hypertable is different
+to a regular hypertable. Because a distributed transaction is a set of 
+individual transactions across multiple nodes, each node can commit 
+its local transaction at a slightly different time due to network 
+transmission delays or other small fluctuations. As a consequence, the
+access node cannot guarantee a fully consistent snapshot of the
+data across all data nodes. For example, a distributed read
+transaction might start when another concurrent write transaction is
+in its commit phase and has committed on some data nodes but not
+others. The read transaction can therefore use a snapshot on one node
+that includes the other transaction's modifications, while the
+snapshot on another data node might not include them.
+
+If you need stronger read consistency in a distributed transaction, then you
+can use consistent snapshots across all data nodes. However, this
+requires a lot of coordination and management, which can negatively effect
+performance, and it is therefore not implemented by default for distributed 
+hypertables.
 
 [hypertables]: /how-to-guides/hypertables/
 [multinode-cloud]: /cloud/:currentVersion:/cloud-multi-node/
 [multinode-mst]: /mst/:currentVersion:/mst-multi-node/
+[2pc]: https://www.postgresql.org/docs/current/sql-prepare-transaction.html