From b4421e7bd190d7164f60ab95b01edbb54da6c0a1 Mon Sep 17 00:00:00 2001
From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com>
Date: Mon, 8 Sep 2025 13:57:03 +0200
Subject: [PATCH] Clarify using of the `ALTER SERVER` options (#2551)

Co-authored-by: Nick Giles <100630647+nick-giles-neo@users.noreply.github.com>
---
 modules/ROOT/pages/clustering/servers.adoc | 32 +++++++++++++++++++---
 1 file changed, 28 insertions(+), 4 deletions(-)

diff --git a/modules/ROOT/pages/clustering/servers.adoc b/modules/ROOT/pages/clustering/servers.adoc
index e83fd59b4..9081a3d3b 100644
--- a/modules/ROOT/pages/clustering/servers.adoc
+++ b/modules/ROOT/pages/clustering/servers.adoc
@@ -426,7 +426,7 @@ Likewise, if `ALTER SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' SET OPTIONS {a
 
 The possible options when altering a server are:
 
-[options="header", width="100%", cols="2a,2,^.^"]
+[options="header", width="100%", cols="1a,2,2"]
 |===
 | Option
 | Allowed values
@@ -435,7 +435,7 @@ The possible options when altering a server are:
 | modeConstraint
 | `PRIMARY`, `SECONDARY`, `NONE`
 | Databases may only be hosted on the server in the mode specified by the constraint.
-`None` means there is no constraint and any mode is allowed.
+`NONE` means there is no constraint and any mode is allowed.
 
 | allowedDatabases
 | list of database names, e.g. `["db1", "db2"]`
@@ -459,10 +459,34 @@ This may not be specified in combination with `allowedDatabases`.
 
 As with the `DEALLOCATE DATABASES FROM SERVER ...` command, if the alteration of a server's options renders it impossible for the cluster to satisfy one or more of the databases' topologies, then the command fails and no changes are made.
 
-[NOTE]
+[IMPORTANT]
 ====
 Input provided to `SET OPTIONS {...}` replaces **all** existing options, rather than being combined with them.
-For instance if `SET OPTIONS {modeConstraint:'SECONDARY'}` is executed followed by `SET OPTIONS {allowedDatabases:['foo']}`, the execution of the second `ALTER` removes the mode constraint.
+
+Any previously set values must be specified every time you run the `ALTER SERVER` command; otherwise they will be overwritten to the unset values.
+
+For instance, you run two statements one after the other:
+
+[source,cypher]
+----
+ALTER SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' SET OPTIONS {modeConstraint:'SECONDARY'};
+----
+
+[source,cypher]
+----
+ALTER SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' SET OPTIONS {allowedDatabases:['foo']};
+----
+
+The execution of the second `ALTER SERVER` removes the mode constraint `SECONDARY`, replacing it with `NONE`.
+
+If you want to keep both values `modeConstraint:'SECONDARY'` and `allowedDatabases:['foo']`, you have to explicitly set them in the options for the `ALTER SERVER` command:
+
+[source,cypher]
+----
+ALTER SERVER '25a7efc7-d063-44b8-bdee-f23357f89f01' SET OPTIONS {modeConstraint:'SECONDARY', allowedDatabases:['foo']};
+----
+
+Always check the current configuration with `SHOW SERVERS YIELD *` and reapply unchanged options when using `ALTER SERVER`.
 ====
 
 === Renaming a server