From 2f28a0f0fc86e73232ed45356ee52276670ffc48 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina Date: Mon, 4 Aug 2025 12:24:26 +0200 Subject: [PATCH 1/5] Clarify backup/restore strategy regarding system db --- .../ROOT/pages/backup-restore/planning.adoc | 67 +++++++++++-------- 1 file changed, 38 insertions(+), 29 deletions(-) diff --git a/modules/ROOT/pages/backup-restore/planning.adoc b/modules/ROOT/pages/backup-restore/planning.adoc index 03c03d2f6..f23e98bc7 100644 --- a/modules/ROOT/pages/backup-restore/planning.adoc +++ b/modules/ROOT/pages/backup-restore/planning.adoc @@ -38,7 +38,7 @@ If you have zero tolerance for downtime and data loss, you might want to conside ** use SSL/TLS for the backup network communication (online only). ** keep your databases as archive files (online or offline). * How many backups you want to keep. -* Where the backups will be stored — drive or remote server, cloud storage, different data center, different location, etc. +* Where the backups will be stored — drive or remote server, cloud storage, different data center, different location, etc. + [TIP] ==== @@ -51,15 +51,14 @@ This ensures that if for some reason your Neo4j DBMS crashes, you will be able t == Backup and restore options Neo4j supports backing up and restoring both online and offline databases. -It uses xref:neo4j-admin-neo4j-cli.adoc[Neo4j Admin tool] commands, which can be run from a live, as well as from an offline Neo4j DBMS. +It uses xref:neo4j-admin-neo4j-cli.adoc[Neo4j Admin tool] commands that can be executed on a Neo4j DBMS, whether it is running or offline. All `neo4j-admin` commands must be invoked as the `neo4j` user to ensure the appropriate file permissions. -* `neo4j-admin database backup/restore` (Enterprise only) -– used for performing online backup (xref:backup-restore/modes.adoc#full-backup[full] and xref:backup-restore/modes.adoc#differential-backup[differential]) and restore operations. -The database to be backed up must be in **online** mode. -The command produces an immutable artifact, which has an inspectable API to aid management and operability. -This command is suitable for production environments, where you cannot afford downtime. -+ -The command can also be invoked over the network if access is enabled using `server.backup.listen_address`. +* `neo4j-admin database backup/restore` label:enterprise[Enterprise Edition] – used for performing online backup (xref:backup-restore/modes.adoc#full-backup[full] and xref:backup-restore/modes.adoc#differential-backup[differential]) and restore operations. +** The database to be backed up must be in **online** mode. +** The command produces an immutable artifact, which has an inspectable API to aid management and operability. +** This command is suitable for production environments, where you cannot afford downtime. +** The command can also be invoked over the network if access is enabled using `server.backup.listen_address`. + [NOTE] ==== @@ -73,9 +72,9 @@ For more information, refer to the xref:backup-restore/online-backup.adoc#backup When using `neo4j-admin database backup` in a cluster, it is recommended to back up from an external instance as opposed to reuse instances that form part of the cluster. ==== * `neo4j-admin database dump/load` –- used for performing offline dump and load operations. -The database to be dumped must be in **offline** mode. -The dump command can only be invoked from the server command line and is suitable for environments where downtime is not a factor. -The command produces an archive file that follows the format _.dump_. +** The database to be dumped must be in **offline** mode. +** The dump command can only be invoked from the server command line and is suitable for environments where downtime is not a factor. +** The command produces an archive file that follows the format _.dump_. * `neo4j-admin database copy` –- used for copying an offline database or backup. This command can be used for cleaning up database inconsistencies and reclaiming unused space. @@ -84,23 +83,9 @@ This command can be used for cleaning up database inconsistencies and reclaiming File system copy-and-paste of databases is not supported and may result in unwanted behavior, such as corrupt stores. ==== -=== Considerations for backing up and restoring databases in a cluster - -Backing up a database in a clustered environment is not essentially different from a standalone backup, apart from the fact that you must know which server in a cluster to connect to. -Use `SHOW DATABASE ` to learn which servers are hosting the database you want to back up. -See xref:clustering/monitoring/show-databases-monitoring.adoc#show-databases-monitoring-listing-single[Listing a single database] for more information. - -However, _restoring_ a database in a cluster is different since it is not known in advance how a database is going to be allocated to the servers in a cluster. -This method relies on the seed already existing on one of the servers. -The recommended way to restore a database in a cluster is to xref::database-administration/standard-databases/seed-from-uri.adoc[seed from URI]. - -[NOTE] -==== -The Neo4j Admin commands `backup`, `restore`, `dump`, `load`, `copy`, and `check-consistency` are not supported for use on xref:database-administration/composite-databases/concepts.adoc[Composite databases]. -They must be run directly on the databases that are associated with that Composite database. -==== +The following table summarizes the commands' capabilities and usage. -.The following table describes the commands' capabilities and usage. +.`neo4j-admin` commands for backing up and restoring databases [cols="<,^,^,^",frame="topbot",options="header"] |=== | Capability/ Usage @@ -184,19 +169,43 @@ They must be run directly on the databases that are associated with that Composi | {check-mark} |=== + +[NOTE] +==== +The Neo4j Admin commands `backup`, `restore`, `dump`, `load`, `copy`, and `check-consistency` are not supported for use on xref:database-administration/composite-databases/concepts.adoc[Composite databases]. +They must be run directly on the databases that are associated with that Composite database. +==== + + +=== Considerations for backing up and restoring databases in a cluster + +Backing up a database in a clustered environment is not essentially different from a standalone backup, apart from the fact that you must know which server in a cluster to connect to. +Use `SHOW DATABASE ` to learn which servers are hosting the database you want to back up. +See xref:clustering/monitoring/show-databases-monitoring.adoc#show-databases-monitoring-listing-single[Listing a single database] for more information. + +However, _restoring_ a database in a cluster is different since it is not known in advance how a database is going to be allocated to the servers in a cluster. +This method relies on the seed already existing on one of the servers. +The recommended way to restore a database in a cluster is to xref::database-administration/standard-databases/seed-from-uri.adoc[seed from URI]. + + [[backup-planning-databases]] == Databases to backup A Neo4j DBMS can host multiple databases. Both Neo4j Community and Enterprise Editions have a default user database, called `neo4j`, and a `system` database, which contains configurations, e.g., operational states of databases, security configuration, schema definitions, login credentials, and roles. -In the Enterprise Edition, you can also create additional user databases. + +In the Enterprise Edition, you can also create multiple user databases. Each of these databases is backed up independently of one another. [NOTE] ==== -It is very important to store a recent backup of your databases, including the `system` database, in a safe location. +Backing up the `system` database, it is recommended to use the `--include-metadata=all` option. +This restores the user databases to the new `system` database retaining not only `users` and `roles` but also the cluster topology. ==== +It is very important to store a recent backup of your databases, including the `system` database, in a safe location. + + [[backup-planning-additional]] == Additional files to back up From b7af803f631ca39ce614da3282c051fbe95703da Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Tue, 12 Aug 2025 15:44:50 +0200 Subject: [PATCH 2/5] Update planning.adoc --- .../ROOT/pages/backup-restore/planning.adoc | 19 ++++++++++--------- 1 file changed, 10 insertions(+), 9 deletions(-) diff --git a/modules/ROOT/pages/backup-restore/planning.adoc b/modules/ROOT/pages/backup-restore/planning.adoc index f23e98bc7..5ce03790e 100644 --- a/modules/ROOT/pages/backup-restore/planning.adoc +++ b/modules/ROOT/pages/backup-restore/planning.adoc @@ -187,22 +187,23 @@ However, _restoring_ a database in a cluster is different since it is not known This method relies on the seed already existing on one of the servers. The recommended way to restore a database in a cluster is to xref::database-administration/standard-databases/seed-from-uri.adoc[seed from URI]. +[NOTE] +==== +For backing up a clustered database, it is recommended to use the `--include-metadata=all` option. +This option includes metadata in the backup file, retaining not only `users` and `roles` but also the cluster topology. +The cluster topology in the `system` database details which servers exist and their modes. +==== [[backup-planning-databases]] -== Databases to backup +== Databases to back up A Neo4j DBMS can host multiple databases. -Both Neo4j Community and Enterprise Editions have a default user database, called `neo4j`, and a `system` database, which contains configurations, e.g., operational states of databases, security configuration, schema definitions, login credentials, and roles. +Both Neo4j Community and Enterprise Editions have a default user database named `neo4j` and a `system` database. +The `system` database contains configurations, e.g., operational states of databases, security configuration, schema definitions, login credentials, and roles. In the Enterprise Edition, you can also create multiple user databases. Each of these databases is backed up independently of one another. -[NOTE] -==== -Backing up the `system` database, it is recommended to use the `--include-metadata=all` option. -This restores the user databases to the new `system` database retaining not only `users` and `roles` but also the cluster topology. -==== - It is very important to store a recent backup of your databases, including the `system` database, in a safe location. @@ -224,4 +225,4 @@ If you have a cluster, you should back up these files for each cluster member. For any backup, it is important that you store your data separately from the production system, where there are no common dependencies, and preferably off-site. If you are running Neo4j in the cloud, you may use a different availability zone or even a separate cloud provider. -Since backups are kept for a long time, the longevity of archival storage should be considered as part of backup planning. \ No newline at end of file +Since backups are kept for a long time, the longevity of archival storage should be considered as part of backup planning. From 9b9c61add8d6986543d4a244637e60bb0226212a Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Fri, 15 Aug 2025 08:37:33 +0200 Subject: [PATCH 3/5] Edit the note --- modules/ROOT/pages/backup-restore/planning.adoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/modules/ROOT/pages/backup-restore/planning.adoc b/modules/ROOT/pages/backup-restore/planning.adoc index 5ce03790e..4d4e5b5ec 100644 --- a/modules/ROOT/pages/backup-restore/planning.adoc +++ b/modules/ROOT/pages/backup-restore/planning.adoc @@ -189,9 +189,9 @@ The recommended way to restore a database in a cluster is to xref::database-admi [NOTE] ==== -For backing up a clustered database, it is recommended to use the `--include-metadata=all` option. -This option includes metadata in the backup file, retaining not only `users` and `roles` but also the cluster topology. -The cluster topology in the `system` database details which servers exist and their modes. +When backing up a clustered database, use the `--include-metadata=all` option. +This option ensures that the backup includes not only `users` and `roles`, but also the cluster topology. +Cluster topology metadata, stored in the `system` database, defines the servers in the cluster and their operational modes. ==== [[backup-planning-databases]] From e1e30f39a4c5263b48784b35eb9b861f57e62b86 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Fri, 15 Aug 2025 17:05:49 +0200 Subject: [PATCH 4/5] Change the note --- modules/ROOT/pages/backup-restore/planning.adoc | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/backup-restore/planning.adoc b/modules/ROOT/pages/backup-restore/planning.adoc index 4d4e5b5ec..0e8a2b0b4 100644 --- a/modules/ROOT/pages/backup-restore/planning.adoc +++ b/modules/ROOT/pages/backup-restore/planning.adoc @@ -177,7 +177,7 @@ They must be run directly on the databases that are associated with that Composi ==== -=== Considerations for backing up and restoring databases in a cluster +== Considerations for backing up and restoring databases in a cluster Backing up a database in a clustered environment is not essentially different from a standalone backup, apart from the fact that you must know which server in a cluster to connect to. Use `SHOW DATABASE ` to learn which servers are hosting the database you want to back up. @@ -187,11 +187,12 @@ However, _restoring_ a database in a cluster is different since it is not known This method relies on the seed already existing on one of the servers. The recommended way to restore a database in a cluster is to xref::database-administration/standard-databases/seed-from-uri.adoc[seed from URI]. -[NOTE] +[IMPORTANT] ==== -When backing up a clustered database, use the `--include-metadata=all` option. -This option ensures that the backup includes not only `users` and `roles`, but also the cluster topology. -Cluster topology metadata, stored in the `system` database, defines the servers in the cluster and their operational modes. +When backing up a clustered database, be aware that the xref:clustering/introduction.adoc#clustering-introduction-operational[cluster topology] metadata is not included in the backup. +The cluster topology is stored in the `system` database and describes how the copies of a database should be spread across the servers in a cluster. + +Because this metadata is excluded from backups, restoring to a new cluster environment requires manual reconfiguration of servers modes and database allocations. ==== [[backup-planning-databases]] From cb49d5d7214b4a285095747a1a61bf5dcb94c3e4 Mon Sep 17 00:00:00 2001 From: Natalia Ivakina <82437520+NataliaIvakina@users.noreply.github.com> Date: Wed, 27 Aug 2025 10:11:21 +0200 Subject: [PATCH 5/5] Update the note --- modules/ROOT/pages/backup-restore/planning.adoc | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/modules/ROOT/pages/backup-restore/planning.adoc b/modules/ROOT/pages/backup-restore/planning.adoc index 0e8a2b0b4..d7ad162bb 100644 --- a/modules/ROOT/pages/backup-restore/planning.adoc +++ b/modules/ROOT/pages/backup-restore/planning.adoc @@ -183,16 +183,17 @@ Backing up a database in a clustered environment is not essentially different fr Use `SHOW DATABASE ` to learn which servers are hosting the database you want to back up. See xref:clustering/monitoring/show-databases-monitoring.adoc#show-databases-monitoring-listing-single[Listing a single database] for more information. -However, _restoring_ a database in a cluster is different since it is not known in advance how a database is going to be allocated to the servers in a cluster. -This method relies on the seed already existing on one of the servers. +Restoring from the command line involves putting a copy of the database on disk on each server that will need it. +That can be awkward to achieve. The recommended way to restore a database in a cluster is to xref::database-administration/standard-databases/seed-from-uri.adoc[seed from URI]. [IMPORTANT] ==== -When backing up a clustered database, be aware that the xref:clustering/introduction.adoc#clustering-introduction-operational[cluster topology] metadata is not included in the backup. -The cluster topology is stored in the `system` database and describes how the copies of a database should be spread across the servers in a cluster. +By default, a database backup includes only the database contents. +If you choose to include metadata, the backup also stores the role-based access control (RBAC) settings associated with the database. -Because this metadata is excluded from backups, restoring to a new cluster environment requires manual reconfiguration of servers modes and database allocations. +When restoring, you have the flexibility to define the target topology (how many primaries and secondaries are desired for the database), which may differ from the topology at backup time. +The database will then be allocated across the available servers according to that topology. ==== [[backup-planning-databases]]