Docker maintenance operations

This page describes how to perform basic maintenance operations when running Neo4j in a Docker container.

Dump and load a Neo4j database (offline)

The neo4j-admin database dump and neo4j-admin database load commands can be run locally to dump and load an offline database.

The following are examples of how to dump and load the default neo4j database. Because these commands are run on a stopped database, you have to launch a container for each operation (dump and load), with the --rm flag.

Example 1. Invoke neo4j-admin database dump to dump your database.
docker run --interactive --tty --rm \
   --volume=$HOME/neo4j/data:/data \  (1)
   --volume=$HOME/neo4j/backups:/backups \  (2)
   neo4j/neo4j-admin:5.8.0 \
neo4j-admin database dump neo4j --to-path=/backups
1 The volume that contains the database that you want to dump.
2 The volume that will be used for the dumped database.
Example 2. Invoke neo4j-admin database load to load your data into the new database.
docker run --interactive --tty --rm \
    --volume=$HOME/neo4j/data:/data \ (1)
    --volume=$HOME/neo4j/backups:/backups \ (2)
    neo4j/neo4j-admin:5.8.0 \
neo4j-admin database load neo4j --from-path=/backups
1 The volume that will contain the database, into which you want to load the dumped data.
2 The volume that stores the database dump.

Finally, you launch a container with the volume that contains the newly loaded database, and start using it.

For more information on the neo4j-admin database dump and load syntax and options, see neo4j-admin database dump and neo4j-admin database load.
For more information on managing volumes, see the official Docker documentation.

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 3. 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.8.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 4. 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 5. 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.8.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.8.0-enterprise docker image can be used to backup the database.

Example 6. 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.8.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 7. 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.8.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 8. 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 9. 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 10. 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.8.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 11. Stop the old database, then restore the backup database using neo4j/neo4j-admin:5.8.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.

Monitor Neo4j

Neo4j logging output is written to files in the /logs directory. This directory is mounted as a /logs volume.

For more information about configuring Neo4j, see Configuration.
For more information about the Neo4j log files, see Logging.