Rewrite the introduction to the Clustering section

Author: NataliaIvakina

modules/ROOT/content-nav.adoc

@@ -151,7 +151,7 @@
 *** xref:clustering/monitoring/show-databases-monitoring.adoc[]
 *** xref:clustering/monitoring/endpoints.adoc[]
 *** xref:clustering/monitoring/status-check.adoc[]
-** Resilient cluster deployment
+** Resilient multi-region cluster deployment
 *** xref:clustering/multi-region-deployment/geo-redundant-deployment.adoc[]
 *** xref:clustering/multi-region-deployment/multi-data-center-routing.adoc[]
 *** xref:clustering/multi-region-deployment/disaster-recovery.adoc[]

modules/ROOT/images/follower-writer.svg

@@ -374,9 +374,10 @@ In production environments, external access to the backup port should be blocked
 In a cluster topology, it is possible to take a backup from any server hosting the database to backup, and each server has two configurable ports capable of serving a backup.
 These ports are configured by `server.backup.listen_address` and `server.cluster.listen_address` respectively.
 Functionally, they are equivalent for backups, but separating them can allow some operational flexibility, while using just a single port can simplify the configuration.
-It is generally recommended to select secondary servers to act as backup servers since they are more numerous than primary servers in typical cluster deployments.
-Furthermore, the possibility of performance issues on a secondary server, caused by a large backup, does not affect the performance or redundancy of the primary servers.
-If a secondary server is not available, then a primary can be selected based on factors, such as its physical proximity, bandwidth, performance, and liveness.
+
+It is generally recommended to select secondary database copies to act as backup resources since they are more numerous than primary copies in typical cluster deployments.
+Furthermore, the possibility of performance issues on a secondary database allocation, caused by a large backup, does not affect the performance or redundancy of the primaries.
+If a secondary is not available, then a primary can be selected based on factors, such as its physical proximity, bandwidth, performance, and liveness.
 
 [NOTE]
 ====

modules/ROOT/images/operational-view.svg …ROOT/images/operational-view_current.svgmodules/ROOT/images/operational-view.svg renamed to modules/ROOT/images/operational-view_current.svg modules/ROOT/images/operational-view.svg renamed to modules/ROOT/images/operational-view_current.svg

@@ -4,9 +4,11 @@
 [[database-management]]
 = Managing databases in a cluster
 
-When creating a database or altering it after creation, you can set the number of both primary and secondary servers to host your database.
-To specify the initial topology, use the command `CREATE DATABASE`.
+When creating a database or altering it after creation, you can specify its role: `primary` or `secondary`.
+To specify the initial database topology, use the Cypher command `CREATE DATABASE`.
 To change the topology once the database is created, run the `ALTER DATABASE` command.
+Note that the database role must be aligned with the server’s `modeConstraint`, which value can be `PRIMARY`, or `SECONDARY`, or `NONE`.
+
 If a database is no longer needed, the command `DROP DATABASE` deletes the database from the cluster.
 
 [[cluster-system-db]]
@@ -18,6 +20,7 @@ When connected to this database you can only perform a specific set of administr
 In the clustered environment, the `system` database can be in a primary or secondary mode.
 To configure its mode, use the xref:configuration/configuration-settings.adoc#config_server.cluster.system_database_mode[`server.cluster.system_database_mode`] setting in the _neo4j.conf_ file.
 This has to be done before starting the Neo4j process.
+For guidelines on how to choose the mode for the `system` database, see xref:clustering/introduction.adoc#primaries-secondaries-for-system-db[Introduction -> Primaries and secondaries for the `system` database].
 
 Deploying a cluster for the first time, consider configuring the xref:configuration/configuration-settings.adoc#config_dbms.cluster.minimum_initial_system_primaries_count[`dbms.cluster.minimum_initial_system_primaries_count`].
 This setting defaults to `3`.
@@ -26,13 +29,16 @@ See xref:clustering/setup/deploy.adoc[] for details.
 For information on how to recover the `system` database, refer to the xref:clustering/multi-region-deployment/disaster-recovery.adoc[Disaster recovery guide].
 
 
-
 [[create-database]]
-== `CREATE DATABASE`
+== Create databases
+
+The command to create a standard database in a cluster is not significantly different from the command to create a database in a non-clustered environment.
+See xref:database-administration/standard-databases/create-databases.adoc[] for more information on database management on single servers.
+
+The difference in a clustered environment is that the database topology can be specified, i.e. how many primaries and secondaries are desired for the database.
+For more details on how many primaries and  secondaries it is recommended to have, see xref:clustering/introduction.adoc[].
 
-The command to create a database in a cluster is not significantly different from the command to create a database in a non-clustered environment (see xref:database-administration/standard-databases/create-databases.adoc[Create, start, and stop databases] for more information on database management on single servers).
-The difference in a clustered environment is that the topology can be specified, i.e. how many primaries and secondaries are desired for the database.
-To create a database `foo` with 3 servers hosting the database in primary mode and 2 servers in secondary mode, run the following command:
+To create a database `foo` with three primaries and two secondaries, run the following Cypher command:
 
 [source, cypher]
 ----
@@ -59,26 +65,24 @@ CREATE DATABASE $dbname TOPOLOGY $primary PRIMARIES $secondary SECONDARIES
 
 The command can only be executed successfully if the cluster's servers are able to satisfy the specified topology.
 If they are not, the command results in an error.
-For example, if the cluster's servers are set up with mode constraints to contain two primaries and three secondaries, or if only four servers exist, the command fails with an error.
+For example, if only four servers exist, the command fails with an error.
+Also, it fails if two servers are set up with a mode constraint of primary, and three servers are set up with a mode constraint of secondary.
 
-[NOTE]
-====
-If `TOPOLOGY` is not specified, the database is created according to `initial.dbms.default_primaries_count` and `initial.dbms.default_secondaries_count` specified in _neo4j.conf_.
-After cluster startup, you can overwrite these values using the `dbms.setDefaultAllocationNumbers` procedure.
-====
+If `TOPOLOGY` is not specified, the database is created according to xref:configuration/configuration-settings.adoc#config_initial.dbms.default_primaries_count[`initial.dbms.default_primaries_count`] and xref:configuration/configuration-settings.adoc#config_initial.dbms.default_secondaries_count[`initial.dbms.default_secondaries_count`] specified in _neo4j.conf_.
+After cluster startup, you can overwrite these values using the xref:procedures.adoc#procedure_dbms_setDefaultAllocationNumbers[`dbms.setDefaultAllocationNumbers()`] procedure.
 
-[NOTE]
-====
-A `CREATE DATABASE` command allocates the database, therefore there is no requirement to execute `REALLOCATE DATABASES` (described in xref:clustering/servers.adoc#_hosting_databases_on_added_servers[Hosting databases on added servers]).
+A `CREATE DATABASE` command allocates the database, therefore there is no requirement to run `REALLOCATE DATABASES` (described in xref:clustering/servers.adoc#_hosting_databases_on_added_servers[Hosting databases on added servers]).
 
 However, over time, or after several `CREATE DATABASE` commands have been issued, the distribution of databases can become unbalanced.
 At this point you can run `REALLOCATE DATABASES` to make the cluster re-balance databases across all servers that are part of the cluster.
-====
+
 
 [[alter-database]]
-== `ALTER DATABASE`
+== Modify database topology and read/write access
+
+To alter the topology of or read/write access to a database after its creation, use the command `ALTER DATABASE`.
 
-To alter the topology of or read/write access to a database after it has been created, use the command `ALTER DATABASE`.
+For information about the command syntax, see xref:database-administration/standard-databases/alter-databases.adoc[].
 
 [[alter-topology]]
 === Alter database topology
@@ -89,6 +93,7 @@ To change the topology of the database `foo` from the previous example, run the
 ----
 ALTER DATABASE foo SET TOPOLOGY 2 PRIMARIES 1 SECONDARY
 ----
+
 Alternatively, you can use link:{neo4j-docs-base-uri}/cypher-manual/current/syntax/parameters[parameters] to provide the number of primaries and secondaries:
 
 .Parameters
@@ -107,7 +112,7 @@ Alternatively, you can use link:{neo4j-docs-base-uri}/cypher-manual/current/synt
 ALTER DATABASE $dbname SET TOPOLOGY $primary PRIMARIES $secondary SECONDARIES
 ----
 
-Like the `CREATE DATABASE` command, this command results in an error if the cluster does not contain sufficient servers to satisfy the requested topology.
+Like the `CREATE DATABASE` command, the `ALTER DATABASE` command results in an error if the cluster does not contain sufficient servers to satisfy the requested topology.
 
 Additionally, `ALTER DATABASE` is optionally idempotent and also results in an error if the database does not exist.
 It is possible to append the command with `IF EXISTS` to make sure that no error is returned if the database does not exist.

modules/ROOT/images/operational-view_new.svg

@@ -5,28 +5,33 @@
 
 This chapter describes the following:
 
-* xref:clustering/introduction.adoc[Introduction] -- An overview of the clustering architecture.
-* Setting up a cluster -- The basics of configuring and deploying a new cluster.
+* xref:clustering/introduction.adoc[Introduction: Neo4j clustering architecture] -- An overview of Neo4j clustering basics.
+
+* **Setting up a cluster** -- The basics of configuring and deploying a new cluster.
 ** xref:clustering/setup/deploy.adoc[Deploy a basic cluster] -- How to set up a basic cluster.
 ** xref:clustering/setup/analytics-cluster.adoc[Deploy an analytics cluster] -- How to deploy a special case Neo4j cluster for analytic queries.
 ** xref:clustering/setup/single-to-cluster.adoc[Move from a standalone deployment to a cluster] -- This section describes how to move from a single Neo4j server to Neo4j cluster.
 ** xref:clustering/setup/reconciler.adoc[Reconciler] -- An internal component that observes the requested state of a server and makes changes to the server to match that state.
 ** xref:clustering/setup/discovery.adoc[Cluster server discovery] -- How servers in a cluster discover each other and form a cluster.
 ** xref:clustering/setup/routing.adoc[Leadership, routing and load balancing] -- Election of leaders, routing and load balancing.
 ** xref:clustering/setup/encryption.adoc[Intra-cluster encryption] -- How to secure the cluster communication.
+
 * xref:clustering/servers.adoc[Managing servers in a cluster] -- How to manage the servers in a cluster.
 * xref:clustering/unbind.adoc[Unbind a server] -- How to remove and archive the cluster state of a cluster server so that it can rebind to a cluster.
 * xref:clustering/databases.adoc[Managing databases in a cluster] -- How to manage the databases in a cluster.
 * xref:clustering/unbind-system-database.adoc[Unbind the `system` database] -- How to remove and archive the cluster state for the `system` database.
-* Monitoring -- Monitoring of a cluster.
+
+* **Monitoring** -- Monitoring of a cluster.
 ** xref:clustering/monitoring/show-servers-monitoring.adoc[Monitor servers] -- The tools available for monitoring the servers in a cluster.
 ** xref:clustering/monitoring/show-databases-monitoring.adoc[Monitor databases] -- The tools available for monitoring the databases in a cluster.
 ** xref:clustering/monitoring/endpoints.adoc[Monitor cluster endpoints for status information] -- The endpoints and semantics of endpoints used to monitor the health of the cluster.
 ** xref:clustering/monitoring/status-check.adoc[Monitor replication status] -- The procedure to monitor which members of a clustered database are up-to-date and can participate in a successful replication.
-* Resilient cluster deployment -- Recommendations and guidance on how to set up a resilient cluster which ensures your database stays available, fast, and recoverable even under failures.
+
+* **Resilient multi-region cluster deployment** -- Recommendations and guidance on how to set up a resilient cluster which ensures your database stays available, fast, and recoverable even under failures.
 ** xref:clustering/multi-region-deployment/geo-redundant-deployment.adoc[] -- Recommended patterns of cluster deployment across multiple cloud regions / data centers.
 ** xref:clustering/multi-region-deployment/multi-data-center-routing.adoc[Multi-data center routing] -- Clusters on multi-data centers.
 ** xref:clustering/multi-region-deployment/disaster-recovery.adoc[Disaster recovery] -- How to recover a cluster in the event of a disaster.
+
 * xref:clustering/settings.adoc[Settings reference] -- A summary of the most important cluster settings.
 * xref:clustering/server-syntax.adoc[Server commands reference] -- Reference of Cypher administrative commands to add and manage servers.
 * xref:clustering/glossary.adoc[Clustering glossary] -- A glossary of terms related to the Neo4j clustering.