From 224ecbde2857cfd9f8f936a1ab163fe1956454c2 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 7 Oct 2025 14:06:12 +0200 Subject: [PATCH 1/5] Document the unbind-system-db command and add details about the system db in cluster (#2631) Add a new page covering the `neo4j-admin dbms unbind-system-db` command. Add a section about the `system` database role in a cluster to the page 'Managing databases in a cluster'. This PR should be copied to the 5.x branch with a few adjustments: the label `Introduced in 5.0` should be added. --------- Co-authored-by: Reneta Popova --- modules/ROOT/content-nav.adoc | 1 + modules/ROOT/pages/clustering/databases.adoc | 17 ++++ .../clustering/unbind-system-database.adoc | 82 +++++++++++++++++++ .../pages/database-administration/index.adoc | 2 + .../ROOT/pages/tools/neo4j-admin/index.adoc | 1 + 5 files changed, 103 insertions(+) create mode 100644 modules/ROOT/pages/clustering/unbind-system-database.adoc diff --git a/modules/ROOT/content-nav.adoc b/modules/ROOT/content-nav.adoc index b5102578d..eb46cea17 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -147,6 +147,7 @@ *** xref:clustering/setup/encryption.adoc[] ** xref:clustering/servers.adoc[] ** xref:clustering/databases.adoc[] +** xref:clustering/unbind-system-database.adoc[] ** Monitoring *** xref:clustering/monitoring/show-servers-monitoring.adoc[] *** xref:clustering/monitoring/show-databases-monitoring.adoc[] diff --git a/modules/ROOT/pages/clustering/databases.adoc b/modules/ROOT/pages/clustering/databases.adoc index 491631b4a..1acfd77a4 100644 --- a/modules/ROOT/pages/clustering/databases.adoc +++ b/modules/ROOT/pages/clustering/databases.adoc @@ -8,6 +8,23 @@ The number of both primary and secondary servers to host a database can be set w The command `CREATE DATABASE` can be used to specify the initial topology and `ALTER DATABASE` can be used to change the topology once the database is created. If a database is no longer needed, the command `DROP DATABASE` deletes the database from the cluster. +[[cluster-system-db]] +== The `system` database in a cluster + +The `system` database contains metadata on the DBMS and security configuration. +When connected to this database you can only perform a specific set of administrative tasks, such as managing databases, servers, and access control. + +In the clustered environment, the `system` database can be in a primary or secondary mode. +To configure its mode, use the xref:configuration/configuration-settings.adoc#config_server.cluster.system_database_mode[`server.cluster.system_database_mode`] setting. + +Deploying a cluster for the first time, consider configuring the xref:configuration/configuration-settings.adoc#config_dbms.cluster.minimum_initial_system_primaries_count[`dbms.cluster.minimum_initial_system_primaries_count`]. +This setting defaults to `3`. +See xref:clustering/setup/deploy.adoc[] for details. + +For information on how to recover the `system` database, refer to the xref:clustering/multi-region-deployment/disaster-recovery.adoc[Disaster recovery guide]. + + + [[create-database]] == `CREATE DATABASE` diff --git a/modules/ROOT/pages/clustering/unbind-system-database.adoc b/modules/ROOT/pages/clustering/unbind-system-database.adoc new file mode 100644 index 000000000..12b6a12ae --- /dev/null +++ b/modules/ROOT/pages/clustering/unbind-system-database.adoc @@ -0,0 +1,82 @@ +:description: The page describes the neo4j-admin command `dbms unbind-system-db`. +[role=enterprise-edition] + += Unbind the `system` database + +You can use the `neo4j-admin dbms unbind-system-db` command to remove and archive the cluster state for the `system` database, so that the server can rebind to a new `system` database in the cluster. + +[CAUTION] +==== +Executing the `neo4j-admin dbms unbind-system-db` command does not affect the cluster state of other standard databases. +However, since all servers in the DBMS need to be shut down to run the command, downtime will occur for all databases inside of the DBMS. +==== +[[unbind-system-db-syntax]] +== Syntax + +The `neo4j-admin dbms unbind-system-db` command has the following syntax: + +---- +neo4j-admin dbms unbind-system-db [-h] [--expand-commands] [--verbose] [--archive-cluster-state[=true|false]] + [--additional-config=] [--archive-path=] +---- + + +[[unbind-system-db-description]] +== Description + +Removes and archives cluster state for `system` database. + +[[unbind-system-db-options]] +== Options + + +The `neo4j-admin dbms unbind-system-db` command has the following options: + +.`neo4j-admin dbms unbind-system-db` options +[options="header", cols="5m,6a,2m"] +|=== +| Option +| Description +| Default + +|--additional-config= +|Configuration file with additional configuration. +| + +|--archive-cluster-state[=true\|false] +|Enable or disable the cluster state archiving. +|false + +|--archive-path= +|Destination (file or folder) of the cluster state archive. +| + +|--expand-commands +|Allow command expansion in config value evaluation. +| + +|-h, --help +|Show this help message and exit. +| + +|--verbose +|Enable verbose output. +| +|=== + +[[unbind-system-db-limitations]] +== Limitations + +The Neo4j process must be shut down on all servers before running the `neo4j-admin dbms unbind-system-db` command. + +[[unbind-system-db-usage]] +== Usage + +The `neo4j-admin dbms unbind-system-db` command removes and archives cluster state for the `system` database, so that the server can rebind to a new `system` database in a cluster. + +You must shut down all cluster members before running the command on each of them. +For details, see xref:clustering/multi-region-deployment/disaster-recovery.adoc#make-the-system-database-write-available[Disaster recovery guide -> Make the `system` database write-available]. + +The `neo4j-admin dbms unbind-system-db` command does not affect the cluster state of the standard databases. +However, since all servers in the DBMS must be shut down before the command is issued, downtime is expected for all databases within the DBMS. + diff --git a/modules/ROOT/pages/database-administration/index.adoc b/modules/ROOT/pages/database-administration/index.adoc index fb1de1b8f..20fcc019a 100644 --- a/modules/ROOT/pages/database-administration/index.adoc +++ b/modules/ROOT/pages/database-administration/index.adoc @@ -74,6 +74,8 @@ image::manage-dbs-community.png[title="A default Neo4j installation.", role="mid .An installation of Neo4j with multiple active databases, named `marketing`, `sales`, and `hr`: image::manage-dbs-enterprise.png[title="A multiple database Neo4j installation.", role="middle"] +For details about the `system` database in a clustered environment, refer to xref:clustering/databases.adoc#cluster-system-db[Managing databases in a cluster -> The `system` database]. + == Composite databases A Composite database is a logical grouping of multiple graphs contained in other, standard databases. diff --git a/modules/ROOT/pages/tools/neo4j-admin/index.adoc b/modules/ROOT/pages/tools/neo4j-admin/index.adoc index 974f4e797..367c89eb9 100644 --- a/modules/ROOT/pages/tools/neo4j-admin/index.adoc +++ b/modules/ROOT/pages/tools/neo4j-admin/index.adoc @@ -59,6 +59,7 @@ For details, see xref:configuration/set-initial-password.adoc[Set an initial pas | `unbind-system-db` | Removes and archives the cluster state of the `system` database so the instance can rebind to a new cluster state of the `system` database. +For details, see xref:clustering/unbind-system-database.adoc[]. .13+| `server` From b42cb6f0fdbf6299c633798ef440ed5185d9498e Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 7 Oct 2025 14:23:15 +0200 Subject: [PATCH 2/5] Update modules/ROOT/pages/clustering/unbind-system-database.adoc --- modules/ROOT/pages/clustering/unbind-system-database.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/unbind-system-database.adoc b/modules/ROOT/pages/clustering/unbind-system-database.adoc index 12b6a12ae..29a4059eb 100644 --- a/modules/ROOT/pages/clustering/unbind-system-database.adoc +++ b/modules/ROOT/pages/clustering/unbind-system-database.adoc @@ -1,5 +1,5 @@ :description: The page describes the neo4j-admin command `dbms unbind-system-db`. -[role=enterprise-edition] +[role=enterprise-edition label--new-5.0] = Unbind the `system` database From 648a4de8dc2888c592c46b8c43275ca986220aa5 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 7 Oct 2025 15:58:51 +0200 Subject: [PATCH 3/5] Update index.adoc --- modules/ROOT/pages/clustering/index.adoc | 1 + 1 file changed, 1 insertion(+) diff --git a/modules/ROOT/pages/clustering/index.adoc b/modules/ROOT/pages/clustering/index.adoc index c37b3eddc..c39cf2c44 100644 --- a/modules/ROOT/pages/clustering/index.adoc +++ b/modules/ROOT/pages/clustering/index.adoc @@ -16,6 +16,7 @@ This chapter describes the following: ** xref:clustering/setup/encryption.adoc[Intra-cluster encryption] -- How to secure the cluster communication. * xref:clustering/servers.adoc[Managing servers in a cluster] -- How to manage the servers in a cluster. * xref:clustering/databases.adoc[Managing databases in a cluster] -- How to manage the databases in a cluster. +* xref:clustering/unbind-system-database.adoc[Unbind the `system` database] -- How to use the `neo4j-admin dbms unbind-system-db` command. * Monitoring -- Monitoring of a cluster. ** xref:clustering/monitoring/show-servers-monitoring.adoc[Monitor servers] -- The tools available for monitoring the servers in a cluster. ** xref:clustering/monitoring/show-databases-monitoring.adoc[Monitor databases] -- The tools available for monitoring the databases in a cluster. From 50c62f84e32108bc8d88ff447c180ba93d6352c6 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 7 Oct 2025 16:06:38 +0200 Subject: [PATCH 4/5] Update modules/ROOT/pages/clustering/index.adoc --- modules/ROOT/pages/clustering/index.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/index.adoc b/modules/ROOT/pages/clustering/index.adoc index c39cf2c44..45c4f0df5 100644 --- a/modules/ROOT/pages/clustering/index.adoc +++ b/modules/ROOT/pages/clustering/index.adoc @@ -16,7 +16,7 @@ This chapter describes the following: ** xref:clustering/setup/encryption.adoc[Intra-cluster encryption] -- How to secure the cluster communication. * xref:clustering/servers.adoc[Managing servers in a cluster] -- How to manage the servers in a cluster. * xref:clustering/databases.adoc[Managing databases in a cluster] -- How to manage the databases in a cluster. -* xref:clustering/unbind-system-database.adoc[Unbind the `system` database] -- How to use the `neo4j-admin dbms unbind-system-db` command. +* xref:clustering/unbind-system-database.adoc[Unbind the `system` database] label:new[Introduced in 5.0] -- How to use the `neo4j-admin dbms unbind-system-db` command. * Monitoring -- Monitoring of a cluster. ** xref:clustering/monitoring/show-servers-monitoring.adoc[Monitor servers] -- The tools available for monitoring the servers in a cluster. ** xref:clustering/monitoring/show-databases-monitoring.adoc[Monitor databases] -- The tools available for monitoring the databases in a cluster. From ddf7eb9b05efc72ece72afcd4fcde548610dd2d2 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 7 Oct 2025 17:02:43 +0200 Subject: [PATCH 5/5] Update modules/ROOT/pages/clustering/unbind-system-database.adoc --- modules/ROOT/pages/clustering/unbind-system-database.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/modules/ROOT/pages/clustering/unbind-system-database.adoc b/modules/ROOT/pages/clustering/unbind-system-database.adoc index 29a4059eb..226b44e88 100644 --- a/modules/ROOT/pages/clustering/unbind-system-database.adoc +++ b/modules/ROOT/pages/clustering/unbind-system-database.adoc @@ -1,5 +1,5 @@ :description: The page describes the neo4j-admin command `dbms unbind-system-db`. -[role=enterprise-edition label--new-5.0] +[role=enterprise-edition new-5.0] = Unbind the `system` database