Standalone database backup and restore examples

This is a guide on how to backup and restore your database using an Infrahub command line tool. Please see this topic for the requirements for using the tool and an explanation of how it works.

This guide assumes that you cloned the Infrahub repository to your machine, but you can also copy the content of this tool's Python file into a local Python file and run it that way.

An alternative to avoid cloning the Infrahub repository is to directly run it through the Infrahub Docker image:

docker run --rm -v /var/run/docker.sock:/var/run/docker.sock registry.opsmill.io/opsmill/infrahub python -m utilities.db_backup

Backup a remote Infrahub database

python -m utilities.db_backup neo4j backup --database-url=172.28.64.1 /infrahub_backups

In this example, the "remote" Infrahub database is accessible at 172.28.64.1 and I want to store the generated backup files in the /infrahub_backups directory. Since the tool starts a helper container, the database may not be directly accessible from Docker depending on your network. You can try using the --host-network option:

python -m utilities.db_backup neo4j backup --host-network --database-url=172.28.64.1 /infrahub_backups

Backup a local Infrahub database with a non-default backup port

python -m utilities.db_backup neo4j backup --database-backup-port=12345 /infrahub_backups

In this example, I am running the backup command on the same machine that is running the Infrahub Docker containers. In this case, port 12345 must also have been set using the NEO4J_server_backup_listen__address environment variable in the Infrahub database container.

Restore a backup on a non-default cypher port

python -m utilities.db_backup neo4j restore /infrahub_backups --database-cypher-port=9876

In this example, I am restoring .backup files that exist in the /infrahub_backups directory and my Infrahub database container uses a non-standard port for cypher access: 9876 instead of 7687.

Cluster Database backup and restore examples

Enterprise Edition

Cluster topology

Node	Role
database	Leader
database-core2	Follower
database-core3	Follower

Context

We are going to back up the Neo4j database from database-core2 and restore it on database-core3, after having dropped the Neo4j database cluster-wide.

Important

Always run backup/restore commands as the neo4j user inside the container to avoid permission issues with the data files.

Step 1: Create backup from database-core2

docker exec -it -u neo4j infrahub-database-core2-1 bash
mkdir -p backups
neo4j-admin database backup --to-path=backups/
ls backups
# Output should include:
# neo4j-2025-03-24T19-57-18.backup

Step 2: Copy the backup to database-core3

docker cp infrahub-database-core2-1:/var/lib/neo4j/backups/neo4j-2025-03-24T19-57-18.backup \
  infrahub-database-core3-1:/var/lib/neo4j/neo4j-2025-03-24T19-57-18.backup

Step 3: drop the Neo4j database across the cluster

Connect to any node

cypher-shell -d system -u neo4j
DROP DATABASE neo4j;
SHOW SERVERS;

Step 4: Clean residual data on database-core3

Connect to the container:

docker exec -it -u neo4j infrahub-database-core3-1 bash

Remove any existing data to avoid corruption:

rm -rf /data/databases/neo4j
rm -rf /data/transactions/neo4j

Then restart the container to ensure a clean state:

docker restart infrahub-database-core3-1

Step 5: Restore the backup on database-core3

Reconnect to the container:

docker exec -it -u neo4j infrahub-database-core3-1 bash

Run the restore command:

neo4j-admin database restore \
  --from-path=/var/lib/neo4j/neo4j-2025-03-24T19-57-18.backup neo4j

Step 6: Identify the seed instance id

Connect via Cypher shell (on the system database):

cypher-shell -d system -u neo4j

Run:

SHOW SERVERS;

⚠️ Note :

Find the serverId corresponding to infrahub-database-core3-1.

For example: d05fce79-e63e-485a-9ce7-1abbf9d18fce.

Step 7: recreate the Neo4j database from the seed

Run the following Cypher command:

CREATE DATABASE neo4j
TOPOLOGY 3 PRIMARIES
OPTIONS {
  existingData: 'use',
  existingDataSeedInstance: 'd05fce79-e63e-485a-9ce7-1abbf9d18fce'
};

Step 8: Verify cluster sync

Check that the database is coming online:

SHOW DATABASES;

Then validate cluster sync status:

SHOW SERVERS;

All nodes should eventually show the Neo4j database as online.

📝 Notes

• If any node shows as dirty or offline, check the logs and ensure that the file /data/databases/neo4j/neostore exists.
• Restoring the database on a single node does not automatically register it with the cluster. You must run the CREATE DATABASE ... OPTIONS { existingData: 'use' } command to register the restored data properly.

Restore a database cluster backup on a standalone instance (for debug)

Context

We are taking a backup from a Neo4j cluster and restoring it on a standalone local Neo4j instance (non-clustered), for the purpose of debugging and data analysis in a safe, isolated environment.

Step 1: Backup from a cluster node Enterprise Edition

The backup was created from a cluster node (either follower or leader) using:

neo4j-admin database backup --to-path=backups/
# Resulting file: neo4j-2025-03-24T19-57-18.backup

Step 2: Copy the backup to database

docker cp neo4j-2025-03-24T19-57-18.backup \
  infrahub-database-1:/var/lib/neo4j/neo4j-2025-03-24T19-57-18.backup

Step 3: prepare the local Neo4j instance

Connect to the container:

docker exec -it -u neo4j infrahub-database-1 bash

Clean any existing Neo4j database (optional but recommended):

rm -rf /data/databases/neo4j
rm -rf /data/transactions/neo4j

Drop the Neo4j Database

cypher-shell -d system -u neo4j
DROP DATABASE neo4j;
SHOW SERVERS;

Step 4. Restore the backup

Run the restore command from the directory where the backup file is located:

neo4j-admin database restore \
  --from-path=/var/lib/neo4j/neo4j-2025-03-24T19-57-18.backup neo4j

Step 5: recreate the Neo4j database

Run the following Cypher command:

CREATE DATABASE neo4j

Step 6: Verify the status

Check that the database is coming online:

SHOW DATABASES;

Then validate database status:

SHOW SERVERS;

📝 Notes

• This process restores only data — not cluster roles, replication, or configuration.