From 53c3c3d0549c35208c885662b9e666001c645d54 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina Date: Thu, 2 Oct 2025 14:56:37 +0200 Subject: [PATCH 1/3] Document the unbind-system-db command and add details about the system db in cluster --- modules/ROOT/content-nav.adoc | 1 + modules/ROOT/pages/clustering/databases.adoc | 17 ++++ .../clustering/unbind-system-database.adoc | 77 +++++++++++++++++++ .../pages/database-administration/index.adoc | 2 + modules/ROOT/pages/neo4j-admin-neo4j-cli.adoc | 1 + 5 files changed, 98 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 2da657536..d1cba9d0b 100644 --- a/modules/ROOT/content-nav.adoc +++ b/modules/ROOT/content-nav.adoc @@ -160,6 +160,7 @@ ** xref:clustering/servers.adoc[] ** xref:clustering/unbind.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 a43385a2e..5bfde362b 100644 --- a/modules/ROOT/pages/clustering/databases.adoc +++ b/modules/ROOT/pages/clustering/databases.adoc @@ -9,6 +9,23 @@ To specify the initial topology, use the command `CREATE DATABASE`. To change the topology once the database is created, run the `ALTER DATABASE` command. 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#make-the-system-database-write-available[Disaster recovery guide -> Make the `system` database write-available]. + + + [[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..03daa26da --- /dev/null +++ b/modules/ROOT/pages/clustering/unbind-system-database.adoc @@ -0,0 +1,77 @@ +: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. + +[[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. + +This command should be run on all remaining members on a cluster to work as expected. Furthermore, the Neo4j process must be shut down before the command is issued. +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]. + +This does not affect the other databases cluster state. +However, since all servers in the DBMS need to be shut down when the command is issued, downtime is expected for all databases inside of the DBMS. + diff --git a/modules/ROOT/pages/database-administration/index.adoc b/modules/ROOT/pages/database-administration/index.adoc index 5bc75d7c0..0418a0e89 100644 --- a/modules/ROOT/pages/database-administration/index.adoc +++ b/modules/ROOT/pages/database-administration/index.adoc @@ -83,6 +83,8 @@ image::manage-dbs-community.svg[title="A default Neo4j installation.",role=popup .An installation of Neo4j with multiple active databases, named `marketing`, `sales`, and `hr`: image::manage-dbs-enterprise.svg[title="A multiple database Neo4j installation.",role=popup] +For details about the `system` database in a clustered environment, refer to the 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/neo4j-admin-neo4j-cli.adoc b/modules/ROOT/pages/neo4j-admin-neo4j-cli.adoc index 66c8ac046..1e907468b 100644 --- a/modules/ROOT/pages/neo4j-admin-neo4j-cli.adoc +++ b/modules/ROOT/pages/neo4j-admin-neo4j-cli.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 bcb159ffbbe0550c8cb91223ed40b29097ef3616 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Mon, 6 Oct 2025 08:48:56 +0200 Subject: [PATCH 2/3] Apply suggestions from code review --- modules/ROOT/pages/clustering/databases.adoc | 2 +- modules/ROOT/pages/clustering/unbind-system-database.adoc | 8 +++++++- 2 files changed, 8 insertions(+), 2 deletions(-) diff --git a/modules/ROOT/pages/clustering/databases.adoc b/modules/ROOT/pages/clustering/databases.adoc index 5bfde362b..e5f64535c 100644 --- a/modules/ROOT/pages/clustering/databases.adoc +++ b/modules/ROOT/pages/clustering/databases.adoc @@ -22,7 +22,7 @@ Deploying a cluster for the first time, consider configuring the xref:configurat 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#make-the-system-database-write-available[Disaster recovery guide -> Make the `system` database write-available]. +For information on how to recover the `system` database, refer to the xref:clustering/multi-region-deployment/disaster-recovery.adoc[Disaster recovery guide]. diff --git a/modules/ROOT/pages/clustering/unbind-system-database.adoc b/modules/ROOT/pages/clustering/unbind-system-database.adoc index 03daa26da..4d2a60174 100644 --- a/modules/ROOT/pages/clustering/unbind-system-database.adoc +++ b/modules/ROOT/pages/clustering/unbind-system-database.adoc @@ -5,6 +5,11 @@ 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 @@ -69,7 +74,8 @@ The Neo4j process must be shut down on all servers before running the `neo4j-adm 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. -This command should be run on all remaining members on a cluster to work as expected. Furthermore, the Neo4j process must be shut down before the command is issued. +This command should be run on all remaining members of a cluster to work as expected. +Furthermore, the Neo4j process must be shut down on all remaining servers at the same time before the command is issued. 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]. This does not affect the other databases cluster state. From 375166b6392db28ba09fdafaacdae7f1cee27a6b Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 7 Oct 2025 12:47:29 +0200 Subject: [PATCH 3/3] Apply suggestions from code review Co-authored-by: Reneta Popova --- modules/ROOT/pages/clustering/unbind-system-database.adoc | 7 +++---- modules/ROOT/pages/database-administration/index.adoc | 2 +- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/clustering/unbind-system-database.adoc b/modules/ROOT/pages/clustering/unbind-system-database.adoc index 4d2a60174..12b6a12ae 100644 --- a/modules/ROOT/pages/clustering/unbind-system-database.adoc +++ b/modules/ROOT/pages/clustering/unbind-system-database.adoc @@ -74,10 +74,9 @@ The Neo4j process must be shut down on all servers before running the `neo4j-adm 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. -This command should be run on all remaining members of a cluster to work as expected. -Furthermore, the Neo4j process must be shut down on all remaining servers at the same time before the command is issued. +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]. -This does not affect the other databases cluster state. -However, since all servers in the DBMS need to be shut down when the command is issued, downtime is expected for all databases inside of the DBMS. +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 0418a0e89..d36b16ecd 100644 --- a/modules/ROOT/pages/database-administration/index.adoc +++ b/modules/ROOT/pages/database-administration/index.adoc @@ -83,7 +83,7 @@ image::manage-dbs-community.svg[title="A default Neo4j installation.",role=popup .An installation of Neo4j with multiple active databases, named `marketing`, `sales`, and `hr`: image::manage-dbs-enterprise.svg[title="A multiple database Neo4j installation.",role=popup] -For details about the `system` database in a clustered environment, refer to the xref:clustering/databases.adoc#cluster-system-db[Managing databases in a cluster -> The `system` database]. +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