From b9912bb729795fc0a74095144a8b219ff907ad8f Mon Sep 17 00:00:00 2001 From: reeb Date: Sun, 24 May 2026 14:40:44 +0300 Subject: [PATCH 1/2] RDoc-2211: Explain why clusters and database groups need an odd number of nodes --- .../content/_create-database-csharp.mdx | 22 +++++++++++++++++++ .../content/_create-database-java.mdx | 22 +++++++++++++++++++ ...luster-best-practice-and-configuration.mdx | 20 +++++++++++++++++ .../distribution/distributed-database.mdx | 19 ++++++++++++++++ .../replication/replication-overview.mdx | 20 +++++++++++++++++ .../create-new-database/general-flow.mdx | 21 ++++++++++++++++++ .../content/_create-database-csharp.mdx | 22 +++++++++++++++++++ .../content/_create-database-java.mdx | 22 +++++++++++++++++++ ...luster-best-practice-and-configuration.mdx | 20 +++++++++++++++++ .../distribution/distributed-database.mdx | 19 ++++++++++++++++ .../replication/replication-overview.mdx | 20 +++++++++++++++++ .../create-new-database/general-flow.mdx | 21 ++++++++++++++++++ .../content/_create-database-csharp.mdx | 22 +++++++++++++++++++ .../content/_create-database-java.mdx | 22 +++++++++++++++++++ ...luster-best-practice-and-configuration.mdx | 20 +++++++++++++++++ .../distribution/distributed-database.mdx | 19 ++++++++++++++++ .../replication/replication-overview.mdx | 20 +++++++++++++++++ .../create-new-database/general-flow.mdx | 21 ++++++++++++++++++ .../content/_create-database-csharp.mdx | 22 +++++++++++++++++++ .../content/_create-database-java.mdx | 22 +++++++++++++++++++ ...luster-best-practice-and-configuration.mdx | 20 +++++++++++++++++ .../distribution/distributed-database.mdx | 19 ++++++++++++++++ .../replication/replication-overview.mdx | 20 +++++++++++++++++ .../create-new-database/general-flow.mdx | 21 ++++++++++++++++++ 24 files changed, 496 insertions(+) diff --git a/docs/client-api/operations/server-wide/content/_create-database-csharp.mdx b/docs/client-api/operations/server-wide/content/_create-database-csharp.mdx index 114d97252d..3e67b4a1c4 100644 --- a/docs/client-api/operations/server-wide/content/_create-database-csharp.mdx +++ b/docs/client-api/operations/server-wide/content/_create-database-csharp.mdx @@ -19,6 +19,28 @@ import CodeBlock from '@theme/CodeBlock'; * [Syntax](../../../../client-api/operations/server-wide/create-database.mdx#syntax) + + + +**Sizing the database group** + +The default replication factor is 1, which puts the database on a single node. +For high availability, set the replication factor to at least 3 so the database +survives losing a node and stays synchronized through +[internal replication](../../../../server/clustering/replication/replication-overview.mdx#internal-replication). + +If the database also uses +[cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), +prefer an odd replication factor (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it, and an odd group size means that majority +is always a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + ## Create new database diff --git a/docs/client-api/operations/server-wide/content/_create-database-java.mdx b/docs/client-api/operations/server-wide/content/_create-database-java.mdx index bf8bfe26ae..90a003c825 100644 --- a/docs/client-api/operations/server-wide/content/_create-database-java.mdx +++ b/docs/client-api/operations/server-wide/content/_create-database-java.mdx @@ -18,6 +18,28 @@ import CodeBlock from '@theme/CodeBlock'; * [Syntax](../../../../client-api/operations/server-wide/create-database.mdx#syntax) + + + +**Sizing the database group** + +The default replication factor is 1, which puts the database on a single node. +For high availability, set the replication factor to at least 3 so the database +survives losing a node and stays synchronized through +[internal replication](../../../../server/clustering/replication/replication-overview.mdx#internal-replication). + +If the database also uses +[cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), +prefer an odd replication factor (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it, and an odd group size means that majority +is always a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + ## Create new database diff --git a/docs/server/clustering/cluster-best-practice-and-configuration.mdx b/docs/server/clustering/cluster-best-practice-and-configuration.mdx index 5a827bfd0b..30b375abfa 100644 --- a/docs/server/clustering/cluster-best-practice-and-configuration.mdx +++ b/docs/server/clustering/cluster-best-practice-and-configuration.mdx @@ -17,6 +17,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; * In this page: * [Clusters should have an odd number of at least 3 nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes) + * [Database groups follow the same rule when you use cluster-wide transactions](../../server/clustering/cluster-best-practice-and-configuration.mdx#database-groups-follow-the-same-rule-when-you-use-cluster-wide-transactions) * [Avoid different cluster configurations among the cluster's nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#avoid-different-cluster-configurations-among-the-clusters-nodes) @@ -42,6 +43,25 @@ so having an odd number of nodes makes achieving the majority easier. +### Database groups follow the same rule when you use cluster-wide transactions + +The recommendation above is about the cluster itself - the nodes that vote on +Raft commands. The same odd-numbered sizing matters for an individual +**database group** when the database uses +[cluster-wide transactions](../../server/clustering/cluster-transactions.mdx) +(or the [atomic guards](../../compare-exchange/atomic-guards.mdx) that wrap them). + +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it. With three members, two must accept; with +five, three must accept; with seven, four. An odd size keeps that count well- +defined and keeps a single node failure inside the majority. + +If the database does not use cluster-wide transactions, you do not have to +keep the group size odd. The database is kept in sync by +[internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication), +which keeps writes flowing on any node that is up - so a group of two members +already lets the database survive losing a node. + ### Avoid different cluster configurations among the cluster's nodes diff --git a/docs/server/clustering/distribution/distributed-database.mdx b/docs/server/clustering/distribution/distributed-database.mdx index 78c50fdae6..44e14fa925 100644 --- a/docs/server/clustering/distribution/distributed-database.mdx +++ b/docs/server/clustering/distribution/distributed-database.mdx @@ -55,7 +55,26 @@ In either case, the number of nodes will represent the `Replication Factor`. Once the database is created by getting a [Consensus](../../../server/clustering/rachis/consensus-operations.mdx), the [Cluster Observer](../../../server/clustering/distribution/cluster-observer.mdx) begins monitoring the _Database Group_ in order to maintain this Replication Factor. + + +**Sizing the database group** + +For high availability, use a database group of at least three nodes so the +database survives losing a node, and rely on +[internal replication](../replication/replication-overview.mdx#internal-replication) +to keep the remaining nodes in sync. +If the database also uses +[cluster-wide transactions](../cluster-transactions.mdx), +prefer an odd group size (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database group's +voting members accept it, and an odd group size means that majority is always +a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + ## Database Topology diff --git a/docs/server/clustering/replication/replication-overview.mdx b/docs/server/clustering/replication/replication-overview.mdx index f793e7d532..6de5a56de9 100644 --- a/docs/server/clustering/replication/replication-overview.mdx +++ b/docs/server/clustering/replication/replication-overview.mdx @@ -51,6 +51,26 @@ import LanguageContent from "@site/src/components/LanguageContent"; * You can _write_ to any node in the database group, that _write_ will be recorded and automatically replicated to all other nodes in the database-group. + + + +**Sizing the database group** + +For high availability through internal replication, use a database group of at +least three nodes so the database survives losing a node. + +If the database also uses +[cluster-wide transactions](../cluster-transactions.mdx), +prefer an odd group size (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it, and an odd group size means that majority +is always a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + #### External replication * __Replicate between__: Two databases that are typically set on different clusters. diff --git a/docs/studio/database/create-new-database/general-flow.mdx b/docs/studio/database/create-new-database/general-flow.mdx index e6c192c106..7e26dd7918 100644 --- a/docs/studio/database/create-new-database/general-flow.mdx +++ b/docs/studio/database/create-new-database/general-flow.mdx @@ -77,6 +77,27 @@ From the database list view, click the **'New database'** button. If no node is checked, then the replication nodes will be selected randomly from the cluster. + + +**Sizing the database group** + +When choosing a **Replication Factor**, use at least three nodes for high +availability - that way the database survives losing a node and stays +synchronized through +[internal replication](../../../server/clustering/replication/replication-overview.mdx#internal-replication). + +If the database also uses +[cluster-wide transactions](../../../server/clustering/cluster-transactions.mdx), +prefer an odd group size (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database group's +voting members accept it, and an odd group size means that majority is always +a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + ## 4. Configure Path diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-csharp.mdx index f0e2f7cad2..f0c5b2bf8f 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-csharp.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-csharp.mdx @@ -19,6 +19,28 @@ import CodeBlock from '@theme/CodeBlock'; * [Syntax](../../../../client-api/operations/server-wide/create-database.mdx#syntax) + + + +**Sizing the database group** + +The default replication factor is 1, which puts the database on a single node. +For high availability, set the replication factor to at least 3 so the database +survives losing a node and stays synchronized through +[internal replication](../../../../server/clustering/replication/replication-overview.mdx#internal-replication). + +If the database also uses +[cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), +prefer an odd replication factor (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it, and an odd group size means that majority +is always a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + ## Create new database diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-java.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-java.mdx index cfb2afb138..90dddb3dcc 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-java.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-java.mdx @@ -18,6 +18,28 @@ import CodeBlock from '@theme/CodeBlock'; * [Syntax](../../../../client-api/operations/server-wide/create-database.mdx#syntax) + + + +**Sizing the database group** + +The default replication factor is 1, which puts the database on a single node. +For high availability, set the replication factor to at least 3 so the database +survives losing a node and stays synchronized through +[internal replication](../../../../server/clustering/replication/replication-overview.mdx#internal-replication). + +If the database also uses +[cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), +prefer an odd replication factor (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it, and an odd group size means that majority +is always a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + ## Create new database diff --git a/versioned_docs/version-6.2/server/clustering/cluster-best-practice-and-configuration.mdx b/versioned_docs/version-6.2/server/clustering/cluster-best-practice-and-configuration.mdx index dac986e47b..14b217ab91 100644 --- a/versioned_docs/version-6.2/server/clustering/cluster-best-practice-and-configuration.mdx +++ b/versioned_docs/version-6.2/server/clustering/cluster-best-practice-and-configuration.mdx @@ -16,6 +16,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; * In this page: * [Clusters should have an odd number of at least 3 nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes) + * [Database groups follow the same rule when you use cluster-wide transactions](../../server/clustering/cluster-best-practice-and-configuration.mdx#database-groups-follow-the-same-rule-when-you-use-cluster-wide-transactions) * [Avoid different cluster configurations among the cluster's nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#avoid-different-cluster-configurations-among-the-clusters-nodes) @@ -41,6 +42,25 @@ so having an odd number of nodes makes achieving the majority easier. +### Database groups follow the same rule when you use cluster-wide transactions + +The recommendation above is about the cluster itself - the nodes that vote on +Raft commands. The same odd-numbered sizing matters for an individual +**database group** when the database uses +[cluster-wide transactions](../../server/clustering/cluster-transactions.mdx) +(or the [atomic guards](../../client-api/session/cluster-transaction/atomic-guards.mdx) that wrap them). + +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it. With three members, two must accept; with +five, three must accept; with seven, four. An odd size keeps that count well- +defined and keeps a single node failure inside the majority. + +If the database does not use cluster-wide transactions, you do not have to +keep the group size odd. The database is kept in sync by +[internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication), +which keeps writes flowing on any node that is up - so a group of two members +already lets the database survive losing a node. + ### Avoid different cluster configurations among the cluster's nodes diff --git a/versioned_docs/version-6.2/server/clustering/distribution/distributed-database.mdx b/versioned_docs/version-6.2/server/clustering/distribution/distributed-database.mdx index 903275f53f..3bfd84433e 100644 --- a/versioned_docs/version-6.2/server/clustering/distribution/distributed-database.mdx +++ b/versioned_docs/version-6.2/server/clustering/distribution/distributed-database.mdx @@ -54,7 +54,26 @@ In either case, the number of nodes will represent the `Replication Factor`. Once the database is created by getting a [Consensus](../../../server/clustering/rachis/consensus-operations.mdx), the [Cluster Observer](../../../server/clustering/distribution/cluster-observer.mdx) begins monitoring the _Database Group_ in order to maintain this Replication Factor. + + +**Sizing the database group** + +For high availability, use a database group of at least three nodes so the +database survives losing a node, and rely on +[internal replication](../replication/replication-overview.mdx#internal-replication) +to keep the remaining nodes in sync. +If the database also uses +[cluster-wide transactions](../cluster-transactions.mdx), +prefer an odd group size (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database group's +voting members accept it, and an odd group size means that majority is always +a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + ## Database Topology diff --git a/versioned_docs/version-6.2/server/clustering/replication/replication-overview.mdx b/versioned_docs/version-6.2/server/clustering/replication/replication-overview.mdx index 9e689cc32a..4c09e81d4b 100644 --- a/versioned_docs/version-6.2/server/clustering/replication/replication-overview.mdx +++ b/versioned_docs/version-6.2/server/clustering/replication/replication-overview.mdx @@ -50,6 +50,26 @@ import LanguageContent from "@site/src/components/LanguageContent"; * You can _write_ to any node in the database group, that _write_ will be recorded and automatically replicated to all other nodes in the database-group. + + + +**Sizing the database group** + +For high availability through internal replication, use a database group of at +least three nodes so the database survives losing a node. + +If the database also uses +[cluster-wide transactions](../cluster-transactions.mdx), +prefer an odd group size (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it, and an odd group size means that majority +is always a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + #### External replication * __Replicate between__: Two databases that are typically set on different clusters. diff --git a/versioned_docs/version-6.2/studio/database/create-new-database/general-flow.mdx b/versioned_docs/version-6.2/studio/database/create-new-database/general-flow.mdx index 6337c6be88..84c34aa79b 100644 --- a/versioned_docs/version-6.2/studio/database/create-new-database/general-flow.mdx +++ b/versioned_docs/version-6.2/studio/database/create-new-database/general-flow.mdx @@ -76,6 +76,27 @@ From the database list view, click the **'New database'** button. If no node is checked, then the replication nodes will be selected randomly from the cluster. + + +**Sizing the database group** + +When choosing a **Replication Factor**, use at least three nodes for high +availability - that way the database survives losing a node and stays +synchronized through +[internal replication](../../../server/clustering/replication/replication-overview.mdx#internal-replication). + +If the database also uses +[cluster-wide transactions](../../../server/clustering/cluster-transactions.mdx), +prefer an odd group size (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database group's +voting members accept it, and an odd group size means that majority is always +a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + ## 4. Configure Path diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-csharp.mdx index 6470f5997b..987c7f4ad7 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-csharp.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-csharp.mdx @@ -19,6 +19,28 @@ import CodeBlock from '@theme/CodeBlock'; * [Syntax](../../../../client-api/operations/server-wide/create-database.mdx#syntax) + + + +**Sizing the database group** + +The default replication factor is 1, which puts the database on a single node. +For high availability, set the replication factor to at least 3 so the database +survives losing a node and stays synchronized through +[internal replication](../../../../server/clustering/replication/replication-overview.mdx#internal-replication). + +If the database also uses +[cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), +prefer an odd replication factor (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it, and an odd group size means that majority +is always a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + ## Create new database diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-java.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-java.mdx index cfb2afb138..90dddb3dcc 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-java.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-java.mdx @@ -18,6 +18,28 @@ import CodeBlock from '@theme/CodeBlock'; * [Syntax](../../../../client-api/operations/server-wide/create-database.mdx#syntax) + + + +**Sizing the database group** + +The default replication factor is 1, which puts the database on a single node. +For high availability, set the replication factor to at least 3 so the database +survives losing a node and stays synchronized through +[internal replication](../../../../server/clustering/replication/replication-overview.mdx#internal-replication). + +If the database also uses +[cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), +prefer an odd replication factor (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it, and an odd group size means that majority +is always a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + ## Create new database diff --git a/versioned_docs/version-7.0/server/clustering/cluster-best-practice-and-configuration.mdx b/versioned_docs/version-7.0/server/clustering/cluster-best-practice-and-configuration.mdx index dac986e47b..14b217ab91 100644 --- a/versioned_docs/version-7.0/server/clustering/cluster-best-practice-and-configuration.mdx +++ b/versioned_docs/version-7.0/server/clustering/cluster-best-practice-and-configuration.mdx @@ -16,6 +16,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; * In this page: * [Clusters should have an odd number of at least 3 nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes) + * [Database groups follow the same rule when you use cluster-wide transactions](../../server/clustering/cluster-best-practice-and-configuration.mdx#database-groups-follow-the-same-rule-when-you-use-cluster-wide-transactions) * [Avoid different cluster configurations among the cluster's nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#avoid-different-cluster-configurations-among-the-clusters-nodes) @@ -41,6 +42,25 @@ so having an odd number of nodes makes achieving the majority easier. +### Database groups follow the same rule when you use cluster-wide transactions + +The recommendation above is about the cluster itself - the nodes that vote on +Raft commands. The same odd-numbered sizing matters for an individual +**database group** when the database uses +[cluster-wide transactions](../../server/clustering/cluster-transactions.mdx) +(or the [atomic guards](../../client-api/session/cluster-transaction/atomic-guards.mdx) that wrap them). + +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it. With three members, two must accept; with +five, three must accept; with seven, four. An odd size keeps that count well- +defined and keeps a single node failure inside the majority. + +If the database does not use cluster-wide transactions, you do not have to +keep the group size odd. The database is kept in sync by +[internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication), +which keeps writes flowing on any node that is up - so a group of two members +already lets the database survive losing a node. + ### Avoid different cluster configurations among the cluster's nodes diff --git a/versioned_docs/version-7.0/server/clustering/distribution/distributed-database.mdx b/versioned_docs/version-7.0/server/clustering/distribution/distributed-database.mdx index 903275f53f..3bfd84433e 100644 --- a/versioned_docs/version-7.0/server/clustering/distribution/distributed-database.mdx +++ b/versioned_docs/version-7.0/server/clustering/distribution/distributed-database.mdx @@ -54,7 +54,26 @@ In either case, the number of nodes will represent the `Replication Factor`. Once the database is created by getting a [Consensus](../../../server/clustering/rachis/consensus-operations.mdx), the [Cluster Observer](../../../server/clustering/distribution/cluster-observer.mdx) begins monitoring the _Database Group_ in order to maintain this Replication Factor. + + +**Sizing the database group** + +For high availability, use a database group of at least three nodes so the +database survives losing a node, and rely on +[internal replication](../replication/replication-overview.mdx#internal-replication) +to keep the remaining nodes in sync. +If the database also uses +[cluster-wide transactions](../cluster-transactions.mdx), +prefer an odd group size (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database group's +voting members accept it, and an odd group size means that majority is always +a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + ## Database Topology diff --git a/versioned_docs/version-7.0/server/clustering/replication/replication-overview.mdx b/versioned_docs/version-7.0/server/clustering/replication/replication-overview.mdx index 9e689cc32a..4c09e81d4b 100644 --- a/versioned_docs/version-7.0/server/clustering/replication/replication-overview.mdx +++ b/versioned_docs/version-7.0/server/clustering/replication/replication-overview.mdx @@ -50,6 +50,26 @@ import LanguageContent from "@site/src/components/LanguageContent"; * You can _write_ to any node in the database group, that _write_ will be recorded and automatically replicated to all other nodes in the database-group. + + + +**Sizing the database group** + +For high availability through internal replication, use a database group of at +least three nodes so the database survives losing a node. + +If the database also uses +[cluster-wide transactions](../cluster-transactions.mdx), +prefer an odd group size (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it, and an odd group size means that majority +is always a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + #### External replication * __Replicate between__: Two databases that are typically set on different clusters. diff --git a/versioned_docs/version-7.0/studio/database/create-new-database/general-flow.mdx b/versioned_docs/version-7.0/studio/database/create-new-database/general-flow.mdx index 6337c6be88..84c34aa79b 100644 --- a/versioned_docs/version-7.0/studio/database/create-new-database/general-flow.mdx +++ b/versioned_docs/version-7.0/studio/database/create-new-database/general-flow.mdx @@ -76,6 +76,27 @@ From the database list view, click the **'New database'** button. If no node is checked, then the replication nodes will be selected randomly from the cluster. + + +**Sizing the database group** + +When choosing a **Replication Factor**, use at least three nodes for high +availability - that way the database survives losing a node and stays +synchronized through +[internal replication](../../../server/clustering/replication/replication-overview.mdx#internal-replication). + +If the database also uses +[cluster-wide transactions](../../../server/clustering/cluster-transactions.mdx), +prefer an odd group size (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database group's +voting members accept it, and an odd group size means that majority is always +a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + ## 4. Configure Path diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-csharp.mdx index f8fda7c46f..b14c0bdfb5 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-csharp.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-csharp.mdx @@ -19,6 +19,28 @@ import CodeBlock from '@theme/CodeBlock'; * [Syntax](../../../../client-api/operations/server-wide/create-database.mdx#syntax) + + + +**Sizing the database group** + +The default replication factor is 1, which puts the database on a single node. +For high availability, set the replication factor to at least 3 so the database +survives losing a node and stays synchronized through +[internal replication](../../../../server/clustering/replication/replication-overview.mdx#internal-replication). + +If the database also uses +[cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), +prefer an odd replication factor (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it, and an odd group size means that majority +is always a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + ## Create new database diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-java.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-java.mdx index cfb2afb138..90dddb3dcc 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-java.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-java.mdx @@ -18,6 +18,28 @@ import CodeBlock from '@theme/CodeBlock'; * [Syntax](../../../../client-api/operations/server-wide/create-database.mdx#syntax) + + + +**Sizing the database group** + +The default replication factor is 1, which puts the database on a single node. +For high availability, set the replication factor to at least 3 so the database +survives losing a node and stays synchronized through +[internal replication](../../../../server/clustering/replication/replication-overview.mdx#internal-replication). + +If the database also uses +[cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), +prefer an odd replication factor (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it, and an odd group size means that majority +is always a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + ## Create new database diff --git a/versioned_docs/version-7.1/server/clustering/cluster-best-practice-and-configuration.mdx b/versioned_docs/version-7.1/server/clustering/cluster-best-practice-and-configuration.mdx index dac986e47b..f5ec3c7151 100644 --- a/versioned_docs/version-7.1/server/clustering/cluster-best-practice-and-configuration.mdx +++ b/versioned_docs/version-7.1/server/clustering/cluster-best-practice-and-configuration.mdx @@ -16,6 +16,7 @@ import LanguageContent from "@site/src/components/LanguageContent"; * In this page: * [Clusters should have an odd number of at least 3 nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes) + * [Database groups follow the same rule when you use cluster-wide transactions](../../server/clustering/cluster-best-practice-and-configuration.mdx#database-groups-follow-the-same-rule-when-you-use-cluster-wide-transactions) * [Avoid different cluster configurations among the cluster's nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#avoid-different-cluster-configurations-among-the-clusters-nodes) @@ -41,6 +42,25 @@ so having an odd number of nodes makes achieving the majority easier. +### Database groups follow the same rule when you use cluster-wide transactions + +The recommendation above is about the cluster itself - the nodes that vote on +Raft commands. The same odd-numbered sizing matters for an individual +**database group** when the database uses +[cluster-wide transactions](../../server/clustering/cluster-transactions.mdx) +(or the [atomic guards](../../compare-exchange/atomic-guards.mdx) that wrap them). + +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it. With three members, two must accept; with +five, three must accept; with seven, four. An odd size keeps that count well- +defined and keeps a single node failure inside the majority. + +If the database does not use cluster-wide transactions, you do not have to +keep the group size odd. The database is kept in sync by +[internal replication](../../server/clustering/replication/replication-overview.mdx#internal-replication), +which keeps writes flowing on any node that is up - so a group of two members +already lets the database survive losing a node. + ### Avoid different cluster configurations among the cluster's nodes diff --git a/versioned_docs/version-7.1/server/clustering/distribution/distributed-database.mdx b/versioned_docs/version-7.1/server/clustering/distribution/distributed-database.mdx index 903275f53f..3bfd84433e 100644 --- a/versioned_docs/version-7.1/server/clustering/distribution/distributed-database.mdx +++ b/versioned_docs/version-7.1/server/clustering/distribution/distributed-database.mdx @@ -54,7 +54,26 @@ In either case, the number of nodes will represent the `Replication Factor`. Once the database is created by getting a [Consensus](../../../server/clustering/rachis/consensus-operations.mdx), the [Cluster Observer](../../../server/clustering/distribution/cluster-observer.mdx) begins monitoring the _Database Group_ in order to maintain this Replication Factor. + + +**Sizing the database group** + +For high availability, use a database group of at least three nodes so the +database survives losing a node, and rely on +[internal replication](../replication/replication-overview.mdx#internal-replication) +to keep the remaining nodes in sync. +If the database also uses +[cluster-wide transactions](../cluster-transactions.mdx), +prefer an odd group size (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database group's +voting members accept it, and an odd group size means that majority is always +a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + ## Database Topology diff --git a/versioned_docs/version-7.1/server/clustering/replication/replication-overview.mdx b/versioned_docs/version-7.1/server/clustering/replication/replication-overview.mdx index 9e689cc32a..4c09e81d4b 100644 --- a/versioned_docs/version-7.1/server/clustering/replication/replication-overview.mdx +++ b/versioned_docs/version-7.1/server/clustering/replication/replication-overview.mdx @@ -50,6 +50,26 @@ import LanguageContent from "@site/src/components/LanguageContent"; * You can _write_ to any node in the database group, that _write_ will be recorded and automatically replicated to all other nodes in the database-group. + + + +**Sizing the database group** + +For high availability through internal replication, use a database group of at +least three nodes so the database survives losing a node. + +If the database also uses +[cluster-wide transactions](../cluster-transactions.mdx), +prefer an odd group size (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database +group's voting members accept it, and an odd group size means that majority +is always a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + #### External replication * __Replicate between__: Two databases that are typically set on different clusters. diff --git a/versioned_docs/version-7.1/studio/database/create-new-database/general-flow.mdx b/versioned_docs/version-7.1/studio/database/create-new-database/general-flow.mdx index 6337c6be88..84c34aa79b 100644 --- a/versioned_docs/version-7.1/studio/database/create-new-database/general-flow.mdx +++ b/versioned_docs/version-7.1/studio/database/create-new-database/general-flow.mdx @@ -76,6 +76,27 @@ From the database list view, click the **'New database'** button. If no node is checked, then the replication nodes will be selected randomly from the cluster. + + +**Sizing the database group** + +When choosing a **Replication Factor**, use at least three nodes for high +availability - that way the database survives losing a node and stays +synchronized through +[internal replication](../../../server/clustering/replication/replication-overview.mdx#internal-replication). + +If the database also uses +[cluster-wide transactions](../../../server/clustering/cluster-transactions.mdx), +prefer an odd group size (3, 5, or 7). +A cluster-wide transaction commits only after a majority of the database group's +voting members accept it, and an odd group size means that majority is always +a clean (n/2 + 1) - never a tie. + +For the full reasoning, see +[Cluster: Best Practices](../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes). + + + ## 4. Configure Path From 3c7e05c29eaa30b4d824cf17453ca3724bd01108 Mon Sep 17 00:00:00 2001 From: reeb Date: Sun, 24 May 2026 15:03:22 +0300 Subject: [PATCH 2/2] RDoc-2211 - finalization --- .../content/_create-database-csharp.mdx | 2 +- .../content/_create-database-java.mdx | 2 +- ...luster-best-practice-and-configuration.mdx | 31 +++++++++++++++---- .../distribution/distributed-database.mdx | 2 +- .../replication/replication-overview.mdx | 2 +- .../create-new-database/general-flow.mdx | 2 +- .../content/_create-database-csharp.mdx | 2 +- .../content/_create-database-java.mdx | 2 +- ...luster-best-practice-and-configuration.mdx | 31 +++++++++++++++---- .../distribution/distributed-database.mdx | 2 +- .../replication/replication-overview.mdx | 2 +- .../create-new-database/general-flow.mdx | 2 +- .../content/_create-database-csharp.mdx | 2 +- .../content/_create-database-java.mdx | 2 +- ...luster-best-practice-and-configuration.mdx | 31 +++++++++++++++---- .../distribution/distributed-database.mdx | 2 +- .../replication/replication-overview.mdx | 2 +- .../create-new-database/general-flow.mdx | 2 +- .../content/_create-database-csharp.mdx | 2 +- .../content/_create-database-java.mdx | 2 +- ...luster-best-practice-and-configuration.mdx | 31 +++++++++++++++---- .../distribution/distributed-database.mdx | 2 +- .../replication/replication-overview.mdx | 2 +- .../create-new-database/general-flow.mdx | 2 +- 24 files changed, 120 insertions(+), 44 deletions(-) diff --git a/docs/client-api/operations/server-wide/content/_create-database-csharp.mdx b/docs/client-api/operations/server-wide/content/_create-database-csharp.mdx index 3e67b4a1c4..dbe774fa11 100644 --- a/docs/client-api/operations/server-wide/content/_create-database-csharp.mdx +++ b/docs/client-api/operations/server-wide/content/_create-database-csharp.mdx @@ -33,7 +33,7 @@ If the database also uses [cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), prefer an odd replication factor (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it, and an odd group size means that majority +group's voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/docs/client-api/operations/server-wide/content/_create-database-java.mdx b/docs/client-api/operations/server-wide/content/_create-database-java.mdx index 90a003c825..7635dda7d6 100644 --- a/docs/client-api/operations/server-wide/content/_create-database-java.mdx +++ b/docs/client-api/operations/server-wide/content/_create-database-java.mdx @@ -32,7 +32,7 @@ If the database also uses [cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), prefer an odd replication factor (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it, and an odd group size means that majority +group's voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/docs/server/clustering/cluster-best-practice-and-configuration.mdx b/docs/server/clustering/cluster-best-practice-and-configuration.mdx index 30b375abfa..f395fa90cf 100644 --- a/docs/server/clustering/cluster-best-practice-and-configuration.mdx +++ b/docs/server/clustering/cluster-best-practice-and-configuration.mdx @@ -11,20 +11,27 @@ import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; # Cluster: Best Practices * In this page: - * [Clusters should have an odd number of at least 3 nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes) - * [Database groups follow the same rule when you use cluster-wide transactions](../../server/clustering/cluster-best-practice-and-configuration.mdx#database-groups-follow-the-same-rule-when-you-use-cluster-wide-transactions) + * [Recommended cluster and database group size](../../server/clustering/cluster-best-practice-and-configuration.mdx#recommended-cluster-and-database-group-size) + * [Clusters should have an odd number of at least 3 nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes) + * [Database groups follow the same rule when you use cluster-wide transactions](../../server/clustering/cluster-best-practice-and-configuration.mdx#database-groups-follow-the-same-rule-when-you-use-cluster-wide-transactions) * [Avoid different cluster configurations among the cluster's nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#avoid-different-cluster-configurations-among-the-clusters-nodes) + + ### Clusters should have an odd number of at least 3 nodes + + We recommend setting up clusters with an odd number of nodes equal to or greater than 3. **A single node cluster:** @@ -41,18 +48,22 @@ command will be created, although any database on the surviving node will still For ACID guarantees, a majority of the nodes must agree on every [cluster-wide transaction](../../server/clustering/cluster-transactions.mdx), so having an odd number of nodes makes achieving the majority easier. + +--- ### Database groups follow the same rule when you use cluster-wide transactions -The recommendation above is about the cluster itself - the nodes that vote on + + +The recommendation above relates to the cluster itself - the nodes that vote on Raft commands. The same odd-numbered sizing matters for an individual -**database group** when the database uses +**[database group](../../glossary/database-group.mdx)** when the database uses [cluster-wide transactions](../../server/clustering/cluster-transactions.mdx) (or the [atomic guards](../../compare-exchange/atomic-guards.mdx) that wrap them). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it. With three members, two must accept; with +group's voting members have accepted it. With three members, two must accept; with five, three must accept; with seven, four. An odd size keeps that count well- defined and keeps a single node failure inside the majority. @@ -62,13 +73,21 @@ keep the group size odd. The database is kept in sync by which keeps writes flowing on any node that is up - so a group of two members already lets the database survive losing a node. + + -### Avoid different cluster configurations among the cluster's nodes + + + Configuration mismatches tend to cause interaction problems between nodes. If you must set [cluster configurations](../../server/configuration/cluster-configuration.mdx) differently in separate nodes, **we recommend first testing it** in a development environment to see that each node interacts properly with the others. + + + + diff --git a/docs/server/clustering/distribution/distributed-database.mdx b/docs/server/clustering/distribution/distributed-database.mdx index 44e14fa925..dfd8fa94de 100644 --- a/docs/server/clustering/distribution/distributed-database.mdx +++ b/docs/server/clustering/distribution/distributed-database.mdx @@ -68,7 +68,7 @@ If the database also uses [cluster-wide transactions](../cluster-transactions.mdx), prefer an odd group size (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database group's -voting members accept it, and an odd group size means that majority is always +voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/docs/server/clustering/replication/replication-overview.mdx b/docs/server/clustering/replication/replication-overview.mdx index 6de5a56de9..bf0312816a 100644 --- a/docs/server/clustering/replication/replication-overview.mdx +++ b/docs/server/clustering/replication/replication-overview.mdx @@ -63,7 +63,7 @@ If the database also uses [cluster-wide transactions](../cluster-transactions.mdx), prefer an odd group size (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it, and an odd group size means that majority +group's voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/docs/studio/database/create-new-database/general-flow.mdx b/docs/studio/database/create-new-database/general-flow.mdx index 7e26dd7918..8fe6f6fc9c 100644 --- a/docs/studio/database/create-new-database/general-flow.mdx +++ b/docs/studio/database/create-new-database/general-flow.mdx @@ -90,7 +90,7 @@ If the database also uses [cluster-wide transactions](../../../server/clustering/cluster-transactions.mdx), prefer an odd group size (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database group's -voting members accept it, and an odd group size means that majority is always +voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-csharp.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-csharp.mdx index f0c5b2bf8f..6c5aa50e69 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-csharp.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-csharp.mdx @@ -33,7 +33,7 @@ If the database also uses [cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), prefer an odd replication factor (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it, and an odd group size means that majority +group's voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-java.mdx b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-java.mdx index 90dddb3dcc..31f5ee3245 100644 --- a/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-java.mdx +++ b/versioned_docs/version-6.2/client-api/operations/server-wide/content/_create-database-java.mdx @@ -32,7 +32,7 @@ If the database also uses [cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), prefer an odd replication factor (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it, and an odd group size means that majority +group's voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-6.2/server/clustering/cluster-best-practice-and-configuration.mdx b/versioned_docs/version-6.2/server/clustering/cluster-best-practice-and-configuration.mdx index 14b217ab91..97ec6a47ab 100644 --- a/versioned_docs/version-6.2/server/clustering/cluster-best-practice-and-configuration.mdx +++ b/versioned_docs/version-6.2/server/clustering/cluster-best-practice-and-configuration.mdx @@ -10,20 +10,27 @@ import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; # Cluster: Best Practices * In this page: - * [Clusters should have an odd number of at least 3 nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes) - * [Database groups follow the same rule when you use cluster-wide transactions](../../server/clustering/cluster-best-practice-and-configuration.mdx#database-groups-follow-the-same-rule-when-you-use-cluster-wide-transactions) + * [Recommended cluster and database group size](../../server/clustering/cluster-best-practice-and-configuration.mdx#recommended-cluster-and-database-group-size) + * [Clusters should have an odd number of at least 3 nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes) + * [Database groups follow the same rule when you use cluster-wide transactions](../../server/clustering/cluster-best-practice-and-configuration.mdx#database-groups-follow-the-same-rule-when-you-use-cluster-wide-transactions) * [Avoid different cluster configurations among the cluster's nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#avoid-different-cluster-configurations-among-the-clusters-nodes) + + ### Clusters should have an odd number of at least 3 nodes + + We recommend setting up clusters with an odd number of nodes equal to or greater than 3. **A single node cluster:** @@ -40,18 +47,22 @@ command will be created, although any database on the surviving node will still For ACID guarantees, a majority of the nodes must agree on every [cluster-wide transaction](../../server/clustering/cluster-transactions.mdx), so having an odd number of nodes makes achieving the majority easier. + +--- ### Database groups follow the same rule when you use cluster-wide transactions -The recommendation above is about the cluster itself - the nodes that vote on + + +The recommendation above relates to the cluster itself - the nodes that vote on Raft commands. The same odd-numbered sizing matters for an individual -**database group** when the database uses +**[database group](../../glossary/database-group.mdx)** when the database uses [cluster-wide transactions](../../server/clustering/cluster-transactions.mdx) (or the [atomic guards](../../client-api/session/cluster-transaction/atomic-guards.mdx) that wrap them). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it. With three members, two must accept; with +group's voting members have accepted it. With three members, two must accept; with five, three must accept; with seven, four. An odd size keeps that count well- defined and keeps a single node failure inside the majority. @@ -61,13 +72,21 @@ keep the group size odd. The database is kept in sync by which keeps writes flowing on any node that is up - so a group of two members already lets the database survive losing a node. + + -### Avoid different cluster configurations among the cluster's nodes + + + Configuration mismatches tend to cause interaction problems between nodes. If you must set [cluster configurations](../../server/configuration/cluster-configuration.mdx) differently in separate nodes, **we recommend first testing it** in a development environment to see that each node interacts properly with the others. + + + + diff --git a/versioned_docs/version-6.2/server/clustering/distribution/distributed-database.mdx b/versioned_docs/version-6.2/server/clustering/distribution/distributed-database.mdx index 3bfd84433e..f14e079ffe 100644 --- a/versioned_docs/version-6.2/server/clustering/distribution/distributed-database.mdx +++ b/versioned_docs/version-6.2/server/clustering/distribution/distributed-database.mdx @@ -67,7 +67,7 @@ If the database also uses [cluster-wide transactions](../cluster-transactions.mdx), prefer an odd group size (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database group's -voting members accept it, and an odd group size means that majority is always +voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-6.2/server/clustering/replication/replication-overview.mdx b/versioned_docs/version-6.2/server/clustering/replication/replication-overview.mdx index 4c09e81d4b..bf3b0eb27c 100644 --- a/versioned_docs/version-6.2/server/clustering/replication/replication-overview.mdx +++ b/versioned_docs/version-6.2/server/clustering/replication/replication-overview.mdx @@ -62,7 +62,7 @@ If the database also uses [cluster-wide transactions](../cluster-transactions.mdx), prefer an odd group size (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it, and an odd group size means that majority +group's voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-6.2/studio/database/create-new-database/general-flow.mdx b/versioned_docs/version-6.2/studio/database/create-new-database/general-flow.mdx index 84c34aa79b..f1f76c2dab 100644 --- a/versioned_docs/version-6.2/studio/database/create-new-database/general-flow.mdx +++ b/versioned_docs/version-6.2/studio/database/create-new-database/general-flow.mdx @@ -89,7 +89,7 @@ If the database also uses [cluster-wide transactions](../../../server/clustering/cluster-transactions.mdx), prefer an odd group size (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database group's -voting members accept it, and an odd group size means that majority is always +voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-csharp.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-csharp.mdx index 987c7f4ad7..b0b7e1eaf6 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-csharp.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-csharp.mdx @@ -33,7 +33,7 @@ If the database also uses [cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), prefer an odd replication factor (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it, and an odd group size means that majority +group's voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-java.mdx b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-java.mdx index 90dddb3dcc..31f5ee3245 100644 --- a/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-java.mdx +++ b/versioned_docs/version-7.0/client-api/operations/server-wide/content/_create-database-java.mdx @@ -32,7 +32,7 @@ If the database also uses [cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), prefer an odd replication factor (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it, and an odd group size means that majority +group's voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-7.0/server/clustering/cluster-best-practice-and-configuration.mdx b/versioned_docs/version-7.0/server/clustering/cluster-best-practice-and-configuration.mdx index 14b217ab91..97ec6a47ab 100644 --- a/versioned_docs/version-7.0/server/clustering/cluster-best-practice-and-configuration.mdx +++ b/versioned_docs/version-7.0/server/clustering/cluster-best-practice-and-configuration.mdx @@ -10,20 +10,27 @@ import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; # Cluster: Best Practices * In this page: - * [Clusters should have an odd number of at least 3 nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes) - * [Database groups follow the same rule when you use cluster-wide transactions](../../server/clustering/cluster-best-practice-and-configuration.mdx#database-groups-follow-the-same-rule-when-you-use-cluster-wide-transactions) + * [Recommended cluster and database group size](../../server/clustering/cluster-best-practice-and-configuration.mdx#recommended-cluster-and-database-group-size) + * [Clusters should have an odd number of at least 3 nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes) + * [Database groups follow the same rule when you use cluster-wide transactions](../../server/clustering/cluster-best-practice-and-configuration.mdx#database-groups-follow-the-same-rule-when-you-use-cluster-wide-transactions) * [Avoid different cluster configurations among the cluster's nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#avoid-different-cluster-configurations-among-the-clusters-nodes) + + ### Clusters should have an odd number of at least 3 nodes + + We recommend setting up clusters with an odd number of nodes equal to or greater than 3. **A single node cluster:** @@ -40,18 +47,22 @@ command will be created, although any database on the surviving node will still For ACID guarantees, a majority of the nodes must agree on every [cluster-wide transaction](../../server/clustering/cluster-transactions.mdx), so having an odd number of nodes makes achieving the majority easier. + +--- ### Database groups follow the same rule when you use cluster-wide transactions -The recommendation above is about the cluster itself - the nodes that vote on + + +The recommendation above relates to the cluster itself - the nodes that vote on Raft commands. The same odd-numbered sizing matters for an individual -**database group** when the database uses +**[database group](../../glossary/database-group.mdx)** when the database uses [cluster-wide transactions](../../server/clustering/cluster-transactions.mdx) (or the [atomic guards](../../client-api/session/cluster-transaction/atomic-guards.mdx) that wrap them). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it. With three members, two must accept; with +group's voting members have accepted it. With three members, two must accept; with five, three must accept; with seven, four. An odd size keeps that count well- defined and keeps a single node failure inside the majority. @@ -61,13 +72,21 @@ keep the group size odd. The database is kept in sync by which keeps writes flowing on any node that is up - so a group of two members already lets the database survive losing a node. + + -### Avoid different cluster configurations among the cluster's nodes + + + Configuration mismatches tend to cause interaction problems between nodes. If you must set [cluster configurations](../../server/configuration/cluster-configuration.mdx) differently in separate nodes, **we recommend first testing it** in a development environment to see that each node interacts properly with the others. + + + + diff --git a/versioned_docs/version-7.0/server/clustering/distribution/distributed-database.mdx b/versioned_docs/version-7.0/server/clustering/distribution/distributed-database.mdx index 3bfd84433e..f14e079ffe 100644 --- a/versioned_docs/version-7.0/server/clustering/distribution/distributed-database.mdx +++ b/versioned_docs/version-7.0/server/clustering/distribution/distributed-database.mdx @@ -67,7 +67,7 @@ If the database also uses [cluster-wide transactions](../cluster-transactions.mdx), prefer an odd group size (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database group's -voting members accept it, and an odd group size means that majority is always +voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-7.0/server/clustering/replication/replication-overview.mdx b/versioned_docs/version-7.0/server/clustering/replication/replication-overview.mdx index 4c09e81d4b..bf3b0eb27c 100644 --- a/versioned_docs/version-7.0/server/clustering/replication/replication-overview.mdx +++ b/versioned_docs/version-7.0/server/clustering/replication/replication-overview.mdx @@ -62,7 +62,7 @@ If the database also uses [cluster-wide transactions](../cluster-transactions.mdx), prefer an odd group size (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it, and an odd group size means that majority +group's voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-7.0/studio/database/create-new-database/general-flow.mdx b/versioned_docs/version-7.0/studio/database/create-new-database/general-flow.mdx index 84c34aa79b..f1f76c2dab 100644 --- a/versioned_docs/version-7.0/studio/database/create-new-database/general-flow.mdx +++ b/versioned_docs/version-7.0/studio/database/create-new-database/general-flow.mdx @@ -89,7 +89,7 @@ If the database also uses [cluster-wide transactions](../../../server/clustering/cluster-transactions.mdx), prefer an odd group size (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database group's -voting members accept it, and an odd group size means that majority is always +voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-csharp.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-csharp.mdx index b14c0bdfb5..77b9e068cd 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-csharp.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-csharp.mdx @@ -33,7 +33,7 @@ If the database also uses [cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), prefer an odd replication factor (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it, and an odd group size means that majority +group's voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-java.mdx b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-java.mdx index 90dddb3dcc..31f5ee3245 100644 --- a/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-java.mdx +++ b/versioned_docs/version-7.1/client-api/operations/server-wide/content/_create-database-java.mdx @@ -32,7 +32,7 @@ If the database also uses [cluster-wide transactions](../../../../server/clustering/cluster-transactions.mdx), prefer an odd replication factor (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it, and an odd group size means that majority +group's voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-7.1/server/clustering/cluster-best-practice-and-configuration.mdx b/versioned_docs/version-7.1/server/clustering/cluster-best-practice-and-configuration.mdx index f5ec3c7151..a7acce949a 100644 --- a/versioned_docs/version-7.1/server/clustering/cluster-best-practice-and-configuration.mdx +++ b/versioned_docs/version-7.1/server/clustering/cluster-best-practice-and-configuration.mdx @@ -10,20 +10,27 @@ import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; import LanguageSwitcher from "@site/src/components/LanguageSwitcher"; import LanguageContent from "@site/src/components/LanguageContent"; +import Panel from "@site/src/components/Panel"; +import ContentFrame from "@site/src/components/ContentFrame"; # Cluster: Best Practices * In this page: - * [Clusters should have an odd number of at least 3 nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes) - * [Database groups follow the same rule when you use cluster-wide transactions](../../server/clustering/cluster-best-practice-and-configuration.mdx#database-groups-follow-the-same-rule-when-you-use-cluster-wide-transactions) + * [Recommended cluster and database group size](../../server/clustering/cluster-best-practice-and-configuration.mdx#recommended-cluster-and-database-group-size) + * [Clusters should have an odd number of at least 3 nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes) + * [Database groups follow the same rule when you use cluster-wide transactions](../../server/clustering/cluster-best-practice-and-configuration.mdx#database-groups-follow-the-same-rule-when-you-use-cluster-wide-transactions) * [Avoid different cluster configurations among the cluster's nodes](../../server/clustering/cluster-best-practice-and-configuration.mdx#avoid-different-cluster-configurations-among-the-clusters-nodes) + + ### Clusters should have an odd number of at least 3 nodes + + We recommend setting up clusters with an odd number of nodes equal to or greater than 3. **A single node cluster:** @@ -40,18 +47,22 @@ command will be created, although any database on the surviving node will still For ACID guarantees, a majority of the nodes must agree on every [cluster-wide transaction](../../server/clustering/cluster-transactions.mdx), so having an odd number of nodes makes achieving the majority easier. + +--- ### Database groups follow the same rule when you use cluster-wide transactions -The recommendation above is about the cluster itself - the nodes that vote on + + +The recommendation above relates to the cluster itself - the nodes that vote on Raft commands. The same odd-numbered sizing matters for an individual -**database group** when the database uses +**[database group](../../glossary/database-group.mdx)** when the database uses [cluster-wide transactions](../../server/clustering/cluster-transactions.mdx) (or the [atomic guards](../../compare-exchange/atomic-guards.mdx) that wrap them). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it. With three members, two must accept; with +group's voting members have accepted it. With three members, two must accept; with five, three must accept; with seven, four. An odd size keeps that count well- defined and keeps a single node failure inside the majority. @@ -61,13 +72,21 @@ keep the group size odd. The database is kept in sync by which keeps writes flowing on any node that is up - so a group of two members already lets the database survive losing a node. + + -### Avoid different cluster configurations among the cluster's nodes + + + Configuration mismatches tend to cause interaction problems between nodes. If you must set [cluster configurations](../../server/configuration/cluster-configuration.mdx) differently in separate nodes, **we recommend first testing it** in a development environment to see that each node interacts properly with the others. + + + + diff --git a/versioned_docs/version-7.1/server/clustering/distribution/distributed-database.mdx b/versioned_docs/version-7.1/server/clustering/distribution/distributed-database.mdx index 3bfd84433e..f14e079ffe 100644 --- a/versioned_docs/version-7.1/server/clustering/distribution/distributed-database.mdx +++ b/versioned_docs/version-7.1/server/clustering/distribution/distributed-database.mdx @@ -67,7 +67,7 @@ If the database also uses [cluster-wide transactions](../cluster-transactions.mdx), prefer an odd group size (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database group's -voting members accept it, and an odd group size means that majority is always +voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-7.1/server/clustering/replication/replication-overview.mdx b/versioned_docs/version-7.1/server/clustering/replication/replication-overview.mdx index 4c09e81d4b..bf3b0eb27c 100644 --- a/versioned_docs/version-7.1/server/clustering/replication/replication-overview.mdx +++ b/versioned_docs/version-7.1/server/clustering/replication/replication-overview.mdx @@ -62,7 +62,7 @@ If the database also uses [cluster-wide transactions](../cluster-transactions.mdx), prefer an odd group size (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database -group's voting members accept it, and an odd group size means that majority +group's voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see diff --git a/versioned_docs/version-7.1/studio/database/create-new-database/general-flow.mdx b/versioned_docs/version-7.1/studio/database/create-new-database/general-flow.mdx index 84c34aa79b..f1f76c2dab 100644 --- a/versioned_docs/version-7.1/studio/database/create-new-database/general-flow.mdx +++ b/versioned_docs/version-7.1/studio/database/create-new-database/general-flow.mdx @@ -89,7 +89,7 @@ If the database also uses [cluster-wide transactions](../../../server/clustering/cluster-transactions.mdx), prefer an odd group size (3, 5, or 7). A cluster-wide transaction commits only after a majority of the database group's -voting members accept it, and an odd group size means that majority is always +voting members have accepted it, and an odd group size means that majority is always a clean (n/2 + 1) - never a tie. For the full reasoning, see