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.

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 Administrative commands.

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

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>`	Configuration file with additional configuration or override the existing configuration settings in the neo4j.conf file.
`--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.
`-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 additional state that would be inconsistent with 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 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=2023-05-01 10:15:30`, where 2023-05-01 10:15:30 is a UTC date and time. The restore recovers transactions that were committed before the provided date.
`--to-path-data=<path>`	Base directory for databases. Usage of this option is only allowed if the `--from-path` parameter points to 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 one directory.
`--verbose`	Enable verbose output.

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

Restore a database backup by running the following command. If you want to replace an existing database, add the option --overwrite-destination=true to the restore 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 can specify a comma-separated list of paths to backup artifacts.
Unless you are replacing an existing database, 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.

Restoring data up to a specific date is only possible after you drop the existing database.

Log in to the Neo4j using cypher-shell:
```
bin/cypher-shell -u neo4j -p password
```
Change the active database to system:
```
:use system;
```
Stop the database that requires the restore:
```
STOP DATABASE databasename;
```
Drop the database that requires the restore:
```
DROP DATABASE databasename;
```
Do not exit the cypher-shell session.

In a different shell terminal, 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"

The --from-path= argument must contain the path to either a full or a differential backup artifact. If you want to restore several databases at once, you can specify a comma-separated list of paths to backup artifacts. 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 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.

Using cypher-shell, recreate the database that you dropped using CREATE DATABASE against the system database, for example:
```
CREATE DATABASE databasename;
```

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

Was this page helpful?