Skip to content

Improve the page on managing servers in cluster #2686

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: dev
Choose a base branch
from
Open

Improve the page on managing servers in cluster #2686

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
1452b1f
Improve the page on managing servers in cluster
NataliaIvakina Oct 24, 2025
1237bc0
Update modules/ROOT/pages/clustering/servers.adoc
NataliaIvakina Oct 24, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
33 changes: 33 additions & 0 deletions modules/ROOT/images/server-lifecycle.svg
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file removed modules/ROOT/images/server-states.png
View file
Open in desktop
Binary file not shown.
Binary file removed modules/ROOT/images/server-states2.png
View file
Open in desktop
Binary file not shown.
Binary file removed modules/ROOT/images/server-states3.png
View file
Open in desktop
Binary file not shown.
Binary file removed modules/ROOT/images/server-states4.png
View file
Open in desktop
Binary file not shown.
4 changes: 3 additions & 1 deletion modules/ROOT/pages/clustering/databases.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,10 +16,12 @@ The `system` database contains metadata on the DBMS and security configuration.
When connected to this database you can only perform a specific set of administrative tasks, such as managing databases, servers, and access control.

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.
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.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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".

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].
Expand Down
1 change: 1 addition & 0 deletions modules/ROOT/pages/clustering/index.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ This chapter describes the following:
* 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.
** 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.
Expand Down
81 changes: 50 additions & 31 deletions modules/ROOT/pages/clustering/server-syntax.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,21 +1,23 @@
:description: This section provides a summary of server management Cypher syntax.
[role=enterprise-edition]
[[server-commands-reference]]
= Server commands reference
= Server management command syntax

Servers can be added and managed using a set of Cypher administration commands executed against the `system` database.
Servers can be added and managed using a set of Cypher administrative commands executed against the `system` database.

When connected to the DBMS over `bolt`, administration commands are automatically routed to the `system` database.
When connected to the DBMS over `bolt`, administrative commands are automatically routed to the `system` database.


[[server-management-syntax]]
== Server management command syntax

[NOTE]
====
More details about the syntax descriptions can be found xref:database-administration/syntax.adoc[here].
More details about the syntax descriptions can be found on the page xref:database-administration/syntax.adoc#administration-syntax-reading[Database management command syntax -> Reading the administrative commands syntax].
====

=== Enable a server

[cols="<15s,<85"]
|===
| Command
Expand All @@ -38,73 +40,86 @@ a| `GRANT SERVER MANAGEMENT`
(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===


=== List servers

[cols="<15s,<85"]
|===
| Command
m| ALTER SERVER
m| SHOW SERVERS

| Syntax
a|
[source, syntax, role=noheader]
----
ALTER SERVER 'name' SET OPTIONS "{" option: value[,...] "}"
SHOW SERVER[S]
[YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
[WHERE expression]
[RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
----

| Description
a| Changes the constraints for a server.
For more information see xref:clustering/servers.adoc#alter-server-options[Altering server options].
a| Lists all servers visible to the cluster.
For more information see xref:clustering/servers.adoc#_listing_servers[Listing servers].

| Required privilege
a| `GRANT SERVER MANAGEMENT`
a| `GRANT SHOW SERVERS`

(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===


=== Alter server's options

[cols="<15s,<85"]
|===
| Command
m| RENAME SERVER
m| ALTER SERVER

| Syntax
a|
[source, syntax, role=noheader]
----
RENAME SERVER 'name' TO 'newName'
ALTER SERVER 'name' SET OPTIONS "{" option: value[,...] "}"
----

| Description
a| Changes the name of a server.
For more information see xref:clustering/servers.adoc#_renaming_a_server[Renaming a server].
a| Changes the constraints for a server.
For more information see xref:clustering/servers.adoc#alter-server-options[Altering server options].

| Required privilege
a| `GRANT SERVER MANAGEMENT`

(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===

=== Rename a server

[cols="<15s,<85"]
|===
| Command
m| DEALLOCATE DATABASES
m| RENAME SERVER

| Syntax
a|
[source, syntax, role=noheader]
----
[DRYRUN] DEALLOCATE DATABASE[S] FROM SERVER[S] 'name'[, ...]
RENAME SERVER 'name' TO 'newName'
----

| Description
a| Removes all databases from the given servers.
For more information see xref:clustering/servers.adoc#_deallocating_databases_from_a_server[Deallocating databases from server].
a| Changes the name of a server.
For more information see xref:clustering/servers.adoc#_renaming_a_server[Renaming a server].

| Required privilege
a| `GRANT SERVER MANAGEMENT`

(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===


=== Remove a server

[cols="<15s,<85"]
|===
| Command
Expand All @@ -127,51 +142,55 @@ a| `GRANT SERVER MANAGEMENT`
(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===


=== Reallocate databases in a cluster

[cols="<15s,<85"]
|===
| Command
m| SHOW SERVERS
m| REALLOCATE DATABASES

| Syntax
a|
[source, syntax, role=noheader]
----
SHOW SERVER[S]
[YIELD { * \| field[, ...] } [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
[WHERE expression]
[RETURN field[, ...] [ORDER BY field[, ...]] [SKIP n] [LIMIT n]]
[DRYRUN] REALLOCATE DATABASE[S]
----

| Description
a| Lists all servers visible to the cluster.
For more information see xref:clustering/servers.adoc#_listing_servers[Listing servers].
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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


| Required privilege
a| `GRANT SHOW SERVERS`
a| `GRANT SERVER MANAGEMENT`

(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===


=== Deallocate databases from a server

[cols="<15s,<85"]
|===
| Command
m| REALLOCATE DATABASES
m| DEALLOCATE DATABASES

| Syntax
a|
[source, syntax, role=noheader]
----
[DRYRUN] REALLOCATE DATABASE[S]
[DRYRUN] DEALLOCATE DATABASE[S] FROM SERVER[S] 'name'[, ...]
----

| Description
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.
a| Removes all databases from the given servers.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

For more information see xref:clustering/servers.adoc#_deallocating_databases_from_a_server[Deallocating databases from server].

| Required privilege
a| `GRANT SERVER MANAGEMENT`

(see xref:authentication-authorization/dbms-administration.adoc#access-control-dbms-administration-privilege-management[SERVER MANAGEMENT privileges])
|===

Loading