Back up and restore a Neo4j database (online)

The Neo4j backup and restore commands can be run locally to backup and restore a live database.

You can also get a neo4j-admin image that can be run on a dedicated machine, under the terms of an existing Enterprise licensing agreement.

If Neo4j (a single instance or any member of a Neo4j cluster) is running inside a Docker container, you can use docker exec to invoke neo4-admin from inside the container and take a backup of a database.

Back up a database using docker exec

To back up a database, you must first mount the host backup folder onto the container. Because Docker does not allow new mounts to be added to a running container, you have to do this when starting the container.

Example 1. A docker run command that mounts the host backup folder to a Neo4j container.
docker run --name <container name> \
    --detach \
    --publish=7474:7474 --publish=7687:7687 \
    --volume=$HOME/neo4j-enterprise/data:/data \ (1)
    --volume=$HOME/neo4j-enterprise/backups:/backups \ (2)
    --user="$(id -u):$(id -g)" \
    --env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \ (3)
    --env NEO4J_server_backup_enabled=true \ (4)
    neo4j:5.26.0-enterprise
1 The volume that contains the database that you want to back up.
2 The volume that will be used for the database backup.
3 The environment variable that accepts the Neo4j Enterprise Edition license agreement.
4 The environment variable that enables online backups.
Example 2. Invoke neo4j-admin database backup to back up an online database, using docker exec:
docker exec --interactive --tty <container name> neo4j-admin database backup --to-path=/backups <database name>

For more information on the neo4j-admin database backup syntax and options, see Back up an online database.

Back up a database using neo4j-admin image

To perform a backup, the cluster needs at least one server with backup enabled and the backup listen address port set and exposed. Ports cannot be exposed on a Docker container once it has started, so this must be done when starting the container.

Example 3. A docker run command that starts a database configured for backing up.
docker run \
    --detach \
    --publish=7474:7474 \
    --publish=7687:7687 \
    --publish=6362:6362 \ (1)
    --volume=$HOME/neo4j-enterprise/data:/data \ (2)
    --env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \ (3)
    --env NEO4J_server_backup_enabled=true \ (4)
    --env NEO4J_server_backup_listen__address=0.0.0.0:6362 \ (5)
    neo4j:5.26.0-enterprise
1 The server.backup.listen_address port defined in 5.
2 The volume that contains the database that you want to back up.
3 The environment variable that accepts the Neo4j Enterprise Edition license agreement.
4 The environment variable that enables online backups.
5 The environment variable that sets the server.backup.listen_address.

Once you have a backup enabled cluster node, the neo4j/neo4j-admin:5.26.0-enterprise docker image can be used to backup the database.

Example 4. Invoke neo4j-admin docker image to back up your database.
docker run --interactive --tty --rm \
   --volume=$HOME/neo4j-enterprise/backups:/backups \  (1)
   --env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \ (2)
   neo4j/neo4j-admin:5.26.0-enterprise \
      neo4j-admin database backup <database name> \
         --to-path=/backups \
         --from=<backup node IP address>:6362 (3)
1 The volume that will be used for the backup database files.
2 The environment variable that accepts the Neo4j Enterprise Edition license agreement.
3 The IP address of the backup cluster node and the server.backup.listen_address port.

Restore a database using docker exec

The following are examples of how to restore a database backup on a stopped database in a running Neo4j instance.

Example 5. A docker run command that creates a container to be used for restoring a database backup.
docker run --name <container name> \
    --detach \
    --publish=7474:7474 --publish=7687:7687 \
    --volume=$HOME/neo4j-enterprise/data:/data \ (1)
    --volume=$HOME/neo4j-enterprise/backups:/backups \ (2)
    --user="$(id -u):$(id -g)" \
    --env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \ (3)
    neo4j:5.26.0-enterprise
1 The volume that contains all your databases.
2 The volume that contains the database backup.
3 The environment variable that accepts the Neo4j Enterprise Edition license agreement.
Example 6. Invoke cypher-shell to stop the database that you want to use for the backup restore.
docker exec -it <containerID/name> cypher-shell -u neo4j -p <my-password> -d system "stop database <database name>;"
Example 7. Invoke neo4j-admin database restore to restore a database backup.
docker exec --interactive --tty <containerID/name> neo4j-admin database restore --from=/backups/<databasename>-<timestamp>.backup --overwrite-destination <database name>

Restore a database using neo4j-admin image

The neo4j-admin database restore action cannot be performed remotely, as it requires access to the neo4j /data folder. Consequently, backup files must be copied over to the new machine prior to a restore, and the neo4j-admin docker image must be run on the same machine as the database to be restored.

Example 8. A docker run command that creates a container to be used for restoring a database backup.
docker run --name <container name> \
    --detach \
    --volume=$HOME/neo4j-enterprise/data:/data \ (1)
    --env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \ (2)
    neo4j:5.26.0-enterprise
1 The volume that contains, or will contain, all your database data.
2 The environment variable accepts the Neo4j Enterprise Edition license agreement.
Example 9. Stop the old database, then restore the backup database using neo4j/neo4j-admin:5.26.0-enterprise. Finally start the database again containing the new data.
docker exec -it <containerID/name> cypher-shell -u neo4j -p <my-password> -d system "stop database <database name>;"
docker run --interactive --tty --rm \
   --volume=$HOME/neo4j-enterprise/data:/data \ (1)
   --volume=$HOME/neo4j-enterprise/backups:/backups \  (2)
   --env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \ (3)
   neo4j/neo4j-admin:{neo4j-version-exact}-enterprise \
      neo4j-admin database restore \
         --from=/backups/<databasename>-<timestamp>.backup \
         --overwrite-destination \
          <database name> \
docker exec -it <containerID/name> cypher-shell -u neo4j -p <my-password> -d system "start database <database name>;"
1 The volume that contains, or will contain, all your database data. This must be the same data folder that the Neo4j DBMS container is using.
2 The volume that contains the database backup.
3 The environment variable that accepts the Neo4j Enterprise Edition license agreement.

For more information on the neo4j-admin database restore syntax and options, see Restore a database backup.

Finally, you can use the Cypher Shell tool to verify that your data has been restored.