Restore a database backup
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
.
Starting with Neo4j 5.20, you can load a full database backup artifact using the neo4j-admin database load
command.
This functionality is available in the Community Edition.
Restoring a database backup to a previous Neo4j version is not supported. |
You must create the database (using CREATE DATABASE
against the system
database) after the restore operation finishes, unless you are replacing an existing database.
neo4j-admin database restore
must be invoked as the neo4j
user to ensure the appropriate file permissions.
For more information, see Create databases.
If you are using CDC, make sure to create this new database with the same |
When restoring a backup chain, the transaction log contained in the differential backup artifacts must first be replayed. This recovery operation is resource-intensive and can be decoupled from the restore operation by using the aggregate command. |
Syntax
neo4j-admin database restore [-h] [--expand-commands]
[--verbose] [--overwrite-destination[=true|false]]
[--additional-config=<file>]
--from-path=<path>[,<path>...]
[--restore-until=<recovery-criteria>]
[--to-path-data=<path>] [--to-path-txn=<path>]
[<database>]
Parameters
Parameter | Description |
---|---|
|
Name of the database after restore. Usage of this parameter is only allowed if the |
Options
Option | Description | Default | ||
---|---|---|---|---|
|
Configuration file with additional configuration. |
|||
|
Allow command expansion in config value evaluation. |
|||
|
A single path or a comma-separated list of paths pointing to a backup artifact file. An artifact file can be 1) a full backup, in which case it is restored directly or, 2) a differential backup, in which case the command tries first to find in the folder a backup chain ending at that specific differential backup and then restores that chain. |
|||
|
Show this help message and exit. |
|||
|
If an existing database should be replaced.
|
|
||
|
Differential backup artifacts contain transaction logs that can be replayed and applied to stores contained in full backup artifacts when restoring a backup chain.
The database applies logs until the recovery predicate is satisfied.
Currently supported predicates are:
|
|||
|
Base directory for databases.
Usage of this option is only allowed if the |
|||
|
Base directory for transaction logs.
Usage of this option is only allowed if the |
|||
|
Enable verbose output. |
As of Neo4j 5.19, the |
Examples
The following examples show how to inspect your backup directory and restore a database backup, created in the section Back up an online database. It is assumed that the backup artifacts (full and differential) are located in the /path/to/mybackups directory.
Inspect the backup artifacts
Use the following command to inspect the backup directory:
bin/neo4j-admin database backup --inspect-path=/path/to/mybackups
| FILE | DATABASE | DATABASE ID | TIME | FULL | COMPRESSED | LOWEST TX | HIGHEST TX |
| file:///path/to/mybackups/neo4j-2023-06-29T14-46-27.backup | neo4j | c8368b24-55e2-474d-bb41-75657f5bfcde | 2023-06-29T13:46:27 | true | true | 1 | 11 |
| file:///path/to/mybackups/neo4j-2023-06-29T14-50-45.backup | neo4j | c8368b24-55e2-474d-bb41-75657f5bfcde | 2023-06-29T13:50:45 | false | true | 12 | 14 |
| file:///path/to/mybackups/neo4j-2023-06-29T14-51-33.backup | neo4j | c8368b24-55e2-474d-bb41-75657f5bfcde | 2023-06-29T13:51:33 | false | true | 15 | 18 |
The example output shows that the backup artifacts are part of a backup chain.
The first artifact is a full backup, and the other two are differential backups.
The LOWEST TX
and HIGHEST TX
columns show the transaction IDs of the first and the last transaction in the backup artifacts.
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
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.
Restore a full backup
Restore a database backup by running the following command:
+
bin/neo4j-admin database restore --from-path=/path/to/backups/neo4j-2023-05-05T11-26-38.backup mydatabase
+
The --from-path=
argument must contain the path to the last backup of a chain, in this case, neo4j-2023-06-29T14-51-33.backup
.
+
If you want to restore several databases at once, you must stop them first and then you can alter the command by specifying a comma-separated list of paths to backup artifacts, and remove the |
-
Create the new database using
CREATE DATABASE
against thesystem
database.CREATE DATABASE mydatabase
Restore data up to a specific date
To restore data up to a specific date, you need to pass the backup artifact that contains the data up to that date.
This example assumes 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.
-
Restore from the backup that contains the data up to the desired date.
bin/neo4j-admin database restore --from-path=/path/to/mybackups/neo4j-2023-06-29T14-50-45.backup --restore-until="2023-06-29 13:50:45" mydatabase
The
--from-path=
argument must contain the path to either a full or a differential backup artifact. The--restore-until=
argument must contain a UTC date and time. The restore recovers all transactions that were committed before the provided date and time.If you want to restore several databases at once, you must stop them first and then you can alter the command by specifying a comma-separated list of paths to backup artifacts, and remove the
<database>
parameter. You should also skip theCREATE DATABASE
step afterward if you are replacing an existing database.If you know the transaction ID of the last transaction that was committed before the date you want to restore to, you can use the
--restore-until=
argument with the transaction ID instead of the date. For example,--restore-until=123
. -
Create the new database using
CREATE DATABASE
against thesystem
database:CREATE DATABASE mydatabase;
Restore a backup located in an AWS S3 storage
This feature is available from Neo4j 5.19.
You can restore a database backup located in an AWS S3 storage, you can use the --from-path
option with an S3 URI.
For example, use the following steps.
Neo4j uses the AWS SDK v2 to call the APIs on AWS using AWS URLs.
Alternatively, you can override the endpoints so that the AWS SDK can communicate with alternative storage systems, such as Ceph, Minio, or LocalStack, using the system variables |
-
Ensure that the AWS CLI is installed and configured with the necessary credentials.
-
Install the AWS CLI by following the instructions in the AWS official documentation — Install the AWS CLI version 2.
-
Use
aws configure
command to set youraws_access_key_id
andaws_secret_access_key
from AWS. -
Create an S3 bucket and a directory to store the backup files using the AWS CLI:
aws s3 mb --region=us-east-1 s3://myBucket aws s3api put-object --bucket myBucket --key myDirectory/
For more information on how to create a bucket and use the AWS CLI, see the AWS official documentation — Use Amazon S3 with the AWS CLI and Use high-level (s3) commands with the AWS CLI.
-
Verify that the
~/.aws/config
is correct by running the following command:cat ~/.aws/config
The output should look like this:
[default] region=eu-north-1
-
Verify that the
~/.aws/credentials
is correct:cat ~/.aws/credentials
The output should look like this:
[default] aws_access_key_id=this.is.secret aws_secret_access_key=this.is.super.secret
-
-
Run the
neo4j-admin database restore
command to restore the database located in your AWS S3 storage:bin/neo4j-admin database restore --from-path=s3://myBucket/myDirectory/myBackup.backup 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 Designated seeder.
Restore users and roles metadata
If you have backed up a database with the option --include-metadata
, you can manually restore the users and roles 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 Cypher Shell:
Using cat
(UNIX)
cat data/scripts/databasename/restore_metadata.cypher | bin/cypher-shell -u user -p password -a ip_address:port -d system --param "database => 'databasename'"
Using type
(Windows)
type data\scripts\databasename\restore_metadata.cypher | bin\cypher-shell.bat -u user -p password -a ip_address:port -d system --param "database => 'databasename'"