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 txLogEnrichment value and in your CDC application, handle the potential loss or corruption of CDC data, see Change Data Capture Manual → Restore backups and snapshots.

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>] [--temp-path=<path>]
                             [--to-path-data=<path>] [--to-path-txn=<path>]
                              [<database>]

Parameters

Table 1. neo4j-admin database restore parameters
Parameter Description

[<database>]

Name of the database after restore. Usage of this parameter is only allowed if the --from-path option points to a path to a single artifact.

Options

Table 2. neo4j-admin database restore options
Option Description Default

--additional-config=<file>[1]

Configuration file with additional configuration.

--expand-commands

Allow command expansion in config value evaluation.

--from-path=<path>[,<path>…​]

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. It is possible to restore backups from AWS S3 buckets, Google Cloud storage buckets, and Azure buckets using the appropriate URI as the path.

-h, --help

Show this help message and exit.

--overwrite-destination[=true|false]

If an existing database should be replaced.

This option is not safe on a cluster since clusters have an additional state that would be inconsistent with the restored database. In a cluster, restore to a new database to avoid this problem.

false

--restore-until=<recovery-criteria>

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: <transactionID> and <timestamp>.

  • to restore a database up to a transaction ID, the required transaction predicate should look like --restore-until=123, where 123 is the provided transaction ID. The restore recovers transaction logs up to, but not including, the transaction 123.

  • to restore a database up to a specific date, the required date predicate should look like --restore-until=2021-09-11 10:15:30, where 2021-09-11 10:15:30 is a UTC date and time. The restore recovers transactions that were committed before the provided timestamp.

--to-path-data=<path>

Base directory for databases. Usage of this option is only allowed if the --from-path parameter points to exactly one directory.

--to-path-txn=<path>

Base directory for transaction logs. Usage of this option is only allowed if the --from-path parameter points to exactly one directory.

--temp-path=<path>

Introduced in 5.24 Provide a path to a temporary empty directory for storing backup files until the command is completed. The files will be deleted once the command is finished.

--verbose

Enable verbose output.

1. See Tools → Configuration for details.

The --from-path=<path> option can also load backups from AWS S3 buckets (from Neo4j 5.19), Google Cloud storage buckets (from Neo4j 5.21), and Azure buckets (from Neo4j 5.24). For more information, see Restore a backup located in a cloud storage.

Neo4j 5.24 introduces the --temp-path option to address potential issues related to disk space when performing backup-related commands, especially when cloud storage is involved.

If --temp-path is not set, a temporary directory is created inside the directory specified by the --from-path option.

If you don’t provide the --from-path option or if your provided path points to a cloud storage bucket, a temporary folder is created inside the current working directory for Neo4j. This fallback option can cause issues because the local filesystem (or the partition where Neo4j is installed) may not have enough free disk to accommodate the intermediate computation.

Therefore, it is strongly recommended to provide a --temp-path option.

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
Example output
|                                                       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

  1. 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 <database> parameter. You should also skip the CREATE DATABASE step afterward if you are replacing an existing database.

  2. Create the new database using CREATE DATABASE against the system 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.

  1. 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 the CREATE 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.

  2. Create the new database using CREATE DATABASE against the system database:

    CREATE DATABASE mydatabase;

Restore a backup located in a cloud storage

The following examples show how to restore a database located in a cloud storage bucket using the --from-path option.

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 aws.endpointUrls3, aws.endpointUrlS3, or aws.endpointUrl, or the environments variables AWS_ENDPOINT_URL_S3 or AWS_ENDPOINT_URL.

  1. Install the AWS CLI by following the instructions in the AWS official documentation — Install the AWS CLI version 2.

  2. 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.

  3. Verify that the ~/.aws/config file is correct by running the following command:

    cat ~/.aws/config

    The output should look like this:

    [default]
region=us-east-1

  4. Configure the access to your AWS S3 bucket by setting the aws_access_key_id and aws_secret_access_key in the ~/.aws/credentials file and, if needed, using a bucket policy. For example:

    1. Use aws configure set aws_access_key_id aws_secret_access_key command to set your IAM credentials from AWS and 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

    2. Additionally, you can use a resource-based policy to grant access permissions to your S3 bucket and the objects in it. Create a policy document with the following content and attach it to the bucket. Note that both resource entries are important to be able to download and upload files.

      {
    "Version": "2012-10-17",
    "Id": "Neo4jBackupAggregatePolicy",
    "Statement": [
        {
            "Sid": "Neo4jBackupAggregateStatement",
            "Effect": "Allow",
            "Action": [
                "s3:ListBucket",
                "s3:GetObject",
                "s3:PutObject",
                "s3:DeleteObject"
            ],
            "Resource": [
                "arn:aws:s3:::myBucket/*",
                "arn:aws:s3:::myBucket"
            ]
        }
    ]
}

  5. Run the neo4j-admin database restore command to restore the database located in your AWS S3 storage. The example assumes that you have backup artifacts located in the myBucket/myDirectory folder in your bucket.

    bin/neo4j-admin database restore --from-path=s3://myBucket/myDirectory/myBackup.backup mydatabase

  1. Ensure you have a Google account and a project created in the Google Cloud Platform (GCP).

    1. Install the gcloud CLI by following the instructions in the Google official documentation — Install the gcloud CLI.

    2. Create a service account and a service account key using Google official documentation — Create service accounts and Creating and managing service account keys.

    3. Download the JSON key file for the service account.

    4. Set the GOOGLE_APPLICATION_CREDENTIALS and GOOGLE_CLOUD_PROJECT environment variables to the path of the JSON key file and the project ID, respectively:

      export GOOGLE_APPLICATION_CREDENTIALS="/path/to/keyfile.json"
export GOOGLE_CLOUD_PROJECT=YOUR_PROJECT_ID

    5. Authenticate the gcloud CLI with the e-mail address of the service account you have created, the path to the JSON key file, and the project ID:

      gcloud auth activate-service-account service-account@example.com --key-file=$GOOGLE_APPLICATION_CREDENTIALS --project=$GOOGLE_CLOUD_PROJECT

      For more information, see the Google official documentation — gcloud auth activate-service-account.

    6. Create a bucket in the Google Cloud Storage using Google official documentation — Create buckets.

    7. Verify that the bucket is created by running the following command:

      gcloud storage ls

      The output should list the created bucket.

  2. Run the neo4j-admin database restore command to restore the database located in a given folder in your Google storage bucket. The example assumes that you have backup artifacts located in the myBucket/myDirectory folder in your bucket.

    bin/neo4j-admin database restore --to-path=gs://myBucket/myDirectory/myBackup.backup mydatabase

  1. Ensure you have an Azure account, an Azure storage account, and a blob container.

    1. You can create a storage account using the Azure portal.
      For more information, see the Azure official documentation on Create a storage account.

    2. Create a blob container in the Azure portal.
      For more information, see the Azure official documentation on Quickstart: Upload, download, and list blobs with the Azure portal.

  2. Install the Azure CLI by following the instructions in the Azure official documentation — Azure official documentation.

  3. Authenticate the neo4j or neo4j-admin process against Azure using the default Azure credentials.
    See the Azure official documentation on default Azure credentials for more information.

    az login

    Then you should be ready to use Azure URLs in either neo4j or neo4j-admin.

  4. To validate that you have access to the container with your login credentials, run the following commands:

    # Upload a file:
az storage blob upload --file someLocalFile  --account-name accountName - --container someContainer --name remoteFileName  --auth-mode login

# Download the file
az storage blob download  --account-name accountName --container someContainer --name remoteFileName --file downloadedFile --auth-mode login

# List container files
az storage blob list  --account-name someContainer --container someContainer  --auth-mode login

  5. Run the neo4j-admin database restore command to restore the database located in a given folder in your Azure blob storage container. The example assumes that you have backup artifacts located in the myStorageAccount/myContainer/myDirectory folder.

    bin/neo4j-admin database restore --to-path=azb://myStorageAccount/myContainer/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'"