6.2. Perform a backup

This section describes how to perform a backup of a Neo4j database.

6.2.1. Backup commands

A Neo4j database can be backed up in online mode, using the backup command of neo4j-admin.

Syntax

neo4j-admin backup --backup-dir=<backup-path> --name=<graph.db-backup>
                    [--from=<address>] [--fallback-to-full[=<true|false>]]
                    [--pagecache=<pagecache>]
                    [--timeout=<timeout>]
                    [--check-consistency[=<true|false>]]
                    [--additional-config=<config-file-path>]
                    [--cc-graph[=<true|false>]]
                    [--cc-indexes[=<true|false>]]
                    [--cc-label-scan-store[=<true|false>]]
                    [--cc-property-owners[=<true|false>]]
                    [--cc-report-dir=<directory>]

Options

Option Default Description

--backup-dir

 

Directory to place backup in.

--name

 

Name of backup. If a backup with this name already exists an incremental backup will be attempted.

--from

localhost:6362

Host and port of Neo4j.

--fallback-to-full

true

If an incremental backup fails backup will move the old backup to <name>.err.<N> and fallback to a full backup instead.

--pagecache

8M

The size of the page cache to use for the backup process.

--timeout

20m

Timeout in the form <time>[ms|s|m|h], where the default unit is seconds. This is a debugging option that should only be used if instructed to by Neo4j Professional Services.

--check-consistency

true

If a consistency check should be made.

--additional-config

 

Configuration file to supply additional configuration in. This argument is deprecated.

--cc-graph

true

Perform checks between nodes, relationships, properties, types and tokens.

--cc-indexes

true

Perform checks on indexes.

--cc-label-scan-store

true

Perform checks on the label scan store.

--cc-property-owners

false

Perform additional checks on property ownership. This check is very expensive in time and memory.

--cc-report-dir

.

Directory where consistency report will be written.

Example 6.1. Back up a database

In this example we are taking explicit measures to control memory usage. We define the page cache using the command line option --pagecache. Further, the HEAP_SIZE environment variable will let us specify the heap size allocated to the backup.

Perform a full backup.

$neo4j-home> export HEAP_SIZE=2G
$neo4j-home> mkdir /mnt/backup
$neo4j-home> bin/neo4j-admin backup --from=192.168.1.34 --backup-dir=/mnt/backup --name=graph.db-backup --pagecache=4G
Doing full backup...
2017-02-01 14:09:09.510+0000 INFO  [o.n.c.s.StoreCopyClient] Copying neostore.nodestore.db.labels
2017-02-01 14:09:09.537+0000 INFO  [o.n.c.s.StoreCopyClient] Copied neostore.nodestore.db.labels 8.00 kB
2017-02-01 14:09:09.538+0000 INFO  [o.n.c.s.StoreCopyClient] Copying neostore.nodestore.db
2017-02-01 14:09:09.540+0000 INFO  [o.n.c.s.StoreCopyClient] Copied neostore.nodestore.db 16.00 kB
...
...
...

Now if we do a directory listing of /mnt/backup we will see that we have a backup of Neo4j called graph-db.backup.

6.2.2. Incremental backups

An incremental backup is performed whenever an existing backup directory is specified and the transaction logs are present since the last backup (see note below). The backup command will then copy any new transactions from Neo4j and apply them to the backup. The result will be an updated backup that is consistent with the current server state.

Example 6.2. Perform an incremental backup

This example assumes that we have performed a full backup as per the previous example. In the same way as before, we make sure to control the memory usage.

Perform an incremental backup: Specify the location of the previous backup.

$neo4j-home> export HEAP_SIZE=2G
$neo4j-home> bin/neo4j-admin backup --from=192.168.1.34 --backup-dir=/mnt/backup --name=graph.db-backup --fallback-to-full=true --check-consistency=true --pagecache=4G
Destination is not empty, doing incremental backup...
Backup complete.

The incremental backup will fail if the existing directory does not contain a valid backup, and --fallback-to-full=false. It will also fail if the required transaction logs have been removed and --fallback-to-full=false. Setting --fallback-to-full=true is a safeguard which will result in a full backup in case an incremental backup cannot be performed.

It is important to note that --check-consistency is true by default. For a quicker incremental backup we can set this to --check-consistency=false and --fallback-to-full=false.

When copying outstanding transactions, the server needs access to the transaction logs. These logs are maintained by Neo4j and automatically removed after a period of time, based on the parameter dbms.tx_log.rotation.retention_policy. When designing our backup strategy it is important to configure dbms.tx_log.rotation.retention_policy such that transaction logs are kept between incremental backups.

6.2.3. Exit codes

neo4j-admin backup will exit with different codes depending on success or error, and in case of error, what error was encountered.

Table 6.1. Neo4j Admin backup exit codes
Code Description

0

Success.

1

Backup failed.

2

Backup succeeded but consistency check failed.

3

Backup succeeded but consistency check found inconsistencies.