Restore a database backup

This section describes how to restore a database backup or an offline database in a live Neo4j deployment.

1. Command

A database backup or an offline database can be restored using the restore command of neo4j-admin. 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 restore must be invoked as the neo4j user to ensure the appropriate file permissions. For more information, see Administrative commands.

If the --prepare-restore option is disabled when backing up your database, you must first perform the neo4j-admin prepare-restore command before you can restore your database. This is to apply the latest transactions pulled at the backup time but not yet applied to the store. For more information, see Prepare a database for restoring.

1.1. Syntax

neo4j-admin restore  --from=<path>[,<path>...]
                    [--verbose]
                    [--expand-commands]
                    [--database=<database>]
                    [--force]
                    [--move]
                    [--to-data-directory=<path>]
                    [--to-data-tx-directory=<path>]

1.2. Options

Option Default Description

--from

A path or multiple paths to the database backup(s) for restore.
A path can contain asterisks or question marks in the last subpath but must not contain commas. Commas are used to separate multiple paths.

--verbose

Enable verbose output.

--expand-commands

Allow command expansion in config value evaluation.

--database

neo4j

Name for the restored database.

--force

Replace an existing database.

--move

Move the backup files to the destination, rather than copying.

--to-data-directory

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

--to-data-tx-directory

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

2. Example

The following is an example of how to perform an online restore of the database backup created in the section Back up an online database, using the neo4j-admin restore command.

bin/neo4j-admin restore --from=/mnt/backups/neo4j --database=neo4j --force

Unless you are replacing an existing database, you must create the database (using CREATE DATABASE against the system database) after the restore operation finishes.

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 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'"

For a detailed example on how to back up and restore a database in a Causal cluster, see Back up and restore a database in Causal Cluster.