Allow parameters in CREATE/ALTER DATABASE TOPOLOGY (#1911)

Document this change: neo-technology/neo4j#27665

---------

Co-authored-by: Reneta Popova <[email protected]>

Author: l-heemann

modules/ROOT/pages/clustering/databases.adoc

@@ -19,6 +19,23 @@ To create a database `foo` with 3 servers hosting the database in primary mode a
 ----
 CREATE DATABASE foo TOPOLOGY 3 PRIMARIES 2 SECONDARIES
 ----
+Alternatively, starting from 5.26, you can use link:{neo4j-docs-base-uri}/cypher-manual/{page-version}/syntax/parameters[parameters] to provide the number of primaries and secondaries:
+
+.Parameters
+[source,javascript, indent=0]
+----
+{
+  "dbname": "foo",
+  "primary": 3,
+  "secondary": 2
+}
+----
+
+.Query
+[source, cypher, indent=0]
+----
+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.
@@ -50,6 +67,23 @@ To change the topology of the database `foo` from the previous example, the comm
 ----
 ALTER DATABASE foo SET TOPOLOGY 2 PRIMARIES 1 SECONDARY
 ----
+Alternatively, starting from 5.26, you can use link:{neo4j-docs-base-uri}/cypher-manual/{page-version}/syntax/parameters[parameters] to provide the number of primaries and secondaries:
+
+.Parameters
+[source,javascript, indent=0]
+----
+{
+  "dbname": "foo",
+  "primary": 2,
+  "secondary": 1
+}
+----
+
+.Query
+[source, cypher, indent=0]
+----
+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.
 
@@ -75,7 +109,7 @@ Keep in mind that during such a transition, the database will be unavailable for
 `ALTER DATABASE` commands are optionally idempotent, with the default behavior to fail with an error if the database does not exist.
 Appending `IF EXISTS` to the command ensures that no error is returned and nothing happens should the database not exist.
 
-If the `ALTER DATABASE` command decreases the number of allocations of a database, allocations on xref:clustering/servers.adoc#_cordoned_servers[cordoned servers] are removed first.
+If the `ALTER DATABASE` command decreases the number of allocations of a database, allocations on xref:clustering/servers.adoc#cordoned-state[cordoned servers] are removed first.
 
 .Query
 [source, cypher]
@@ -401,7 +435,7 @@ In this case, the address for `server01` is `localhost:7687` and thus, the serve
 The topology of `foo` is stored in the `system` database and when you create it, it is allocated according to the default topology (which can be shown with `CALL dbms.showTopologyGraphConfig`).
 This may be different from the topology of `foo` when it was backed up.
 If you want to ensure a certain allocation across the cluster, you can specify the desired topology with the `TOPOLOGY` clause in the `CREATE DATABASE` command.
-See <<#_create_database, `CREATE DATABASE`>> for more information.
+See <<create-database, `CREATE DATABASE`>> for more information.
 +
 [source, cypher, role=noplay]
 ----

modules/ROOT/pages/clustering/servers.adoc

@@ -92,11 +92,12 @@ When a server is in the deallocated state, it no longer hosts any databases besi
 Additionally, deallocated servers cannot have any further databases allocated to them.
 Note that there is a known situation in which a previously deallocated offline server can transiently show as deallocating when restarting, it will, however, eventually return to the deallocated state without intervention.
 
+[cordoned-state]
 === Cordoned state
 
 The _Cordoned_ state is similar to _Deallocating_ in that servers in this state will not be allocated to host additional databases.
 Unlike _Deallocating_ however, cordoned servers do not lose the databases they already host.
-It is worth noting that when decreasing the number of allocations of a database, allocations on cordoned servers are removed first. 
+It is worth noting that when decreasing the number of allocations of a database, allocations on cordoned servers are removed first.
 
 A server is transitioned from the _Enabled_ state to the _Cordoned_ state by executing the procedure `dbms.cluster.cordonServer`.
 A server in the _Cordoned_ state may be transitioned to _Deallocating_, or back to _Enabled_.