RDoc-2211: Explain why clusters and database groups need an odd number of nodes

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)
 
 </Admonition>
+
+<Admonition type="note" title="">
+
+**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 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
+[Cluster: Best Practices](../../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes).
+
+</Admonition>
+
 ## Create new database
 
 <Admonition type="note" title="">

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)
 
 </Admonition>
+
+<Admonition type="note" title="">
+
+**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 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
+[Cluster: Best Practices](../../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes).
+
+</Admonition>
+
 ## Create new database
 
 <Admonition type="note" title="">

docs/server/clustering/cluster-best-practice-and-configuration.mdx

@@ -11,19 +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
 <Admonition type="note" title="">
 
 * 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)
+   * [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)
 
 </Admonition>
 
 
+<Panel heading="Recommended cluster and database group size">
+
 ### Clusters should have an odd number of at least 3 nodes
 
+<ContentFrame>
+
 We recommend setting up clusters with an odd number of nodes equal to or greater than 3.
 
 **A single node cluster:**  
@@ -40,15 +48,46 @@ 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.
 
+</ContentFrame>
+
+---
+
+### Database groups follow the same rule when you use cluster-wide transactions
+
+<ContentFrame>
 
+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](../../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 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.
 
+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
+</ContentFrame>
+
+</Panel>
+
+<Panel heading="Avoid different cluster configurations among the cluster's nodes">
+
+<ContentFrame>
 
 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.
 
+</ContentFrame>
+
+</Panel>
+
 

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.
 
+<Admonition type="note" title="">
+
+**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 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
+[Cluster: Best Practices](../cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes).
+
+</Admonition>
 
 ## Database Topology
 

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.
+
+<Admonition type="note" title="">
+
+**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 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
+[Cluster: Best Practices](../cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes).
+
+</Admonition>
+
 #### External replication
 
 * __Replicate between__: Two databases that are typically set on different clusters.   

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.  
 </Admonition>
 
+<Admonition type="note" title="">
+
+**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 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
+[Cluster: Best Practices](../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes).
+
+</Admonition>
+
 
 ## 4. Configure Path
 

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)
 
 </Admonition>
+
+<Admonition type="note" title="">
+
+**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 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
+[Cluster: Best Practices](../../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes).
+
+</Admonition>
+
 ## Create new database
 
 <Admonition type="note" title="">

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)
 
 </Admonition>
+
+<Admonition type="note" title="">
+
+**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 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
+[Cluster: Best Practices](../../../../server/clustering/cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes).
+
+</Admonition>
+
 ## Create new database
 
 <Admonition type="note" title="">

versioned_docs/version-6.2/server/clustering/cluster-best-practice-and-configuration.mdx

@@ -10,19 +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
 <Admonition type="note" title="">
 
 * 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)
+   * [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)
 
 </Admonition>
 
 
+<Panel heading="Recommended cluster and database group size">
+
 ### Clusters should have an odd number of at least 3 nodes
 
+<ContentFrame>
+
 We recommend setting up clusters with an odd number of nodes equal to or greater than 3.
 
 **A single node cluster:**  
@@ -39,15 +47,46 @@ 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.
 
+</ContentFrame>
+
+---
+
+### Database groups follow the same rule when you use cluster-wide transactions
+
+<ContentFrame>
 
+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](../../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 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.
 
+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
+</ContentFrame>
+
+</Panel>
+
+<Panel heading="Avoid different cluster configurations among the cluster's nodes">
+
+<ContentFrame>
 
 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.
 
+</ContentFrame>
+
+</Panel>
+
 

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.
 
+<Admonition type="note" title="">
+
+**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 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
+[Cluster: Best Practices](../cluster-best-practice-and-configuration.mdx#clusters-should-have-an-odd-number-of-at-least-3-nodes).
+
+</Admonition>
 
 ## Database Topology