Clarify how to restore a database backup in cluster (#3035)

Our restore documentation is very standalone minded. This PR attempts to
cover methods on how to restore a clustered database from a backup or
dump file.

Author: NataliaIvakina

modules/ROOT/pages/backup-restore/copy-database.adoc

@@ -7,6 +7,7 @@
 You can use the `neo4j-admin database copy` command to copy a database, create a compacted/defragmented copy of a database, clean up database inconsistencies, or do a direct migration from Neo4j 4.4 to any 5.x version.
 `neo4j-admin database copy` reclaims the unused space, creates a defragmented copy of the _data store_, and creates the node label and relationship type lookup indexes.
 
+[[neo4j-admin-copy-command-limitations]]
 .Command limitations
 [NOTE]
 ====
@@ -384,6 +385,78 @@ START DATABASE neo4j
 For a detailed example of how to reclaim unused space, see xref:performance/space-reuse.adoc#space-reuse-reclaim-space[Reclaim unused space].
 ====
 
+[role=label--new-2026.03]
+[[copy-data-store-from-backup]]
+=== Copy the data store from a backup
+
+The following example assumes that you have a backup (created with the `neo4j-admin database backup` command) of your existing database `foo` in an AWS S3 bucket.
+
+Before copying the database store from a backup, you do not need to stop or drop the database `foo`.
+
+You can specify any differential backup in the chain.
+Then the entire chain up to that point must be located in the same folder as the specified diff.
+The chain will be found in the folder and all changes in that chain up to the point specified will be part of the result database from the copy operation.
+If not, the command will fail due to incomplete chain.
+
+[IMPORTANT]
+====
+`--source-location` and `--source-format` cannot be used together with `--from-path-data` and/or `--from-path-txn` due to the conflict in trying to supply data from two different locations at once.
+
+The copy command does not copy over users and roles metadata.
+You have to copy and re-apply them manually.
+====
+
+. Copy the data from a backup of your standard database `foo` into a backup for the database `foo-restored`.
++
+[source, shell]
+----
+neo4j-admin database copy foo foo-restored --source-location=s3://bucket/folder/foo.backup --source-format=backup --copy-schema --target-location=s3://bucket/folder --target-format=backup
+----
++
+Copying a database does not automatically create it.
+Therefore, it will not be visible if you do `SHOW DATABASES` at this point.
+
+. Run the following command to create the database `foo-restored` by seeding it from your backup folder in the AWS S3 bucket:
++
+[.tabbed-example]
+=====
+[role=include-with-Cypher-25 label--new-2025.06]
+======
+
+[source, cypher]
+----
+CREATE DATABASE foo-restored
+OPTIONS {seedUri: “s3://bucket/folder/”};
+----
+
+======
+[role=include-with-Cypher-5]
+======
+
+[source, cypher]
+----
+CREATE DATABASE foo-restored
+OPTIONS {existingData: 'use', seedUri: “s3://bucket/folder/”};
+----
+======
+=====
+
+. Verify that the new database is online by running the following command:
++
+[source, cypher]
+----
+SHOW DATABASES;
+----
+. After the new database is online, you can drop the old database `foo`.
++
+Run the following command to drop the old database `foo`:
++
+[source, cypher]
+----
+DROP DATABASE foo;
+----
+
+
 [[copy-estimating-iops]]
 == Estimating the processing time
 

modules/ROOT/pages/backup-restore/online-backup.adoc

@@ -13,7 +13,7 @@ Note that it is not allowed to take a backup of a database alias, only physical
 [[online-backup-command]]
 == Command
 
-A Neo4j database can be backed up in **online mode** using the `backup` command of `neo4j-admin`.
+A Neo4j database can be backed up in **online mode** using the `neo4j-admin database backup` command.
 The command must be invoked as the `neo4j` user to ensure the appropriate file permissions.
 
 It is best practice, but not mandatory, to perform the backup from a server on the same network as the database, but that is not part of the cluster.

modules/ROOT/pages/backup-restore/restore-backup.adoc

@@ -3,15 +3,40 @@
 [[restore-backup]]
 = Restore a database backup
 
+Neo4j suggests a few options to restore a database backup artifact (full or differential) created with the xref:backup-restore/online-backup.adoc[`neo4j-admin database backup`] command.
+
+== Restore a database on a standalone server
+
+To restore a database from a backup in a standalone server environment, use one of the following methods:
+
+* Use the <<restore-backup-command, `neo4j-admin database restore`>> command.
+* Restore a database using URI approach.
+See xref:database-administration/standard-databases/seed-from-uri.adoc[] for detailed information.
+* Recreate a database using the xref:database-administration/standard-databases/recreate-database.adoc[`dbms.recreateDatabase()` procedure].
+* label:new[Introduced in 2026.03] Use the xref:backup-restore/copy-database.adoc[`neo4j-admin database copy`] command to restore database data from a backup.
+See xref:backup-restore/copy-database.adoc#copy-data-store-from-backup[Copy database data from a backup] for an example.
+* You can also load a **full** database backup artifact using the xref:backup-restore/restore-dump.adoc[`neo4j-admin database load`] command.
+This functionality is available in the Community Edition.
+
+== Restore a clustered database from a backup
+
+To restore a database from a backup in a clustered environment, use one of the following methods:
+
+* Recreate a database from a URI.
+See xref:clustering/databases.adoc#restore-database-using-uri-approach[Restore a database in cluster using URI approach] for more information.
+* Designate one of the servers to be used as a seeder, and restore the database backup on that server.
+For more information, see xref:clustering/databases.adoc#cluster-designated-seeder[Restore a database using a server as a designated seeder].
+* Recreate a database using the `dbms.recreateDatabase()` procedure.
+See xref:clustering/databases.adoc#restore-database-using-recreate-procedure[Restore a database using `dbms.recreateDatabase()`] for more details.
+* label:new[Introduced in 2026.03] Use the xref:backup-restore/copy-database.adoc[`neo4j-admin database copy`] command.
+See xref:clustering/databases.adoc#restore-database-using-copy-command[Restore a clustered database using the `copy` command] for more details.
+
 [[restore-backup-command]]
 == Command
 
 A database backup artifact (full or differential) can be restored within the same or to a later Neo4j version using the `restore` command of `neo4j-admin`.
 
-You can also load a **full** database backup artifact using the xref:backup-restore/restore-dump.adoc[`neo4j-admin database load`] command.
-This functionality is available in the Community Edition.
-
-[NOTE]
+[IMPORTANT]
 ====
 Restoring a database backup to a previous Neo4j version is not supported.
 ====
@@ -172,7 +197,7 @@ The `LOWEST TX` and `HIGHEST TX` columns show the transaction IDs of the first a
 That means, if you restore `neo4j-2023-06-29T14-50-45.backup`, your database will have `14` as the last transaction ID.
 
 
-=== Restore a database backup
+=== Restore a backup on a standalone server
 
 The following examples assume that you want to restore your data in a new database, called `mydatabase`.
 If you want to replace an existing database, you need to stop it first and add the option `--overwrite-destination=true` to the restore command.
@@ -235,6 +260,7 @@ For example, `--restore-until=123`.
 CREATE DATABASE mydatabase;
 ----
 
+
 [[restore-cloud-storage]]
 === Restore a backup located in cloud storage
 
@@ -261,6 +287,14 @@ The example assumes that you have backup artifacts located in the `myBucket/myDi
 ----
 bin/neo4j-admin database restore --from-path=s3://myBucket/myDirectory/myBackup.backup mydatabase
 ----
+
+. If you have not stopped your database and used the `--overwrite-destination=true` option, you have to create the new `mydatabase` by running the command:
++
+[source,cypher]
+----
+CREATE DATABASE mydatabase;
+----
+
 ======
 
 [role=include-with-Google-cloud-storage]
@@ -275,6 +309,14 @@ The example assumes that you have backup artifacts located in the `myBucket/myDi
 ----
 bin/neo4j-admin database restore --from-path=gs://myBucket/myDirectory/myBackup.backup mydatabase
 ----
+
+. If you have not stopped your database and used the `--overwrite-destination=true` option, you have to create the new `mydatabase` by running the command:
++
+[source,cypher]
+----
+CREATE DATABASE mydatabase;
+----
+
 ======
 
 [role=include-with-Azure-cloud-storage]
@@ -289,20 +331,23 @@ The example assumes that you have backup artifacts located in the `myStorageAcco
 ----
 bin/neo4j-admin database restore --from-path=azb://myStorageAccount/myContainer/myDirectory/myBackup.backup mydatabase
 ----
+
+. If you have not stopped your database and used the `--overwrite-destination=true` option, you have to create the new `mydatabase` by running the command:
++
+[source,cypher]
+----
+CREATE DATABASE mydatabase;
+----
+
 ======
 =====
 
-=== Restore a database backup in a cluster
 
-To restore a database backup in a cluster, designate one of the servers to be used as a seeder, and restore the database backup on that server.
-Then, use that server to create the restored database on other servers in the cluster.
-For more information, see xref:clustering/databases.adoc#cluster-seed[Designated seeder].
+== Restore users and roles metadata
 
-=== Restore users and roles metadata
+Users, roles, and auth rules metadata are backed up during the backup process by default.
 
-If you have backed up a database with the option `--include-metadata`, you can manually restore the users, roles, and auth rules metadata.
-
-From the _<NEO4J_HOME>_ directory, you run the Cypher script _/data/scripts/databasename/restore_metadata.cypher_, which the `neo4j-admin database restore` command outputs, using xref:cypher-shell.adoc[]:
+If you need to restore the users and roles metadata, you have to do it manually by running the Cypher script from the _<NEO4J_HOME>_ directory, _/data/scripts/databasename/restore_metadata.cypher_, which the `neo4j-admin database restore` command outputs, using xref:cypher-shell.adoc[]:
 
 *Using `cat` (UNIX)*
 [source, shell, role=nocopy noplay]
@@ -315,3 +360,4 @@ cat ../data/scripts/databasename/restore_metadata.cypher | bin/cypher-shell -u u
 ----
 type ..\data\scripts\databasename\restore_metadata.cypher | bin\cypher-shell.bat -u user -p password -a ip_address:port -d system --param "database => 'databasename'"
 ----
+

modules/ROOT/pages/backup-restore/restore-dump.adoc

@@ -4,7 +4,7 @@
 
 The `neo4j-admin database load` command can be used to load a database from an archive created with the xref:backup-restore/offline-backup.adoc#offline-backup-command[`neo4j-admin database dump`] command or a full backup artifact created by the xref:backup-restore/online-backup.adoc[`neo4j-admin database backup`] command from Neo4j Enterprise.
 
-If you are replacing an existing database, you have to shut it down before running the command and use the `--overwrite-destination` option. +
+If you are replacing an existing database on a standalone server, you have to shut it down before running the command and use the `--overwrite-destination` option. +
 label:enterprise-edition[] If you are not replacing an existing database, you must create the database (using `CREATE DATABASE` against the `system` database) after the load operation finishes.
 
 The command can be run from either an online or offline Neo4j DBMS on Enterprise edition.
@@ -108,15 +108,8 @@ The `--overwrite-destination` option is required because you are replacing the e
 
 If you are not replacing an existing database in Enterprise Edition, you must create the database (using `CREATE DATABASE` against the `system` database) after the load operation finishes.
 
-[NOTE]
-====
-When using the `load` command to seed a cluster, and a previous version of the database exists, you must delete it (using `DROP DATABASE`) first.
-Alternatively, you can stop the Neo4j instance and unbind it from the cluster using `neo4j-admin server unbind` to remove its cluster state data.
-If you fail to DROP or unbind before loading the dump, that database’s store files will be out of sync with its cluster state, potentially leading to logical corruptions.
-For more information, see xref:clustering/databases.adoc#cluster-seed[Seed a cluster].
-====
 
-[NOTE]
+[IMPORTANT]
 ====
 `neo4j-admin database load` cannot be applied to xref:scalability/composite-databases/concepts.adoc[Composite databases].
 It must be run directly on the databases that are associated with that Composite database.
@@ -200,3 +193,15 @@ bin/neo4j-admin database load mydatabase --from-path=azb://myStorageAccount/myCo
 ======
 =====
 
+
+[role=label--enterprise-edition]
+[[restore-dump-in-cluster]]
+=== Restore a clustered database from a dump 
+
+It is recommended to restore a clustered database from a dump using a URI approach.
+See xref:database-administration/standard-databases/seed-from-uri.adoc[] for details.
+
+When using the `neo4j-admin database load` command to seed a cluster, and a previous version of the database exists, you must delete it (using `DROP DATABASE`) first.
+If you fail to `DROP` the database, that database’s store files will be out of sync with its cluster state, potentially leading to logical corruptions.
+For more information, see xref:clustering/databases.adoc#cluster-designated-seeder[Restore a database using a designated seeder].
+