Similar to restoration requirements for user databases, it might be required to recover or restore the system database, using online or offline backups. This article aims at demonstrating the process of performing an offline dump and load for the system database in a Neo4j Docker environment, applicable for Neo4j 4.4.x and 5.x versions.

Following is a step-by-step demonstration of such offline backup and restore process.

1. Initialise a neo4j 4.x container e.g. as:

~ %docker run --name neo4j \
-p7474:7474 -p7687:7687 \
-d \
-v /Users/harry_qiu/neo4j/data:/data \
-v /Users/harry_qiu/neo4j/logs:/logs \
-v /Users/harry_qiu/neo4j/import:/import \
-v /Users/harry_qiu/neo4j/backups:/backups \
-v /Users/harry_qiu/neo4j/plugins:/plugins \
--env NEO4J_AUTH=neo4j/password \
--env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \
neo4j:4.4.15-enterprise

 
2. Access the system database via cypher-shell as “docker exec --interactive --tty <containerID/name> cypher-shell <options>” e.g:

~ % docker exec -it neo4j cypher-shell -u neo4j -p password -d system

 where “neo4j” is the container name and the database name is “system”. 

3. Create two users e.g. 'harry' and 'mary' in the neo4j dbms via cypher-shell, with privileges to modify the system database.

neo4j@system> show users;
+---------------------------------------------------------------------------+
| user | roles | passwordChangeRequired | suspended | home |
+---------------------------------------------------------------------------+
| "neo4j" | ["admin", "PUBLIC"] | FALSE | FALSE | NULL |
+---------------------------------------------------------------------------+

1 row
neo4j@system> create user harry set password 'harry123' change not required;
0 rows
neo4j@system> create user mary set password 'mary123' change not required;
0 rows
neo4j@system> show users;
+---------------------------------------------------------------------------+
| user | roles | passwordChangeRequired | suspended | home |
+---------------------------------------------------------------------------+
| "harry" | ["PUBLIC"] | FALSE | FALSE | NULL |
| "mary" | ["PUBLIC"] | FALSE | FALSE | NULL |
| "neo4j" | ["admin", "PUBLIC"] | FALSE | FALSE | NULL |
+---------------------------------------------------------------------------+

4. Stop the neo4j container and perform an offline backup of the system database via a separate neo4j-admin tools container, which should use the same volume mounts as the neo4j container:

~ %docker stop neo4j
~ % docker run --interactive --tty --rm \
-v /Users/harry_qiu/neo4j/data:/data \
-v /Users/harry_qiu/neo4j/backups:/backups \
--env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \
neo4j/neo4j-admin:4.4.15-enterprise \
neo4j-admin dump --database=system --to=/backups/system.dump
Selecting JVM - Version:11.0.17+8, Name:OpenJDK 64-Bit Server VM, Vendor:Eclipse Adoptium
Done: 78 files, 251.1MiB processed.

 
5. List contents of the /backups volume:

~ % ls -l /Users/harry_qiu/neo4j/backups
total 48
-rw-r--r-- 1 harry_qiu staff 23419 Mar 16 13:55 system.dump

 An offline backup of the system database has thus been successfully completed.

6. Drop the two newly created users 'harry' and 'mary' as these shall no longer be required

~ %docker start neo4j
~ % docker exec -it neo4j cypher-shell -u neo4j -p password -d system
neo4j@system> drop user harry;
0 rows
neo4j@system> drop user mary;
0 rows
neo4j@system> show users;
+---------------------------------------------------------------------------+
| user | roles | passwordChangeRequired | suspended | home |
+---------------------------------------------------------------------------+
| "neo4j" | ["admin", "PUBLIC"] | FALSE | FALSE | NULL |
+---------------------------------------------------------------------------+

 

7. A test restore of the offline backup performed in step 4, may then be performed, to recover the two users deleted in step 6:

a)- Stop neo4j container

~ %docker stop neo4j

b)- Initialise the neo4j-admin tools container to load the system database dump file, created in step4. As before, the “neo4j-admin tools” container should use the same mounts as the “neo4j” container.

~ %docker run --interactive --tty --rm \
-v /Users/harry_qiu/neo4j/data:/data \
-v /Users/harry_qiu/neo4j/backups:/backups \
--env NEO4J_ACCEPT_LICENSE_AGREEMENT=yes \
neo4j/neo4j-admin:4.4.15-enterprise \
neo4j-admin load --database=system --from=/backups/system.dump 

Selecting JVM - Version:11.0.17+8, Name:OpenJDK 64-Bit Server VM, Vendor:Eclipse Adoptium
Done: 78 files, 251.1MiB processed.

 Note: The neo4j-admin load command used above, includes the “--force” option, to override the existing system database.
 

8. Verify restoration of the previously dropped users, on the now restored, system database.

~ % docker exec -it neo4j cypher-shell -u neo4j -p password -d system
neo4j@system> show users;
+---------------------------------------------------------------------------+
| user | roles | passwordChangeRequired | suspended | home |
+---------------------------------------------------------------------------+
| "harry" | ["PUBLIC"] | FALSE | FALSE | NULL |
| "mary" | ["PUBLIC"] | FALSE | FALSE | NULL |
| "neo4j" | ["admin", "PUBLIC"] | FALSE | FALSE | NULL |
+---------------------------------------------------------------------------+

 As evident above, the previously two dropped users “harry” and “mary” had been recovered by the restoration.

​​​​​​​​​​​​​​Notes:

• For Neo4j version 5.x, ensure to initialise the docker containers, using the appropriate image name, e.g. “neo4j:5.5.0” in place of “neo4j:4.4.15” used in the example above.
• The dump and load commands in Neo4j version 5.x are as follows:

neo4j-admin database dump system --overwrite-destination=true --to-path=/backups/system

neo4j-admin database load --from-path=/backups/system system --overwrite-destination=true

References:

https://neo4j.com/docs/operations-manual/4.4/docker/maintenance/#docker-neo4j-dump

https://neo4j.com/docs/operations-manual/5/docker/maintenance/#docker-neo4j-dump