Neo4j database dumps aren’t just backups; they’re a snapshot of your entire graph structure and data, making them incredibly powerful for migration.
Let’s see it in action. Imagine you have a small Neo4j instance running, and you want to move its data to a new, perhaps more powerful, server.
First, on the source server, you’ll initiate the dump. This is done using the neo4j-admin command-line tool.
neo4j-admin dump --database=neo4j --to-path=/data/dumps/my_graph_dump.db
This command tells Neo4j to create a complete, consistent snapshot of the neo4j database and store it as a single file (.db extension) in the /data/dumps/ directory. The --database flag specifies which database to dump if you have multiple. The --to-path is where the output file will be created. This process locks the database for writes briefly to ensure consistency, so plan for a short maintenance window.
Once the dump is created, you’ll transfer this .db file to your target server. This could be via scp, rsync, or any file transfer method you prefer.
On the target server, assuming you have Neo4j installed and configured, you’ll first ensure the target database is empty or that you’re okay with overwriting its contents. Then, you’ll load the dump.
neo4j-admin load --database=neo4j --from-path=/path/to/transferred/my_graph_dump.db --force
The load command reads the .db file and reconstructs the graph. The --database flag here specifies the target database name on the new instance, and --from-path points to the dump file you transferred. The --force flag is crucial; it tells Neo4j to overwrite the existing database if one with the same name already exists on the target. This is how you achieve a clean migration.
After the load completes, you restart the Neo4j service on the target machine.
sudo systemctl restart neo4j
And if all goes well, your graph data will be fully available on the new server.
The underlying mechanism is quite elegant. The dump command serializes the graph’s internal data structures – nodes, relationships, properties, and indexes – into a highly optimized binary format. This format is designed for both efficient storage and rapid deserialization. When you load, Neo4j reads this binary stream and reconstructs the database from scratch. It’s not like a SQL dump where you get text commands; it’s a direct representation of the graph’s physical layout.
What many people don’t realize is that the .db file is not a plain text file you can easily inspect or edit. It’s a proprietary binary format. While you can technically copy this file between Neo4j instances, the neo4j-admin load command is the officially supported and safest way to perform migrations, as it handles all the necessary internal consistency checks and setup. Attempting to manually copy the database directory without using neo4j-admin load is a recipe for corruption.
The next step after a successful migration is often to verify data integrity and performance tuning on the new hardware.