From bbca5558c029a836b1e7215b176c8ec49db113f7 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina Date: Mon, 29 Sep 2025 13:20:46 +0200 Subject: [PATCH 1/9] Clarify situation when enabling newly added servers --- .../pages/changes-deprecations-removals.adoc | 2 +- .../multi-data-center-routing.adoc | 2 +- modules/ROOT/pages/clustering/servers.adoc | 28 +++- .../clustering/setup/analytics-cluster.adoc | 130 ++++++++++++------ .../ROOT/pages/clustering/setup/deploy.adoc | 40 +++++- .../configuration/configuration-settings.adoc | 2 +- 6 files changed, 149 insertions(+), 55 deletions(-) diff --git a/modules/ROOT/pages/changes-deprecations-removals.adoc b/modules/ROOT/pages/changes-deprecations-removals.adoc index 6bc5c9a32..678d11996 100644 --- a/modules/ROOT/pages/changes-deprecations-removals.adoc +++ b/modules/ROOT/pages/changes-deprecations-removals.adoc @@ -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. diff --git a/modules/ROOT/pages/clustering/multi-region-deployment/multi-data-center-routing.adoc b/modules/ROOT/pages/clustering/multi-region-deployment/multi-data-center-routing.adoc index 0fe725a1c..d091f2e5b 100644 --- a/modules/ROOT/pages/clustering/multi-region-deployment/multi-data-center-routing.adoc +++ b/modules/ROOT/pages/clustering/multi-region-deployment/multi-data-center-routing.adoc @@ -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. diff --git a/modules/ROOT/pages/clustering/servers.adoc b/modules/ROOT/pages/clustering/servers.adoc index d9677252b..604df0cf5 100644 --- a/modules/ROOT/pages/clustering/servers.adoc +++ b/modules/ROOT/pages/clustering/servers.adoc @@ -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, all 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. @@ -72,11 +83,22 @@ 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 not 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 on the first startup of the DBMS. ==== +Another option to enable a server is to set xref:configuration/configuration-settings.adoc#config_initial.dbms.automatically_enable_free_servers[`initial.dbms.automatically_enable_free_servers`] to `true`. + Once enabled, the server may be allocated databases to host. +If you need to change some of the server's values, use the <> command. + [[deallocating-state]] diff --git a/modules/ROOT/pages/clustering/setup/analytics-cluster.adoc b/modules/ROOT/pages/clustering/setup/analytics-cluster.adoc index 5ca1ba35d..26f4adfb2 100644 --- a/modules/ROOT/pages/clustering/setup/analytics-cluster.adoc +++ b/modules/ROOT/pages/clustering/setup/analytics-cluster.adoc @@ -16,20 +16,19 @@ 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] ---- @@ -37,7 +36,7 @@ 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] ---- @@ -45,7 +44,7 @@ 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] ---- @@ -53,7 +52,7 @@ 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] ---- @@ -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] ---- @@ -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] ---- +-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -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 @@ -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] ---- @@ -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] ---- @@ -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] ---- @@ -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] ---- +-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -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 diff --git a/modules/ROOT/pages/clustering/setup/deploy.adoc b/modules/ROOT/pages/clustering/setup/deploy.adoc index 56afb6264..da9fa55ca 100644 --- a/modules/ROOT/pages/clustering/setup/deploy.adoc +++ b/modules/ROOT/pages/clustering/setup/deploy.adoc @@ -12,7 +12,7 @@ See also xref:clustering/settings.adoc[Settings reference] for more detailed des .Important settings for clusters [options="header",cols="<3,<4"] |=== -| Option name +| Setting name | Description | xref:configuration/configuration-settings.adoc#config_server.default_advertised_address[`server.default_advertised_address`] | The address that other machines are told to connect to. @@ -24,21 +24,38 @@ Setting this value to `0.0.0.0` makes Neo4j bind to all available network interf | A comma-separated list of endpoints that a server should contact in order to discover other cluster members. Typically, all cluster members, including the current server, must be specified in this list. The behavior of this setting can be modified by configuring the setting `dbms.cluster.discovery.resolver_type`. This is described in detail in xref:clustering/setup/discovery.adoc[]. +| xref:configuration/configuration-settings.adoc#config_dbms.cluster.minimum_initial_system_primaries_count[`dbms.cluster.minimum_initial_system_primaries_count`] +| Minimum number of machines initially required to form a clustered DBMS. +The cluster is considered formed when at least this many members have discovered each other, bound together, and bootstrapped a highly available `system` database. +The default value is `3`. +As a result, at least this many of the cluster's initial machines must have xref:configuration/configuration-settings.adoc#config_server.cluster.system_database_mode[`server.cluster.system_database_mode`] set to `PRIMARY`. +|xref:configuration/configuration-settings.adoc#config_server.cluster.system_database_mode[`server.cluster.system_database_mode`] +| Users must manually specify the mode for the `system` database on each server. +The default value is `PRIMARY`. | xref:configuration/configuration-settings.adoc#config_initial.dbms.default_primaries_count[`initial.dbms.default_primaries_count`] | The number of initial database hostings in primary mode. If not specified, it defaults to one hosting in primary mode. | xref:configuration/configuration-settings.adoc#config_initial.dbms.default_secondaries_count[`initial.dbms.default_secondaries_count`] | The number of initial database hostings in secondary mode. If not specified, it defaults to zero hostings in secondary mode. +| 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`] +| +|xref:configuration/configuration-settings.adoc#config_initial.server.tags[`initial.server.tags`] +| |=== -[NOTE] -==== -Any setting with the `initial` prefix is only effective on the first startup of the DBMS. -Changing the default number of primaries and secondaries dynamically can only be done with the xref:procedures.adoc#procedure_dbms_setDefaultAllocationNumbers[`dbms.setDefaultAllocationNumbers`] procedure. +Points to consider: + +* Any setting with the `initial` prefix is only effective on the first startup of the DBMS, except for `initial.dbms.automatically_enable_free_servers`. + +* Changing the default number of primaries and secondaries dynamically can only be done with the xref:procedures.adoc#procedure_dbms_setDefaultAllocationNumbers[`dbms.setDefaultAllocationNumbers`] procedure. See xref:clustering/databases.adoc#create-database[`CREATE DATABASE`] for more information. -To view the current default settings, use the xref:procedures.adoc#procedure_dbms_showTopologyGraphConfig[`dbms.showTopologyGraphConfig`] procedure. -==== + +* To view the current default settings, use the xref:procedures.adoc#procedure_dbms_showTopologyGraphConfig[`dbms.showTopologyGraphConfig`] procedure. [CAUTION] @@ -116,6 +133,15 @@ SHOW SERVERS; +-----------------------------------------------------------------------------------------------------------+ ---- +[NOTE] +==== +Note that initialized servers are `ENABLED` automatically at the first DBMS startup. + +Their values are taken from the initial settings. + +If you need to change the server's options, use the xref:clustering/servers.adoc#alter-server-options[`ALTER SERVER`] command. +==== + For more extensive information about each server, use the `SHOW SERVERS YIELD *` command: [source, cypher, role=noplay] diff --git a/modules/ROOT/pages/configuration/configuration-settings.adoc b/modules/ROOT/pages/configuration/configuration-settings.adoc index 0c2e1a1ed..49648ad41 100644 --- a/modules/ROOT/pages/configuration/configuration-settings.adoc +++ b/modules/ROOT/pages/configuration/configuration-settings.adoc @@ -866,7 +866,7 @@ m|+++NONE+++ [role=label--enterprise-edition] -[[config_server.tags]] +[[config_initial.server.tags]] === `initial.server.tags` .initial.server.tags From 0bb80588a2738c01a1f774db358ef0bb9107a0f5 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Mon, 29 Sep 2025 17:10:07 +0200 Subject: [PATCH 2/9] Add info about initial setting to the Deploy cluster page --- modules/ROOT/pages/clustering/setup/deploy.adoc | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/clustering/setup/deploy.adoc b/modules/ROOT/pages/clustering/setup/deploy.adoc index da9fa55ca..5f5cb32a4 100644 --- a/modules/ROOT/pages/clustering/setup/deploy.adoc +++ b/modules/ROOT/pages/clustering/setup/deploy.adoc @@ -39,18 +39,22 @@ If not specified, it defaults to one hosting in primary mode. | The number of initial database hostings in secondary mode. If not specified, it defaults to zero hostings in secondary mode. | xref:configuration/configuration-settings.adoc#config_initial.server.mode_constraint[`initial.server.mode_constraint`] -| +| Specifies the server mode - whether it can host only primary databases, only secondary databases, or both types. +Initialized at the first DBMS startup. +When a new server is added to the cluster, the setting is used as the default input for the `ENABLE SERVER` command; can be overriden when the command is executed. |xref:configuration/configuration-settings.adoc#config_initial.server.allowed_databases[`initial.server.allowed_databases`] -| +|List of database names allowed on this server; all others are denied. |xref:configuration/configuration-settings.adoc#config_initial.server.denied_databases[`initial.server.denied_databases`] -| +|List of database names not allowed on this server. Empty means nothing is denied. |xref:configuration/configuration-settings.adoc#config_initial.server.tags[`initial.server.tags`] -| +|A list of server tag names used by the database allocation and when configuring load balancing and replication policies. +Initialized at the first DBMS startup and/or when a newly added server is enabled. +The setting is used as the default input for the `ENABLE SERVER` command; can be overriden when the command is executed. |=== Points to consider: -* Any setting with the `initial` prefix is only effective on the first startup of the DBMS, except for `initial.dbms.automatically_enable_free_servers`. +* Any setting with the `initial` prefix is effective on the first startup of the DBMS and/or when a new server is added to the cluster and has to be explixitly xref:clustering/servers.adoc#server-enabled-state[`ENABLED`]. * Changing the default number of primaries and secondaries dynamically can only be done with the xref:procedures.adoc#procedure_dbms_setDefaultAllocationNumbers[`dbms.setDefaultAllocationNumbers`] procedure. See xref:clustering/databases.adoc#create-database[`CREATE DATABASE`] for more information. From 88bb436e7adfe9f15ce52543b67e56af8ba7b3c2 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Mon, 29 Sep 2025 17:28:09 +0200 Subject: [PATCH 3/9] Update deploy.adoc --- modules/ROOT/pages/clustering/setup/deploy.adoc | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/modules/ROOT/pages/clustering/setup/deploy.adoc b/modules/ROOT/pages/clustering/setup/deploy.adoc index 5f5cb32a4..e15f99a42 100644 --- a/modules/ROOT/pages/clustering/setup/deploy.adoc +++ b/modules/ROOT/pages/clustering/setup/deploy.adoc @@ -87,6 +87,8 @@ They are configured by preparing xref:configuration/file-locations.adoc[_neo4j.c Note that they are all identical, except for the configuration of `server.default_advertised_address`. +Besides, in the example below, the `dbms.cluster.minimum_initial_system_primaries_count` setting is not configured as it defaults to three, and we deploy a cluster of three servers. +However in case of setting up a cluster with only *two* servers, the setting `dbms.cluster.minimum_initial_system_primaries_count` must be set to `2` on all servers . ._neo4j.conf_ on server01.example.com: [source, properties] @@ -171,12 +173,6 @@ The instance may appear unavailable while it is joining the cluster. If you want to follow along with the startup, you can see the messages in xref:configuration/file-locations.adoc[_neo4j.log_]. ==== -[CAUTION] -==== -The setting -xref:configuration/configuration-settings.adoc#config_dbms.cluster.minimum_initial_system_primaries_count[`dbms.cluster.minimum_initial_system_primaries_count`] -must be set to `2` on all servers in case setting up a cluster with only *two* servers. -==== [[cluster-example-create-databases-on-cluster]] == Create new databases in a cluster From 5e9dd8bb77bc95ec621620f1591585fa123ad8ff Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Thu, 2 Oct 2025 09:43:24 +0200 Subject: [PATCH 4/9] Update modules/ROOT/pages/clustering/setup/deploy.adoc --- modules/ROOT/pages/clustering/setup/deploy.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/deploy.adoc b/modules/ROOT/pages/clustering/setup/deploy.adoc index e15f99a42..6ca6de4d6 100644 --- a/modules/ROOT/pages/clustering/setup/deploy.adoc +++ b/modules/ROOT/pages/clustering/setup/deploy.adoc @@ -54,7 +54,7 @@ The setting is used as the default input for the `ENABLE SERVER` command; can be Points to consider: -* Any setting with the `initial` prefix is effective on the first startup of the DBMS and/or when a new server is added to the cluster and has to be explixitly xref:clustering/servers.adoc#server-enabled-state[`ENABLED`]. +* Any setting with the `initial` prefix is effective on the first startup of the DBMS and/or when a new server is added to the cluster and has to be explicitly xref:clustering/servers.adoc#server-enabled-state[`ENABLED`]. * Changing the default number of primaries and secondaries dynamically can only be done with the xref:procedures.adoc#procedure_dbms_setDefaultAllocationNumbers[`dbms.setDefaultAllocationNumbers`] procedure. See xref:clustering/databases.adoc#create-database[`CREATE DATABASE`] for more information. From d74c5896551d59436cad28c0f8188bef160b7610 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Fri, 3 Oct 2025 14:36:14 +0200 Subject: [PATCH 5/9] Apply suggestions from code review Co-authored-by: Nick Giles <100630647+nick-giles-neo@users.noreply.github.com> --- modules/ROOT/pages/clustering/servers.adoc | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/modules/ROOT/pages/clustering/servers.adoc b/modules/ROOT/pages/clustering/servers.adoc index 604df0cf5..bf7ccead8 100644 --- a/modules/ROOT/pages/clustering/servers.adoc +++ b/modules/ROOT/pages/clustering/servers.adoc @@ -37,7 +37,7 @@ When first discovered, a server's name defaults to the value of its generated se [[server-enabled-state]] === Enabled state -When you deploy a cluster for the first time, all servers included in the initial deployment are automatically enabled. +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. @@ -83,17 +83,18 @@ This may not be specified in combination with `allowedDatabases`. [NOTE] ==== -When a server is enabled, if no `OPTIONS` are not provided, the default server's values are taken from the settings: +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 on the first startup of the DBMS. +All these settings are only effective when enabling the relevant server. ==== -Another option to enable a server is to set xref:configuration/configuration-settings.adoc#config_initial.dbms.automatically_enable_free_servers[`initial.dbms.automatically_enable_free_servers`] to `true`. +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. From 8766dffe359b82a710682ccd92853ae2bba7c9b8 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Mon, 6 Oct 2025 09:29:57 +0200 Subject: [PATCH 6/9] Update deploy.adoc --- modules/ROOT/pages/clustering/setup/deploy.adoc | 2 ++ 1 file changed, 2 insertions(+) diff --git a/modules/ROOT/pages/clustering/setup/deploy.adoc b/modules/ROOT/pages/clustering/setup/deploy.adoc index 6ca6de4d6..4ff1dbcf1 100644 --- a/modules/ROOT/pages/clustering/setup/deploy.adoc +++ b/modules/ROOT/pages/clustering/setup/deploy.adoc @@ -44,8 +44,10 @@ Initialized at the first DBMS startup. When a new server is added to the cluster, the setting is used as the default input for the `ENABLE SERVER` command; can be overriden when the command is executed. |xref:configuration/configuration-settings.adoc#config_initial.server.allowed_databases[`initial.server.allowed_databases`] |List of database names allowed on this server; all others are denied. +When a new server is added to the cluster, the setting is used as the default input for the `ENABLE SERVER` command; can be overriden when the command is executed. |xref:configuration/configuration-settings.adoc#config_initial.server.denied_databases[`initial.server.denied_databases`] |List of database names not allowed on this server. Empty means nothing is denied. +When a new server is added to the cluster, the setting is used as the default input for the `ENABLE SERVER` command; can be overriden when the command is executed. |xref:configuration/configuration-settings.adoc#config_initial.server.tags[`initial.server.tags`] |A list of server tag names used by the database allocation and when configuring load balancing and replication policies. Initialized at the first DBMS startup and/or when a newly added server is enabled. From d6abface01cfade6ac8205bfba27d1c04ff3da15 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 7 Oct 2025 10:07:55 +0200 Subject: [PATCH 7/9] Update servers.adoc --- modules/ROOT/pages/clustering/servers.adoc | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/clustering/servers.adoc b/modules/ROOT/pages/clustering/servers.adoc index bf7ccead8..f1e9e7eb1 100644 --- a/modules/ROOT/pages/clustering/servers.adoc +++ b/modules/ROOT/pages/clustering/servers.adoc @@ -93,8 +93,15 @@ When a server is enabled, if no `OPTIONS` are provided, the default server's val 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);`. +Another way to enable servers is to configure the DBMS automatically enable free servers. +You can do this in one of two ways: + +* 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. +* By running the following procedure after deployment: ++ +---- +CALL dbms.cluster.setAutomaticallyEnableFreeServers(true); +---- Once enabled, the server may be allocated databases to host. From 626570752c9cc806a0241e1454e3fa720165d640 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 7 Oct 2025 10:47:41 +0200 Subject: [PATCH 8/9] Update deploy.adoc --- .../ROOT/pages/clustering/setup/deploy.adoc | 30 ++++++++++--------- 1 file changed, 16 insertions(+), 14 deletions(-) diff --git a/modules/ROOT/pages/clustering/setup/deploy.adoc b/modules/ROOT/pages/clustering/setup/deploy.adoc index 4ff1dbcf1..673b9f706 100644 --- a/modules/ROOT/pages/clustering/setup/deploy.adoc +++ b/modules/ROOT/pages/clustering/setup/deploy.adoc @@ -56,7 +56,7 @@ The setting is used as the default input for the `ENABLE SERVER` command; can be Points to consider: -* Any setting with the `initial` prefix is effective on the first startup of the DBMS and/or when a new server is added to the cluster and has to be explicitly xref:clustering/servers.adoc#server-enabled-state[`ENABLED`]. +* Any setting with the `initial` prefix is effective on the first startup of the DBMS and/or when a new server joins the cluster and has to be explicitly xref:clustering/servers.adoc#server-enabled-state[`ENABLED`]. * Changing the default number of primaries and secondaries dynamically can only be done with the xref:procedures.adoc#procedure_dbms_setDefaultAllocationNumbers[`dbms.setDefaultAllocationNumbers`] procedure. See xref:clustering/databases.adoc#create-database[`CREATE DATABASE`] for more information. @@ -81,7 +81,7 @@ Depending on the type of xref:configuration/configuration-settings.adoc#config_d In this case, you set `dbms.cluster.discovery.resolver_type=LIST`. -.Configure a cluster with three servers in primary mode +.Configure a cluster with three servers hosting databases in a primary mode 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. @@ -89,9 +89,11 @@ They are configured by preparing xref:configuration/file-locations.adoc[_neo4j.c Note that they are all identical, except for the configuration of `server.default_advertised_address`. -Besides, in the example below, the `dbms.cluster.minimum_initial_system_primaries_count` setting is not configured as it defaults to three, and we deploy a cluster of three servers. -However in case of setting up a cluster with only *two* servers, the setting `dbms.cluster.minimum_initial_system_primaries_count` must be set to `2` on all servers . +Besides, in the example below, the `dbms.cluster.minimum_initial_system_primaries_count` setting is not configured, as it defaults to three, and a cluster of three servers is being deployed. +However, in case of setting up a cluster with only *two* servers, the setting `dbms.cluster.minimum_initial_system_primaries_count` must be set to `2` on all servers. +. Prepare _neo4j.conf_ files on each server. ++ ._neo4j.conf_ on server01.example.com: [source, properties] ---- @@ -100,7 +102,7 @@ server.default_advertised_address=server01.example.com dbms.cluster.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000 initial.dbms.default_primaries_count=3 ---- - ++ ._neo4j.conf_ on server02.example.com: [source, properties] ---- @@ -109,7 +111,7 @@ server.default_advertised_address=server02.example.com dbms.cluster.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000 initial.dbms.default_primaries_count=3 ---- - ++ ._neo4j.conf_ on server03.example.com: [source, properties] ---- @@ -118,18 +120,18 @@ server.default_advertised_address=server03.example.com dbms.cluster.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000 initial.dbms.default_primaries_count=3 ---- - ++ 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] ---- +-----------------------------------------------------------------------------------------------------------+ @@ -140,7 +142,7 @@ SHOW SERVERS; | "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "server03:7687" | "Enabled" | "Available" | ["system", "neo4j"] | +-----------------------------------------------------------------------------------------------------------+ ---- - ++ [NOTE] ==== Note that initialized servers are `ENABLED` automatically at the first DBMS startup. @@ -150,13 +152,13 @@ Their values are taken from the initial settings. If you need to change the server's options, use the xref:clustering/servers.adoc#alter-server-options[`ALTER SERVER`] command. ==== -For more extensive information about each server, use the `SHOW SERVERS YIELD *` command: - +. For more extensive information about each server, use the `SHOW SERVERS YIELD *` command: ++ [source, cypher, role=noplay] ---- SHOW SERVERS YIELD *; ---- - ++ [queryresult] ---- +-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ From f4b7bfe60b57574080b3b0eb2f8e54d5cfd1fde9 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 7 Oct 2025 10:58:01 +0200 Subject: [PATCH 9/9] Update modules/ROOT/pages/clustering/setup/deploy.adoc --- modules/ROOT/pages/clustering/setup/deploy.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/setup/deploy.adoc b/modules/ROOT/pages/clustering/setup/deploy.adoc index 673b9f706..598b31901 100644 --- a/modules/ROOT/pages/clustering/setup/deploy.adoc +++ b/modules/ROOT/pages/clustering/setup/deploy.adoc @@ -81,7 +81,7 @@ Depending on the type of xref:configuration/configuration-settings.adoc#config_d In this case, you set `dbms.cluster.discovery.resolver_type=LIST`. -.Configure a cluster with three servers hosting databases in a primary mode +.Configure a cluster with three servers hosting databases in primary mode 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.