Back up an offline database

Remember to plan your backup carefully and back up each of your databases, including the system database.

Command

The neo4j-admin database dump command can be used for performing a full backup of an offline database. It dumps a database into a single-file archive, called <database>.dump, and stores it in the <NEO4J_HOME>/data directory. Alternatively, neo4j-admin database dump can stream dump to standard output, enabling the output to be piped to another program, for example to neo4j-admin database load.

If the database is hosted in a cluster, make sure that the database is stopped on the server you are connected to. The command can be run only locally from an online or an offline Neo4j DBMS. It does not support SSL/TLS.

Syntax

neo4j-admin database dump [-h] [--expand-commands]
                          [--verbose] [--overwrite-destination[=true|false]]
                          [--additional-config=<file>]
                          [--to-path=<path> | --to-stdout]
                          <database>

Description

Dump a database into a single-file archive. The archive can be used by the load command. <to-path> should be a directory (in which case a file called <database>.dump will be created), or --to-stdout can be supplied to use standard output. If neither --to-path or --to-stdout is supplied server.directories.dumps.root setting will be used as a destination. It is not possible to dump a database that is mounted in a running Neo4j server.

Parameters

Table 1. neo4j-admin database dump parameters
Parameter Description

<database>

Name of the database to dump. Can contain * and ? for globbing. Note that * and ? have special meaning in some shells and might need to be escaped or used with quotes.

Options

The neo4j-admin database dump command has the following options:

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

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

Configuration file with additional configuration.

--expand-commands

Allow command expansion in config value evaluation.

-h, --help

Show this help message and exit.

--overwrite-destination[=true|false]

Overwrite any existing dump file in the destination folder.

false

--to-path=<path>

Destination folder of a database dump. It is possible to dump databases into AWS S3 buckets, Google Cloud storage buckets, and Azure buckets using the appropriate URI as the path.

--to-stdout

Use standard output as the destination for the database dump.

--verbose

Enable verbose output.

1. See Tools → Configuration for details.

The --to-path=<path> option can also dump databases into 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 Dump a database to a folder located in a cloud storage.

Examples

The following examples show how to dump a database using the neo4j-admin database dump command. The command creates a file called database.dump where database is the database specified in the command.

neo4j-admin database dump cannot be applied to Composite databases. It must be run directly on the databases that are associated with that Composite database.

Dump the default database neo4j to a local directory

You can use the following command to create a dump of the default database neo4j in a local directory. The target directory must exist before running the command and the database must be offline.

bin/neo4j-admin database dump neo4j --to-path=/full/path/to/dumps

Dump a database to a folder located in a cloud storage

The following examples show how to dump a database to a cloud storage bucket using the --to-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 neo4j-admin database dump command to dump your database into your AWS S3 bucket:

    bin/neo4j-admin database dump mydatabase --to-path=s3://myBucket/myDirectory/

  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 neo4j-admin database dump command to dump your database into your Google bucket:

    bin/neo4j-admin database dump mydatabase --to-path=gs://myBucket/myDirectory/

  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 neo4j-admin database dump command to dump your database into your Azure container:

    bin/neo4j-admin database dump mydatabase --to-path=azb://myStorageAccount/myContainer/myDirectory/