diff --git a/modules/ROOT/pages/backup-restore/copy-database.adoc b/modules/ROOT/pages/backup-restore/copy-database.adoc index ad05460709..966f087713 100644 --- a/modules/ROOT/pages/backup-restore/copy-database.adoc +++ b/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 diff --git a/modules/ROOT/pages/backup-restore/online-backup.adoc b/modules/ROOT/pages/backup-restore/online-backup.adoc index acb13f7fd0..9497842f87 100644 --- a/modules/ROOT/pages/backup-restore/online-backup.adoc +++ b/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. diff --git a/modules/ROOT/pages/backup-restore/restore-backup.adoc b/modules/ROOT/pages/backup-restore/restore-backup.adoc index 1ae12a92ba..1bff6c2a8f 100644 --- a/modules/ROOT/pages/backup-restore/restore-backup.adoc +++ b/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 <> 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 __ 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 __ 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'" ---- + diff --git a/modules/ROOT/pages/backup-restore/restore-dump.adoc b/modules/ROOT/pages/backup-restore/restore-dump.adoc index 67e0710e78..e245603a5f 100644 --- a/modules/ROOT/pages/backup-restore/restore-dump.adoc +++ b/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]. + diff --git a/modules/ROOT/pages/clustering/databases.adoc b/modules/ROOT/pages/clustering/databases.adoc index d64f68548d..33511f68ae 100644 --- a/modules/ROOT/pages/clustering/databases.adoc +++ b/modules/ROOT/pages/clustering/databases.adoc @@ -275,22 +275,86 @@ 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. -For more details, see xref:database-administration/standard-databases/seed-from-uri.adoc[Create a database from a URI]. +* You can <>, where all servers to host the database are seeded with an identical seed from an external source specified by that URI. +* You can use <>, where a designated server is used to create a backed-up database on other servers in the cluster. +* You can use <>. +* You can also use <>. -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. + +[[restore-database-using-uri-approach]] +=== Restore a database from a URI + +Before restoring a database from a backup, ensure you have 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 the original one. +The new allocations can be put on any `ENABLED` server in the cluster. + +To restore a clustered database from a URI, follow the steps. + +. On one of the cluster's 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 `ENABLED` 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. [[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. +[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. +==== + +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,12 +396,30 @@ 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 <> for more information. + +[.tabbed-example] +===== +[role=include-with-Cypher-25 label--new-2025.06] +====== + [source, cypher, role=noplay] ---- CREATE DATABASE foo TOPOLOGY [desired number of primaries] PRIMARIES [desired number of secondaries] SECONDARIES OPTIONS {existingData: 'use', existingDataSeedServer: '8512c9b9-d9e8-48e6-b037-b15b0004ca18'}; ---- + +====== +[role=include-with-Cypher-5] +====== +[source, cypher, role=noplay] +---- +CREATE DATABASE foo +TOPOLOGY [desired number of primaries] PRIMARIES [desired number of secondaries] SECONDARIES +OPTIONS {existingData: 'use', existingDataSeedInstance: '8512c9b9-d9e8-48e6-b037-b15b0004ca18'}; +---- +====== +===== + . Verify that the `foo` database is online on the desired number of servers, in the desired roles. If the `foo` database is of considerable size, the execution of the command can take some time. + @@ -359,6 +441,132 @@ SHOW DATABASE foo; 9 rows available after 3 ms, consumed after another 1 ms ---- + +[[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[]. + +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. + +You need xref:authentication-authorization/dbms-administration/dbms-database-management-privileges.adoc[the `CREATE DATABASE` and `DROP DATABASE` privileges] to run the recreate procedure. + +You do not need to `DROP DATABASE` before calling the `dbms.recreateDatabase()` procedure. + +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",}); +---- + +If you need to change the original database topology, run the command: + +[source, shell] +---- +CALL dbms.recreateDatabase("foo", {seedURI: "s3://myBucket/myBackup.backup", primaries: 3, secondaries: 0}); +---- + +Number of newly defined `primaries` and `secondaries` must respect number of `ENABLED` servers in a cluster and their mode constraints. + +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. + +As a final step, 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 from a 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 (created with the `neo4j-admin database backup` command) 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. + +[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 +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. + +. 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; +---- + + [[cluster-allow-deny-db]] == Controlling locations with allowed/denied databases @@ -374,6 +582,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