Clarify how to restore a database backup in cluster

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]
 ====

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

@@ -172,10 +172,10 @@ 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 database backup in a standalone environment
 
 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.
+If you want to replace an existing standalone database, you need to stop it first and add the option `--overwrite-destination=true` to the restore command.
 
 . Restore a database backup by running the following command:
 +
@@ -235,6 +235,7 @@ For example, `--restore-until=123`.
 CREATE DATABASE mydatabase;
 ----
 
+
 [[restore-cloud-storage]]
 === Restore a backup located in cloud storage
 
@@ -292,17 +293,26 @@ bin/neo4j-admin database restore --from-path=azb://myStorageAccount/myContainer/
 ======
 =====
 
+
 === 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].
+To restore a database backup in a cluster, you can use one of the following methods:
+
+* 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 from a backup or server URI.
+See xref:clustering/databases.adoc#restore-database-using-uri-approach[Restore a database using URI approach] for more information.
+* 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 database backup using the `neo4j-admin database copy` command] for more details.
+
 
 === Restore users and roles metadata
 
-If you have backed up a database with the option `--include-metadata`, you can manually restore the users, roles, and auth rules metadata.
+Roles and users metadata are backed up during the backup process by default.
 
-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 +325,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

@@ -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,18 @@ 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 
+
+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.
+
+Alternatively, you can stop the Neo4j server and unbind it from the cluster using xref:clustering/unbind.adoc[`neo4j-admin server unbind`] to remove its cluster state data.
+
+If you fail to `DROP` the database or unbind a server 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-designated-seeder[Restore a database using a designated seeder].
+
+It is recommended to restore a database dump using a URI approach.
+See xref:database-administration/standard-databases/seed-from-uri.adoc[] for details.
+

modules/ROOT/pages/clustering/databases.adoc

@@ -275,22 +275,27 @@ neo4j@neo4j> DRYRUN REALLOCATE DATABASES;
 
 
 [[cluster-seed]]
-== Seed a cluster
+== Restore a clustered database from a `.backup`/`.dump`
 
-There are two different ways to seed a cluster with data:
+To restore a clustered database from a backup, or to seed a cluster with data:
 
-* The first option is to use a _designated seeder_, where a designated server is used to create a backed-up database on other servers in the cluster.
-* The other option is to seed the cluster from a URI, where all servers to host the database are seeded with an identical seed from an external source specified by that URI.
+* You can use a _designated seeder_, where a designated server is used to create a backed-up database on other servers in the cluster.
+* You can seed the cluster from a URI, where all servers to host the database are seeded with an identical seed from an external source specified by that URI.
 For more details, see xref:database-administration/standard-databases/seed-from-uri.adoc[Create a database from a URI].
+* You can use the `dbms.recreateDatabase()` procedure.
+* You can also use the `neo4j-admin database copy` command.
 
+[NOTE]
+====
 Keep in mind that using a designated seeder can be problematic in some situations as it is not known in advance how a database is going to be allocated to the servers in a cluster.
 Also, this method relies on the seed already existing on one of the servers.
+====
 
 
 [[cluster-designated-seeder]]
-=== Designated seeder
+=== Restore a database using a designated seeder
 
-In order to designate a server in the cluster as a seeder, a database backup is transferred to that server using the xref:backup-restore/restore-backup.adoc[`neo4j-admin database restore`] command.
+In order to designate a server in the cluster as _a seeder_, a database backup is transferred to that server using the xref:backup-restore/restore-backup.adoc[`neo4j-admin database restore`] command.
 Subsequently, that server is used as the source for other cluster members to copy the backed-up database from.
 
 This example creates a user database called `foo`, hosted on three servers in primary mode.
@@ -332,7 +337,7 @@ This may be different from the topology of `foo` when it was backed up.
 If you want to ensure a certain allocation across the cluster, you can specify the desired topology with the `TOPOLOGY` clause in the `CREATE DATABASE` command.
 See <<create-database, `CREATE DATABASE`>> for more information.
 +
-[source, cypher, role=noplay]
+[source, cypher5, role=noplay]
 ----
 CREATE DATABASE foo
 TOPOLOGY [desired number of primaries] PRIMARIES [desired number of secondaries] SECONDARIES
@@ -359,6 +364,193 @@ SHOW DATABASE foo;
 9 rows available after 3 ms, consumed after another 1 ms
 ----
 
+
+[[restore-database-using-uri-approach]]
+=== Restore a database from a URI
+
+Before restoring a database, you have to take its backup and drop the database on all servers.
+If you have not dropped the database before restoring it, use `CREATE OR REPLACE DATABASE` instead of the `CREATE DATABASE` command.
+
+The seed can be a full backup, a differential backup, or a dump from an existing database.
+When using `CloudSeedProvider`, the URI can point also to a folder which contains a backup chain.
+The sources of seeds are called _seed providers_. +
+For detailed information about seed providers in Neo4j, see xref:database-administration/standard-databases/seed-from-uri.adoc[].
+
+Remember that the dump file created with the xref:backup-restore/offline-backup.adoc#offline-backup-command[`neo4j-admin database dump`] command contains only the database data.
+The associated users and roles metadata are not included and must be recreated manually after restore.
+
+When restoring a database from a backup seed in a cluster, you have to define the database topology.
+You have the opportunity to create a topology that will differ from an original one.
+
+The new allocations can be put on any available server in the cluster.
+
+On one of the servers, run the command:
+
+[.tabbed-example]
+=====
+[role=include-with-Cypher-25 label--new-2025.06]
+======
+
+[source, cypher25]
+----
+CREATE DATABASE foo
+TOPOLOGY [desired number of primaries] PRIMARIES [desired number of secondaries] SECONDARIES
+OPTIONS { seedURI: 's3://myBucket/myBackup.backup' }
+----
+
+======
+[role=include-with-Cypher-5]
+======
+
+[source, cypher5]
+----
+CREATE DATABASE foo
+TOPOLOGY [desired number of primaries] PRIMARIES [desired number of secondaries] SECONDARIES
+OPTIONS { existingData: 'use', seedURI: 's3://myBucket/myBackup.backup' }
+----
+======
+=====
+
+Number of primaries and secondaries must respect the number of available servers and their mode constraints.
+The `CREATE DATABASE` command automatically allocates the database.
+
+If you restore your database from a backup file created with the xref:backup-restore/online-backup.adoc[`neo4j-admin database backup`] command, users and roles metadata is backed up by default unless you have changed the default value of the `--include-metadata` option.
+As a final step, you can xref:backup-restore/restore-backup.adoc#_restore_users_and_roles_metadata[restore users and roles metadata].
+This step is optional.
+
+Verify that the restored database is online on the desired number of servers, in the desired roles by running the `SHOW DATABASES` command.
+
+Starting with 2026.04, you can also restore a database from a server URI using the `server://` scheme.
+See xref:database-administration/standard-databases/seed-from-uri.adoc#server-seed-provider[Create a database from a URI -> `ServerSeedProvider`] for details.
+
+
+[[restore-database-using-recreate-procedure]]
+=== Restore a database using the `dbms.recreateDatabase()` procedure
+
+For detailed information on the recreate procedure, its options and limitations, see xref:database-administration/standard-databases/recreate-database.adoc[].
+
+You need xref:authentication-authorization/dbms-administration/dbms-database-management-privileges.adoc[the `CREATE DATABASE` and `DROP DATABASE` privileges] to run the recreate procedure.
+
+If you provide a URI to a backup or a dump, the stores on all servers will be replaced by the backup or the dump at the given URI.
+The new database allocations can be put on any `ENABLED` server in the cluster.
+
+To restore a database using backup as a seed and keeping the original database topology, run the command:
+
+[source, shell]
+----
+CALL dbms.recreateDatabase("foo", {seedURI: "s3://myBucket/myBackup.backup",});
+----
+
+Starting with 2026.04, you can also use server URI to recreate a database from a backup/dump located on a server in the cluster's file system:
+
+[source, shell]
+----
+CALL dbms.recreateDatabase("foo", {seedURI: "server://server-id/myBackup.backup"});
+----
+
+If a database is restored using `dbms.recreateDatabase()`, all previously granted user and role privileges on that database are preserved.
+
+Verify that the restored database is online on the desired number of servers, in the desired roles by running the `SHOW DATABASES` command.
+
+
+[role=label--new-2026.03]
+[[restore-database-using-copy-command]]
+=== Restore a database backup using the `neo4j-admin database copy` command
+
+See xref:backup-restore/copy-database.adoc#neo4j-admin-copy-command-limitations[Command limitations] before using this option.
+
+The following example assumes that you have a backup of your existing database `foo` in an AWS S3 bucket.
+Before restoring a database, you do not need to stop or drop the database `foo`.
+
+The following options can be specified for the `neo4j-admin database copy` command:
+
+* `--source-location` -- a path to the full backup of an existing database or the last differential backup in the chain.
+This folder can be located locally or remotely (e.g., an S3 bucket) and must contain the full backup and all the differential backups in the chain, if any.
+* `--source-format=backup` -- the format of the source backup.
+* `--copy-schema` -- (optional) to copy the schema of the existing database if needed.
+* `--target-location` -- a path to a folder for target backup artifact data. Used together with `--target-format=backup`.
+* `--target-format` -- the format of the output data.
+Possible values are `backup` and `database` (default).
+* `--compress` -- label:new[Introduced in 2026.04] (optional) produces compressed backup artifacts.
+See xref:backup-restore/copy-database.adoc#copy-database-command-options[Copy a database store] for more information.
+
+`--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.
+
+. Copy the data from a backup of your standard database `foo` into 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`
+TOPOLOGY [desired number of primaries] PRIMARIES [desired number of secondaries] SECONDARIES
+OPTIONS {seedUri: “s3://bucket/folder/”};
+----
+
+======
+[role=include-with-Cypher-5]
+======
+
+[source, cypher]
+----
+CREATE DATABASE foo-restored
+TOPOLOGY [desired number of primaries] PRIMARIES [desired number of secondaries] SECONDARIES
+OPTIONS {existingData: 'use', seedUri: “s3://bucket/folder/”};
+----
+======
+=====
++
+Number of primaries and secondaries must respect the number of available servers and their mode constraints.
+
+. Wait until the last committed transaction ID is the same for all allocations of the database and then 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` if it is no longer needed, or put it into read-write mode if you want to keep it for other purposes.
++
+[.tabbed-example]
+=====
+[.include-with-drop-database]
+======
+
+Run the following command to drop the old database `foo`:
+
+[source, cypher]
+----
+DROP DATABASE foo;
+----
+======
+[.include-with-change-access-mode]
+======
+
+Change the access mode of the old database `foo` to read-write:
+
+[source, cypher]
+----
+ALTER DATABASE foo SET ACCESS READ WRITE;
+----
+======
+=====
+
+
+
+
+
 [[cluster-allow-deny-db]]
 == Controlling locations with allowed/denied databases
 
@@ -374,6 +566,7 @@ Note that starting from 2025.12, database name patterns (wildcards) are supporte
 ** `modeConstraint` - controls in what mode (primary, secondary, or none) databases can be hosted on a server.
 If not set, there are no mode constraints on the server.
 
+
 [[cluster-default-database]]
 == Default database in a cluster