From 3e4c8a374d5d992ce4ad45a5ef5ac6bb421d2015 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Wed, 8 Oct 2025 09:32:31 +0200 Subject: [PATCH 1/2] Clarify when and how to enable new servers (#2623) - To document a missing step in the guide on how to deploy an analytics cluster: you have to enable servers that are in the free state. - To clarify the use and meaning of the initial settings when you deploy a cluster for the first time. - To add information about the setting, allowing automatic enabling of free servers, to the section on the `ENABLED` state of servers. --------- Co-authored-by: Nick Giles <100630647+nick-giles-neo@users.noreply.github.com> --- .../multi-data-center-routing.adoc | 2 +- modules/ROOT/pages/clustering/servers.adoc | 36 +++- .../clustering/setup/analytics-cluster.adoc | 203 +++++++++++++----- .../ROOT/pages/clustering/setup/deploy.adoc | 88 ++++++-- .../configuration/configuration-settings.adoc | 2 +- 5 files changed, 252 insertions(+), 79 deletions(-) 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 c4acd1420..5ecef37b4 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 @@ -58,7 +58,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 70f371471..6ed0ad52e 100644 --- a/modules/ROOT/pages/clustering/servers.adoc +++ b/modules/ROOT/pages/clustering/servers.adoc @@ -35,8 +35,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. @@ -71,11 +82,30 @@ label:new[Introduced in 5.6] [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 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. +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 0df4450c8..265da2508 100644 --- a/modules/ROOT/pages/clustering/setup/analytics-cluster.adoc +++ b/modules/ROOT/pages/clustering/setup/analytics-cluster.adoc @@ -34,7 +34,7 @@ They are configured by preparing xref:configuration/file-locations.adoc[_neo4j.c 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`. To use the discovery service v2: @@ -42,6 +42,8 @@ To use the discovery service v2: * You have to set the configuration of `dbms.cluster.discovery.version` to `V2_ONLY`. * Instead of `dbms.cluster.discovery.endpoints`, use `dbms.cluster.discovery.v2.endpoints`. +. Prepare a _neo4j.conf_ file for each server. ++ ._neo4j.conf_ on server01.example.com: [source, properties] ---- @@ -50,7 +52,7 @@ server.default_advertised_address=server01.example.com dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000,server04.example.com:6000,server05.example.com:6000 dbms.cluster.discovery.version=V2_ONLY ---- - ++ ._neo4j.conf_ on server02.example.com: [source, properties] ---- @@ -59,7 +61,7 @@ server.default_advertised_address=server02.example.com dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000,server04.example.com:6000,server05.example.com:6000 dbms.cluster.discovery.version=V2_ONLY ---- - ++ ._neo4j.conf_ on server03.example.com: [source, properties] ---- @@ -68,7 +70,7 @@ server.default_advertised_address=server03.example.com dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.com:6000,server03.example.com:6000,server04.example.com:6000,server05.example.com:6000 dbms.cluster.discovery.version=V2_ONLY ---- - ++ ._neo4j.conf_ on server04.example.com - an analytics server: [source, properties] ---- @@ -79,7 +81,7 @@ dbms.cluster.discovery.version=V2_ONLY initial.server.mode_constraint=SECONDARY server.cluster.system_database_mode=SECONDARY ---- - ++ ._neo4j.conf_ on server05.example.com - an analytics server: [source, properties] ---- @@ -91,37 +93,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] ---- +-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -135,6 +137,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"] | ++----------------------------------------------------------------------------------------------------------+ +---- + ====== [role=include-with-Discovery-service-v1 label--deprecated-5.23] ====== @@ -150,6 +176,8 @@ Key points: * The servers for analytics have mode constraints configured that restrict their hosting mode to _secondary_ to prevent them from participating in normal write operations. * In the example below, you set `dbms.cluster.discovery.resolver_type=LIST`. +. Prepare a _neo4j.conf_ file for each server. ++ ._neo4j.conf_ on server01.example.com: [source, properties] ---- @@ -157,7 +185,7 @@ server.default_listen_address=0.0.0.0 server.default_advertised_address=server01.example.com dbms.cluster.discovery.endpoints=server01.example.com:5000,server02.example.com:5000,server03.example.com:5000,server04.example.com:5000,server05.example.com:5000 ---- - ++ ._neo4j.conf_ on server02.example.com: [source, properties] ---- @@ -165,7 +193,7 @@ server.default_listen_address=0.0.0.0 server.default_advertised_address=server02.example.com dbms.cluster.discovery.endpoints=server01.example.com:5000,server02.example.com:5000,server03.example.com:5000,server04.example.com:5000,server05.example.com:5000 ---- - ++ ._neo4j.conf_ on server03.example.com: [source, properties] ---- @@ -173,7 +201,7 @@ server.default_listen_address=0.0.0.0 server.default_advertised_address=server03.example.com dbms.cluster.discovery.endpoints=server01.example.com:5000,server02.example.com:5000,server03.example.com:5000,server04.example.com:5000,server05.example.com:5000 ---- - ++ ._neo4j.conf_ on server04.example.com - an analytics server: [source, properties] ---- @@ -183,7 +211,7 @@ dbms.cluster.discovery.endpoints=server01.example.com:5000,server02.example.com: initial.server.mode_constraint=SECONDARY server.cluster.system_database_mode=SECONDARY ---- - ++ ._neo4j.conf_ on server05.example.com - an analytics server: [source, properties] ---- @@ -194,17 +222,17 @@ 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] ---- +-----------------------------------------------------------------------------------------------------------+ @@ -217,14 +245,14 @@ SHOW SERVERS; | "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] ---- +-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -237,6 +265,30 @@ SHOW SERVERS YIELD *; | "9207bfd9-aa1b-40c2-b965-edcd3955a20e" | "9207bfd9-aa1b-40c2-b965-edcd3955a20e" | "server05:7687" | "Free" | "Available" | ["system"] | [] | [] | [] | [] | "SECONDARY" | "5.8.0" | +-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ---- + +. 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"] | ++----------------------------------------------------------------------------------------------------------+ +---- ====== ===== @@ -282,6 +334,7 @@ The following example shows how to set up a non-fault tolerant analytics cluster ===== [role=include-with-Discovery-service-v2 label--new-5.23] ====== + 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. @@ -293,7 +346,7 @@ 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`. To use the discovery service v2: @@ -301,6 +354,8 @@ To use the discovery service v2: * You have to set the configuration of `dbms.cluster.discovery.version` to `V2_ONLY`. * Instead of `dbms.cluster.discovery.endpoints`, use `dbms.cluster.discovery.v2.endpoints`. +. Prepare a _neo4j.conf_ file for each server. ++ ._neo4j.conf_ on server01.example.com - the writer: [source, properties] ---- @@ -310,7 +365,7 @@ server.default_advertised_address=server01.example.com dbms.cluster.discovery.v2.endpoints=server01.example.com:6000 dbms.cluster.discovery.version=V2_ONLY ---- - ++ ._neo4j.conf_ on server02.example.com - an analytics server: [source, properties] ---- @@ -321,7 +376,7 @@ dbms.cluster.discovery.version=V2_ONLY initial.server.mode_constraint=SECONDARY server.cluster.system_database_mode=SECONDARY ---- - ++ ._neo4j.conf_ on server03.example.com - an analytics server: [source, properties] ---- @@ -333,17 +388,17 @@ 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] ---- +-----------------------------------------------------------------------------------------------------------+ @@ -354,14 +409,14 @@ SHOW SERVERS; | "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] ---- +-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -372,6 +427,29 @@ SHOW SERVERS YIELD *; | "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "73e9a990-0a97-4a09-91e9-622bf0b239a4" | "server03:7687" | "Free" | "Available" | ["system"] | ["system"] | [] | [] | [] | "SECONDARY" | "5.8.0" | +-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ ---- + +. 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"] | ++----------------------------------------------------------------------------------------------------------+ +---- + ====== [role=include-with-Discovery-service-v1 label--deprecated-5.23] ====== @@ -390,7 +468,8 @@ This is required in order to have a cluster with only a single primary for the ` * The servers for analytics have mode constraints configured that restrict their hosting mode to _secondary_ to prevent them from participating in normal write operations. * In the example below, you set `dbms.cluster.discovery.resolver_type=LIST`. - +. Prepare a _neo4j.conf_ file for each server. ++ ._neo4j.conf_ on server01.example.com - the writer: [source, properties] ---- @@ -399,7 +478,7 @@ server.default_advertised_address=server01.example.com # Only has self in this list dbms.cluster.discovery.endpoints=server01.example.com:5000 ---- - ++ ._neo4j.conf_ on server02.example.com - an analytics server: [source, properties] ---- @@ -409,7 +488,7 @@ dbms.cluster.discovery.endpoints=server01.example.com:5000,server02.example.com: initial.server.mode_constraint=SECONDARY server.cluster.system_database_mode=SECONDARY ---- - ++ ._neo4j.conf_ on server03.example.com - an analytics server: [source, properties] ---- @@ -420,35 +499,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] ---- +-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -460,9 +539,31 @@ 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 deca442ec..f9e67286f 100644 --- a/modules/ROOT/pages/clustering/setup/deploy.adoc +++ b/modules/ROOT/pages/clustering/setup/deploy.adoc @@ -17,7 +17,7 @@ For more details, see xref:clustering/setup/discovery.adoc[]. .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. @@ -35,21 +35,44 @@ The setting configures the endpoints for **discovery service v2**. The setting must be set to the same value on all cluster members. 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`] +| 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. +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. +The setting is used as the default input for the `ENABLE SERVER` command; can be overriden when the command is executed. |=== -[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 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. -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] @@ -69,7 +92,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 primary mode [.tabbed-example] ===== @@ -89,7 +112,11 @@ To use discovery service v2: * Instead of `dbms.cluster.discovery.endpoints`, use `dbms.cluster.discovery.v2.endpoints`. +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 a _neo4j.conf_ files on each server. ++ ._neo4j.conf_ on server01.example.com: [source, properties] ---- @@ -99,7 +126,7 @@ dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.c dbms.cluster.discovery.version=V2_ONLY initial.dbms.default_primaries_count=3 ---- - ++ ._neo4j.conf_ on server02.example.com: [source, properties] ---- @@ -109,7 +136,7 @@ dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.c dbms.cluster.discovery.version=V2_ONLY initial.dbms.default_primaries_count=3 ---- - ++ ._neo4j.conf_ on server03.example.com: [source, properties] ---- @@ -119,18 +146,18 @@ dbms.cluster.discovery.v2.endpoints=server01.example.com:6000,server02.example.c dbms.cluster.discovery.version=V2_ONLY 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] ---- +-----------------------------------------------------------------------------------------------------------+ @@ -141,14 +168,23 @@ 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. -For more extensive information about each server, use the `SHOW SERVERS YIELD *` command: +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] ---- SHOW SERVERS YIELD *; ---- - ++ [queryresult] ---- +-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ @@ -174,7 +210,10 @@ If you want to follow along with the startup, you can see the messages in xref:c 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 they are all identical, except for the configuration of `server.default_advertised_address`: +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 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. ._neo4j.conf_ on server01.example.com: [source, properties] @@ -225,6 +264,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] @@ -253,12 +301,6 @@ If you want to follow along with the startup, you can see the messages in xref:c ====== ===== -[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 diff --git a/modules/ROOT/pages/configuration/configuration-settings.adoc b/modules/ROOT/pages/configuration/configuration-settings.adoc index 72f5a285f..af9b64956 100644 --- a/modules/ROOT/pages/configuration/configuration-settings.adoc +++ b/modules/ROOT/pages/configuration/configuration-settings.adoc @@ -945,7 +945,7 @@ m|+++NONE+++ [role=label--enterprise-edition] -[[config_server.tags]] +[[config_initial.server.tags]] === `initial.server.tags` .initial.server.tags From 24f47cc501a59f15e2a5cd4101b1e72e7b67c875 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Thu, 9 Oct 2025 08:12:59 +0200 Subject: [PATCH 2/2] 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 f9e67286f..5ff5cba09 100644 --- a/modules/ROOT/pages/clustering/setup/deploy.adoc +++ b/modules/ROOT/pages/clustering/setup/deploy.adoc @@ -115,7 +115,7 @@ To use discovery service v2: 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 a _neo4j.conf_ files on each server. +. Prepare a _neo4j.conf_ file on each server. + ._neo4j.conf_ on server01.example.com: [source, properties]