Restore a database backup

Command

A database backup artifact 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 database restore must be invoked as the neo4j user to ensure the appropriate file permissions. For more information, see Administrative commands.

When restoring a backup chain, the transaction log contained in the differential backup artifacts need first to 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    --from-path=<path>[,<path>...]
                                [--overwrite-destination=<true/false>]
                                [--restore-until=<recoveryCriteria>]
                                [--to-path-data=<path>]
                                [--to-path-txn=<path>]
                                [--verbose]
                                [--expand-commands]
                                [--force]
                                <database>

Options

Option Default Description

Option	Default	Description
`--from-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.
`--overwrite-destination`		Replace an existing database. This option is not safe on a cluster since clusters have additional state that would be inconsistent with restored database. In a cluster, restore to a new database to avoid this problem.
`--restore-until`		Differential backup artifacts contains 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: `<transaction>` and `<date>`. to restore a database up to a transaction id, the required transaction predicate should look like: `--restore-until=123`, where 123 is a provided transaction id. The restore recovers transaction logs up to - but not including - 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 n2021-09-11 10:15:30 is a UTC date. The restore recovers transactions that were committed before the provided date.
`--to-path-data`		Base directory for databases. Usage of this option is only allowed if the `--from-path` parameter points to one directory.
`--to-path-txn`		Base directory for transaction logs. Usage of this option is only allowed if the `--from-path` parameter points to one directory.
`--verbose`		Enable verbose output.
`--expand-commands`		Allow command expansion in config value evaluation.
`--additional-config`		Configuration file to provide additional or override the existing configuration settings in the neo4j.conf file.

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

--overwrite-destination

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

--restore-until

Differential backup artifacts contains 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: <transaction> and <date>.

to restore a database up to a transaction id, the required transaction predicate should look like: --restore-until=123, where 123 is a provided transaction id. The restore recovers transaction logs up to - but not including - 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 n2021-09-11 10:15:30 is a UTC date. The restore recovers transactions that were committed before the provided date.

--to-path-data

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

--to-path-txn

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

--verbose

Enable verbose output.

--expand-commands

Allow command expansion in config value evaluation.

--additional-config

Configuration file to provide additional or override the existing configuration settings in the neo4j.conf file.

Parameters

Parameter Default Description

Parameter	Default	Description
`<database>`		Name for the restored database.

<database>

Name for the restored database.

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 database restore command.

bin/neo4j-admin database restore --from-path=/mnt/backups/neo4j-2021-11-05T11-26-38.backup --overwrite-destination neo4j

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

Was this page helpful?