Improve the page on managing servers in cluster #2686

NataliaIvakina · 2025-10-24T13:16:57Z

No description provided.

modules/ROOT/pages/clustering/servers.adoc

neo4j-docops-agent · 2025-10-24T14:02:58Z

This PR includes documentation updates
View the updated docs at https://neo4j-docs-operations-2686.surge.sh

Updated pages:

NataliaIvakina · 2025-10-27T11:22:09Z

modules/ROOT/pages/clustering/servers.adoc

+server.default_advertised_address=server07.example.com
+dbms.cluster.discovery.resolver_type=LIST
+dbms.cluster.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000,server04.example.com:6000,server05.example.com:6000,server06.example.com:6000,
+server.cluster.system_database_mode=PRIMARY


I think we should explain why we set server.cluster.system_database_mode to PRIMARY. Or to SECONDARY. We don't explain anywhere the system database mode.

I agree, I think it would be a helpful addition.

NataliaIvakina · 2025-10-27T11:24:35Z

modules/ROOT/pages/clustering/servers.adoc

+server.cluster.system_database_mode=PRIMARY
 ----
+
+Additionally, you can configure a set of initial settings to provide values for the server's options.


Do we need to add here information about any other configs?

Rather than providing an exhaustive list of initial. settings, should we explain ones prefixed with initial are such settings and then link the configuration settings page?

jackwaudby · 2025-10-27T11:36:11Z

modules/ROOT/pages/clustering/databases.adoc


 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`.
+In a cluster, the `system` database forms its own Raft group.


Our position is that we try mention Raft as little as possible in the documentation as it is an implementation-level detail; in theory we could change consensus algorithms tomorrow. We don't mention Raft anywhere else in this page so I don't think we need to add this line, primarily as we then would need to explain "what is Raft".

jackwaudby · 2025-10-27T11:38:21Z

modules/ROOT/pages/clustering/server-syntax.adoc

-For more information see xref:clustering/servers.adoc#_hosting_databases_on_added_servers[Hosting databases on added servers].
-
-Note that is a cluster-level command, not a server-level command.
+a| Removes all databases from the given servers.


We possibly make this more precise by saying "all user databases", but I don't think that is super important.

jackwaudby · 2025-10-27T11:39:40Z

modules/ROOT/pages/clustering/server-syntax.adoc

+a| Re-balances databases among the servers in the cluster.
+For more information see xref:clustering/servers.adoc#_hosting_databases_on_added_servers[Hosting databases on added servers].
+
+Note that is a cluster-level command, not a server-level command.


Do we define anywhere what is meant by "cluster-level" and "server-level"? It makes sense to me, but possibly not to a user who is less familiar with clustering parlance.

This is a good comment, but I will return to this page later, in another PR. I'd prefer to keep them and explain if it's needed.

jackwaudby · 2025-10-27T11:40:26Z

modules/ROOT/pages/clustering/servers.adoc


-[[server-states]]
-== Server states
+For details on server management command syntax, see xref:clustering/server-syntax.adoc[].


Is this missing something in the []?

jackwaudby · 2025-10-27T11:44:21Z

modules/ROOT/pages/clustering/servers.adoc

+DEALLOCATE DATABASE[S] FROM SERVER[S] 'name'[, ...]
+----
+
+The command reallocates all their hosted databases to other servers in the cluster.


Suggested change

The command reallocates all their hosted databases to other servers in the cluster.

The command reallocates all user databases hosted by the server to other servers in the cluster.

jackwaudby · 2025-10-27T11:47:28Z

modules/ROOT/pages/clustering/servers.adoc

+server.default_advertised_address=server07.example.com
+dbms.cluster.discovery.resolver_type=LIST
+dbms.cluster.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000,server04.example.com:6000,server05.example.com:6000,server06.example.com:6000,
+server.cluster.system_database_mode=PRIMARY


I agree, I think it would be a helpful addition.

jackwaudby · 2025-10-27T11:49:34Z

modules/ROOT/pages/clustering/servers.adoc

+server.cluster.system_database_mode=PRIMARY
 ----
+
+Additionally, you can configure a set of initial settings to provide values for the server's options.


Rather than providing an exhaustive list of initial. settings, should we explain ones prefixed with initial are such settings and then link the configuration settings page?

jackwaudby · 2025-10-27T11:52:01Z

modules/ROOT/pages/clustering/servers.adoc

-`modeConstraint` is used to control whether a server can be used to host a database in only primary or secondary mode.
-`allowedDatabases` and `deniedDatabases` are collections of database names that filter which databases may be hosted on a server.
+
+* `modeConstraint` is used to control whether a server can be used to host a database in only primary, or only secondary mode, or both.


Suggested change

* `modeConstraint` is used to control whether a server can be used to host a database in only primary, or only secondary mode, or both.

* `modeConstraint` is used to control whether a server can only host user databases in primary mode, only in secondary mode, or can host databases in either mode.

jackwaudby · 2025-10-27T11:55:41Z

modules/ROOT/pages/clustering/servers.adoc

+The command `REALLOCATE DATABASE[S]` can be used to rebalance database allocations across the cluster, adding some to the newly added server(s).
+See xref:clustering/databases.adoc#reallocate-databases[Managing databases in a cluster -> Reallocate databases] for more information.


Suggested change

The command `REALLOCATE DATABASE[S]` can be used to rebalance database allocations across the cluster, adding some to the newly added server(s).

See xref:clustering/databases.adoc#reallocate-databases[Managing databases in a cluster -> Reallocate databases] for more information.

possibly reallocating databases some to the newly added server(s).

Adding the possibly might be good as if you add a new server and the allocation is already optimal then no databases will move to the new server. E.g., you have 3 servers with 1 database each, adding server 4 and calling reallocate will have no impact.

Improve the page on managing servers in cluster

1452b1f

NataliaIvakina added cherry-pick-this-to-main WIP labels Oct 24, 2025

NataliaIvakina commented Oct 24, 2025

View reviewed changes

modules/ROOT/pages/clustering/servers.adoc Outdated Show resolved Hide resolved

Update modules/ROOT/pages/clustering/servers.adoc

1237bc0

NataliaIvakina added the clustering label Oct 24, 2025

NataliaIvakina commented Oct 27, 2025

View reviewed changes

jackwaudby self-assigned this Oct 27, 2025

jackwaudby approved these changes Oct 27, 2025

View reviewed changes

NataliaIvakina removed the WIP label Oct 27, 2025

	The command reallocates all their hosted databases to other servers in the cluster.
	The command reallocates all user databases hosted by the server to other servers in the cluster.

	* `modeConstraint` is used to control whether a server can be used to host a database in only primary, or only secondary mode, or both.
	* `modeConstraint` is used to control whether a server can only host user databases in primary mode, only in secondary mode, or can host databases in either mode.

		The command `REALLOCATE DATABASE[S]` can be used to rebalance database allocations across the cluster, adding some to the newly added server(s).
		See xref:clustering/databases.adoc#reallocate-databases[Managing databases in a cluster -> Reallocate databases] for more information.

	The command `REALLOCATE DATABASE[S]` can be used to rebalance database allocations across the cluster, adding some to the newly added server(s).
	See xref:clustering/databases.adoc#reallocate-databases[Managing databases in a cluster -> Reallocate databases] for more information.
	possibly reallocating databases some to the newly added server(s).

Uh oh!

Improve the page on managing servers in cluster #2686

Are you sure you want to change the base?

Improve the page on managing servers in cluster #2686

Uh oh!

Conversation

NataliaIvakina commented Oct 24, 2025

Uh oh!

Uh oh!

neo4j-docops-agent commented Oct 24, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants