5.x-cherry-pick-1127 (#1130)

Co-authored-by: Jack Waudby <[email protected]>

Author: AlexicaWright

modules/ROOT/pages/clustering/databases.adoc

@@ -67,6 +67,19 @@ See xref:clustering/databases.adoc#cluster-seed[Seed a cluster] further on for i
 Also, it is possible to automatically transition _from_ a topology with a single primary host to multiple primary hosts.
 Keep in mind that during such a transition, the database will be unavailable for a short period of time.
 
+`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.
+
+.Query
+[source, cypher]
+----
+ALTER DATABASE nonExisting IF EXISTS SET TOPOLOGY 1 PRIMARY 0 SECONDARY
+----
+
+[role="statsonlyqueryresult"]
+0 rows
 // This part can be added back once it has been implemented.
 // The allocation approach can be specified with the setting `initial.dbms.database_allocator`.
 // The available options are:

modules/ROOT/pages/clustering/servers.adoc

@@ -49,6 +49,7 @@ Additionally, servers which are deallocating will not have any further databases
 
 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. 
 
 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_.