Docker maintenance operations

Basic maintenance operations when running Neo4j in a Docker container.

Dump and load a Neo4j database (offline)

The neo4j-admin dump and neo4j-admin 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 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:4.4.9 \
neo4j-admin dump --database=neo4j --to=/backups/<dump-name>.dump
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 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:4.4.9 \
neo4j-admin load --database=neo4j --from=/backups/<dump-name>.dump
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 dump and load syntax and options, see neo4j-admin dump and neo4j-admin 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_dbms_backup_enabled=true \ (4)
    neo4j:4.4.9-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 states that you have accepted the Neo4j Enterprise Edition license agreement.
4 The environment variable that enables online backups.
Example 4. Invoke neo4j-admin backup to back up an online database, using docker exec:
docker exec --interactive --tty <container name> neo4j-admin backup --backup-dir=/backups --database=<database name>
For more information on the neo4j-admin 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 node 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_dbms_backup_enabled=true \ (4)
    --env NEO4J_dbms_backup_listen__address=0.0.0.0:6362 \ (5)
    neo4j:4.4.9-enterprise
1 The dbms.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 states that you have accepted the Neo4j Enterprise Edition license agreement.
4 The environment variable that enables online backups.
5 The environment variable that sets the dbms.backup.listen_address.

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

Example 6. Invoke neo4j-admin docker image to backup your database.
docker run --interactive --tty --rm \
   --volume=$HOME/neo4j-enterprise/backups:/backups \  (1)
   --env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \ (2)
   neo4j/neo4j-admin:4.4.9-enterprise \
      neo4j-admin backup --database=<database name> \
         --backup-dir=/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 states that you have accepted the Neo4j Enterprise Edition license agreement.
3 The IP address of the backup cluster node and the dbms.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:4.4.9-enterprise
1 The volume that contains all your databases.
2 The volume that contains the database backup.
3 The environment variable that states that you have accepted 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 restore to restore a database backup.
docker exec --interactive --tty <containerID/name> neo4j-admin restore --from=/backups/<database backup name> --database=<database name>

Restore a database using neo4j-admin image

The neo4j-admin 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:4.4.9-enterprise
1 The volume that contains, or will contain, all your database data.
2 The environment variable that states that you have accepted the Neo4j Enterprise Edition license agreement.
Example 11. Stop the old database, then restore the backup database using neo4j/neo4j-admin:4.4.9-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 restore \
         --database=<database name> \
         --from=/backups/<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 database container is using.
2 The volume that contains the database backup.
3 The environment variable that states that you have accepted the Neo4j Enterprise Edition license agreement.

For more information on the neo4j-admin 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.

Upgrade Neo4j on Docker

The following is an example of a docker run command that launches a container and upgrades a Neo4j database stored in a Docker volume or a host folder.

docker run \
    --publish=7474:7474 --publish=7687:7687 \
    --volume=$HOME/neo4j/data:/data \ (1)
    --env NEO4J_dbms_allow__upgrade=true \ (2)
    neo4j:4.4.9 \(3)
1 The volume that contains the database that you want to upgrade.
2 The environment variable that enables the upgrade.
3 The new version of the Neo4j Docker image to which you want to upgrade your database.

The upgrade to a later patch release of Neo4j 4.4 is straightforward — stop the container and then restart it using the later Neo4j docker image. For more details on upgrading, see Upgrade and Migration Guide → Upgrade to a newer PATCH release.

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.

Since a docker instance is run as neo4j console, you would not normally expect to see neo4j.log in the /logs directory. However, you can still get it by running:

docker logs <containerID/name>

It is also possible to configure Neo4j to write the logs to a file by setting the configuration NEO4J_dbms_logs_user_stdout__enabled=true as an environment variable.