Skip to content

Clarify situation when enabling servers #2623

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 6 commits into
base: dev
Choose a base branch
from
Open

Clarify situation when enabling servers #2623

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
9ed87b7
Clarify situation when enabling newly added servers
NataliaIvakina Sep 29, 2025
752e281
Add info about initial setting to the Deploy cluster page
NataliaIvakina Sep 29, 2025
bd4d403
Update deploy.adoc
NataliaIvakina Sep 29, 2025
5ea5ef4
Update modules/ROOT/pages/clustering/setup/deploy.adoc
NataliaIvakina Oct 2, 2025
e54fb4a
Apply suggestions from code review
NataliaIvakina Oct 3, 2025
76dfab7
Update deploy.adoc
NataliaIvakina Oct 6, 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
2 changes: 1 addition & 1 deletion modules/ROOT/pages/changes-deprecations-removals.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ Instead use the value of xref:configuration/configuration-settings.adoc#config_s
Instead use the value of xref:configuration/configuration-settings.adoc#config_server.cluster.listen_address[`server.cluster.listen_address`].

|link:{neo4j-docs-base-uri}/operations-manual/5/configuration/configuration-settings#config_server.groups[server.groups] label:enterprise[Enterprise Edition]
|Replaced by xref:configuration/configuration-settings.adoc#config_server.tags[`initial.server.tags`].
|Replaced by xref:configuration/configuration-settings.adoc#config_initial.server.tags[`initial.server.tags`].

|link:{neo4j-docs-base-uri}/operations-manual/5/configuration/configuration-settings#config_server.memory.off_heap.block_cache_size[server.memory.off_heap.block_cache_size]
|Removed without replacement.
Expand Down
2 changes: 1 addition & 1 deletion ...es/ROOT/pages/clustering/multi-region-deployment/multi-data-center-routing.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Applying the same tag to multiple servers logically groups them together.
Note that servers can have mulitple tags.

Server tags are defined as a key that maps onto a set of servers in a cluster.
Server tags are defined on each server using the xref:configuration/configuration-settings.adoc#config_server.tags[`initial.server.tags`] parameter in _neo4j.conf_.
Server tags are defined on each server using the xref:configuration/configuration-settings.adoc#config_initial.server.tags[`initial.server.tags`] parameter in _neo4j.conf_.
Each server in a cluster can be tagged with to zero or more server tags.
Server tags can be altered at runtime via the `ALTER SERVER` command,
see xref:clustering/servers.adoc#alter-server-options[Altering server options] for more details.
Expand Down
29 changes: 26 additions & 3 deletions modules/ROOT/pages/clustering/servers.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,8 +37,19 @@ When first discovered, a server's name defaults to the value of its generated se
[[server-enabled-state]]
=== Enabled state

A server in the free state needs to be explicitly enabled in order to be considered an active member of the cluster.
The command `ENABLE SERVER server name` is used to transition a server into this _Enabled_ state.
When you deploy a cluster for the first time, at least the minimum number of servers included in the initial deployment are automatically enabled.
For details, refer to the example on how to xref:clustering/setup/deploy.adoc#cluster-example-configure-a-three-primary-cluster[Configure a cluster with three servers].

If you add a new server after the cluster is already running, the server is added in the `FREE` state.
A server in the `FREE` state needs to be explicitly enabled in order to be considered an active member of the cluster.

To transition a server into the _Enabled_ state, use the command `ENABLE SERVER`:

[source, syntax, role=noheader]
----
ENABLE SERVER 'serverId' [OPTIONS "{" option: value[,...] "}"]
----

The server's initial name is its ID.
If the server is already enabled and the command is executed with the same options, nothing is changed.

Expand Down Expand Up @@ -72,11 +83,23 @@ This may not be specified in combination with `allowedDatabases`.

[NOTE]
====
When a server is enabled, if no `OPTIONS` are not provided, the default server values are taken from the settings `initial.server.mode_constraint`, `initial.server.allowed_databases`, `initial.server.denied_databases`, and/or `initial.server.tags`.
When a server is enabled, if no `OPTIONS` are provided, the default server's values are taken from the settings:

* xref:configuration/configuration-settings.adoc#config_initial.server.mode_constraint[`initial.server.mode_constraint`]
* xref:configuration/configuration-settings.adoc#config_initial.server.allowed_databases[`initial.server.allowed_databases`]
* xref:configuration/configuration-settings.adoc#config_initial.server.denied_databases[`initial.server.denied_databases`]
* and/or xref:configuration/configuration-settings.adoc#config_initial.server.tags[`initial.server.tags`]

All these settings are only effective when enabling the relevant server.
====

Another option to enable servers is to have the DBMS automatically enable free servers.
Do this either by setting xref:configuration/configuration-settings.adoc#config_initial.dbms.automatically_enable_free_servers[`initial.dbms.automatically_enable_free_servers`] to `true` before starting the deployment for the first time, or running `CALL dbms.cluster.setAutomaticallyEnableFreeServers(true);`.

Once enabled, the server may be allocated databases to host.

If you need to change some of the server's values, use the <<alter-server-options, `ALTER SERVER`>> command.



[[deallocating-state]]
Expand Down
130 changes: 88 additions & 42 deletions modules/ROOT/pages/clustering/setup/analytics-cluster.adoc
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,44 +16,43 @@ Bear in mind that the GDS library does **not** support fault tolerance and there
=== Deploy the cluster


.Configure a cluster with five servers, two only for read queries


In this example, three servers named `server01.example.com`, `server02.example.com` and `server03.example.com` are configured as the transactional part of the cluster.
. Configure a cluster with five servers, two only for read queries
+
In this example, three servers named `server01.example.com`, `server02.example.com`, and `server03.example.com` are configured as the transactional part of the cluster.
Two more servers names `server04.example.com` and `server05.example.com` are configured for the analytical queries.
Neo4j Enterprise Edition is installed on all five servers.
They are configured by preparing xref:configuration/file-locations.adoc[_neo4j.conf_] on each server.

+
Key points:

+
* All servers include _all_ members in their discovery list.
* The servers for analytics have mode constraints configured that restrict their hosting mode to _secondary_ to prevent them from participating in normal write operations.
* The servers for analytics have their mode constraints configured to _SECONDARY_ to prevent them from participating in write operations.
* In the example below, you set `dbms.cluster.discovery.resolver_type=LIST`.

+
._neo4j.conf_ on server01.example.com:
[source, properties]
----
server.default_listen_address=0.0.0.0
server.default_advertised_address=server01.example.com
dbms.cluster.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000,server04.example.com:6000,server05.example.com:6000
----

+
._neo4j.conf_ on server02.example.com:
[source, properties]
----
server.default_listen_address=0.0.0.0
server.default_advertised_address=server02.example.com
dbms.cluster.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000,server04.example.com:6000,server05.example.com:6000
----

+
._neo4j.conf_ on server03.example.com:
[source, properties]
----
server.default_listen_address=0.0.0.0
server.default_advertised_address=server03.example.com
dbms.cluster.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000,server04.example.com:6000,server05.example.com:6000
----

+
._neo4j.conf_ on server04.example.com - an analytics server:
[source, properties]
----
Expand All @@ -63,7 +62,7 @@ dbms.cluster.endpoints=server01.example.com:6000,server02.example.com:6000,serve
initial.server.mode_constraint=SECONDARY
server.cluster.system_database_mode=SECONDARY
----

+
._neo4j.conf_ on server05.example.com - an analytics server:
[source, properties]
----
Expand All @@ -74,37 +73,37 @@ initial.server.mode_constraint=SECONDARY
server.cluster.system_database_mode=SECONDARY
----

The Neo4j servers are ready to be started.
. The Neo4j servers are ready to be started.
The startup order does not matter.

After the cluster has started, it is possible to connect to any of the instances and run `SHOW SERVERS` to check the status of the cluster.
. After the cluster has started, it is possible to connect to any of the instances and run `SHOW SERVERS` to check the status of the cluster.
This shows information about each member of the cluster:

+
[source, cypher, role=noplay]
----
SHOW SERVERS;
----

+
[queryresult]
----
+-----------------------------------------------------------------------------------------------------------+
| name | address | state | health | hosting |
+-----------------------------------------------------------------------------------------------------------+
+----------------------------------------------------------------------------------------------------------+
| name | address | state | health | hosting |
+----------------------------------------------------------------------------------------------------------+
| "f3bd1199-bc6f-4a38-b25c-5f7588df5182" | "server01:7687" | "Enabled" | "Available" | ["system", "neo4j"] |
| "b331e481-c2ba-4b4e-82f3-bb51fe171483" | "server02:7687" | "Enabled" | "Available" | ["system"] |
| "bd80e8fd-a51b-406a-9ed4-42daf4792aa6" | "server03:7687" | "Enabled" | "Available" | ["system"] |
| "df3758b1-337f-4b8a-a9de-8e745ca96549" | "server04:7687" | "Free" | "Available" | ["system"] |
| "9207bfd9-aa1b-40c2-b965-edcd3955a20e" | "server05:7687" | "Free" | "Available" | ["system"] |
+-----------------------------------------------------------------------------------------------------------+
+----------------------------------------------------------------------------------------------------------+
----

+
For more extensive information about each server, use the `SHOW SERVERS YIELD *` command:

+
[source, cypher, role=noplay]
----
SHOW SERVERS YIELD *;
----

+
[queryresult]
----
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Expand All @@ -118,6 +117,30 @@ SHOW SERVERS YIELD *;
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
----

. To support analytic queries on the secondary servers, you have to explicitly enable them by running:
+
[source, cypher, role=noplay]
----
ENABLE SERVER "df3758b1-337f-4b8a-a9de-8e745ca96549";
ENABLE SERVER "9207bfd9-aa1b-40c2-b965-edcd3955a20e";
----
+
To check the result, run `SHOW SERVERS`.
The output should show:
+
[queryresult]
----
+----------------------------------------------------------------------------------------------------------+
| name | address | state | health | hosting |
+----------------------------------------------------------------------------------------------------------+
| "f3bd1199-bc6f-4a38-b25c-5f7588df5182" | "server01:7687" | "Enabled" | "Available" | ["system", "neo4j"] |
| "b331e481-c2ba-4b4e-82f3-bb51fe171483" | "server02:7687" | "Enabled" | "Available" | ["system"] |
| "bd80e8fd-a51b-406a-9ed4-42daf4792aa6" | "server03:7687" | "Enabled" | "Available" | ["system"] |
| "df3758b1-337f-4b8a-a9de-8e745ca96549" | "server04:7687" | "Enabled" | "Available" | ["system"] |
| "9207bfd9-aa1b-40c2-b965-edcd3955a20e" | "server05:7687" | "Enabled" | "Available" | ["system"] |
+----------------------------------------------------------------------------------------------------------+
----

[[cluster-example-create-databases-on-cluster]]
=== Create new databases in the cluster

Expand Down Expand Up @@ -153,22 +176,22 @@ The following example shows how to set up a non-fault tolerant analytics cluster

=== Deploy the cluster

.Configure a cluster with three servers

. Configure a cluster with three servers
+
In this example, three servers named `server01.example.com`, `server02.example.com` and `server03.example.com` are configured.
Neo4j Enterprise Edition is installed on all three servers.
They are configured by preparing xref:configuration/file-locations.adoc[_neo4j.conf_] on each server.
Note that `server01.example.com` is different from the others, and is the only server where write operations take place.
The other servers are able to execute read queries, and if using GDS, to write results back to the writing server.

+
Key points:

+
* The writer server only has itself in the list of discovery.
This means it does not seek out the other members when it starts, they have to discover it.
This is required in order to have a cluster with only a single primary for the `system` database.
* The servers for analytics have mode constraints configured that restrict their hosting mode to _secondary_ to prevent them from participating in normal write operations.
* The servers for analytics have their mode constraints configured to `SECONDARY` to prevent them from participating in write operations.
* In the example below, you set `dbms.cluster.discovery.resolver_type=LIST`.

+
._neo4j.conf_ on server01.example.com - the writer:
[source, properties]
----
Expand All @@ -177,7 +200,7 @@ server.default_advertised_address=server01.example.com
# Only has self in this list
dbms.cluster.endpoints=server01.example.com:6000
----

+
._neo4j.conf_ on server02.example.com - an analytics server:
[source, properties]
----
Expand All @@ -187,7 +210,7 @@ dbms.cluster.endpoints=server01.example.com:6000,server02.example.com:6000,serve
initial.server.mode_constraint=SECONDARY
server.cluster.system_database_mode=SECONDARY
----

+
._neo4j.conf_ on server03.example.com - an analytics server:
[source, properties]
----
Expand All @@ -198,35 +221,35 @@ initial.server.mode_constraint=SECONDARY
server.cluster.system_database_mode=SECONDARY
----

The Neo4j servers are ready to be started.
. The Neo4j servers are ready to be started.
The startup order does not matter.

After the cluster has started, it is possible to connect to any of the instances and run `SHOW SERVERS` to check the status of the cluster.
. After the cluster has started, it is possible to connect to any of the instances and run `SHOW SERVERS` to check the status of the cluster.
This shows information about each member of the cluster:

+
[source, cypher, role=noplay]
----
SHOW SERVERS;
----

+
[queryresult]
----
+-----------------------------------------------------------------------------------------------------------+
| name | address | state | health | hosting |
+-----------------------------------------------------------------------------------------------------------+
+----------------------------------------------------------------------------------------------------------+
| name | address | state | health | hosting |
+----------------------------------------------------------------------------------------------------------+
| "d6fbe54b-0c6a-4959-9bcb-dcbbe80262a4" | "server01:7687" | "Enabled" | "Available" | ["system", "neo4j"] |
| "e56b49ea-243f-11ed-861d-0242ac120002" | "server02:7687" | "Free" | "Available" | ["system"] |
| "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "server03:7687" | "Free" | "Available" | ["system"] |
+-----------------------------------------------------------------------------------------------------------+
+----------------------------------------------------------------------------------------------------------+
----

+
For more extensive information about each server, use the `SHOW SERVERS YIELD *` command:

+
[source, cypher, role=noplay]
----
SHOW SERVERS YIELD *;
----

+
[queryresult]
----
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
Expand All @@ -238,6 +261,29 @@ SHOW SERVERS YIELD *;
+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
----

. To support analytic queries on the secondary servers, you need to explicitly enable them by running:
+
[source, cypher, role=noplay]
----
ENABLE SERVER "e56b49ea-243f-11ed-861d-0242ac120002";
ENABLE SERVER "73e9a990-0a97-4a09-91e9-622bf0b239a4";
----
+
To check the result, run `SHOW SERVERS`.
The output should show:
+
[queryresult]
----
+----------------------------------------------------------------------------------------------------------+
| name | address | state | health | hosting |
+----------------------------------------------------------------------------------------------------------+
| "d6fbe54b-0c6a-4959-9bcb-dcbbe80262a4" | "server01:7687" | "Enabled" | "Available" | ["system", "neo4j"] |
| "e56b49ea-243f-11ed-861d-0242ac120002" | "server02:7687" | "Enabled" | "Available" | ["system"] |
| "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "server03:7687" | "Enabled" | "Available" | ["system"] |
+----------------------------------------------------------------------------------------------------------+
----



[[cluster-example-create-databases-on-single-primary-cluster]]
=== Create new databases in the cluster
Expand Down
Loading