Skip to main content

Capture an external Neo4j database directly to cloud storage

If your Neo4j servers cannot fetch a staged artifact from an object store, infrahub-backup restore has no way to seed them, and the supported round trip does not close. Neo4j Enterprise can instead write a backup straight to cloud storage itself, which gives you an artifact in your own bucket without any of the tool's machinery.

This is a manual procedure. infrahub-backup does not perform it, does not schedule it, and does not know the artifact exists. Use it when you need a backup in your bucket and cannot meet the restore prerequisites in Prepare an external database for backup and restore; use infrahub-backup create whenever you can.

What you take on​

Everything infrahub-backup normally does for you becomes yours to do:

ConcernWith infrahub-backup createDirect to cloud storage
Artifact formatSingle archive with metadata and checksumsVendor artifacts, one per database, unrelated to each other
Restoreinfrahub-backup restore finds and validates the archiveYou drive the vendor restore yourself
Both databasesNeo4j and PostgreSQL captured in one coordinated runTwo independent runs you sequence
Storage efficiency and encryptionThe plakar backend removes repeated blocks and encrypts themWhatever your bucket provides
Retention--retention-days and --retention-count prune archivesBucket lifecycle rules, written by you
CompletenessPartial captures are detected and removedYou read the command output and judge

Two of those deserve their own warning.

warning

The artifacts this procedure produces are not restorable with infrahub-backup restore. It looks for an Infrahub backup archive with its metadata, and finds neither. Plan the restore before you rely on the backup.

warning

Your two databases are captured by two separate commands, so their recovery points differ by however long you leave between them. A restore that mixes recovery points leaves Infrahub's graph and its task history disagreeing. Quiesce Infrahub around both captures, or accept and record the gap.

Prerequisites​

  • Neo4j Enterprise 2025.03 or later on the server. Writing a backup directly to cloud storage was added in that release.
  • A backup client machine on the same network as the database, with a matching Neo4j installation so neo4j-admin is available, and with local disk at least the size of the database. Writing to cloud storage still stages through local disk. The neo4j-admin in the infrahub-backup container image cannot write to cloud storage, because the image leaves out the S3, Azure and Google Cloud client libraries. Use a full Neo4j installation for this procedure.
  • The Neo4j backup service listening on a non-loopback address. This prerequisite is the same one the supported path needs — see Step 1 of the preparation guide.
  • Cloud storage credentials on the backup client, and a PostgreSQL client at least as new as your task manager database server.

Step 1: Capture Neo4j to your bucket​

From the backup client, run the vendor backup command with a cloud destination. Pass every cluster member so the capture can fall back when one is unreachable:

neo4j-admin database backup \
--from=neo4j-a.example.internal:6362,neo4j-b.example.internal:6362 \
--to-path=s3://my-infrahub-backups/manual \
neo4j

Check the vendor documentation for your release before you script this. The flags and the supported destination schemes belong to Neo4j, not to Infrahub, and they change between releases.

Step 2: Capture the task manager database​

Infrahub's task history lives in PostgreSQL and is not covered by the command above. Take a custom-format dump, which restores into the same or a later major version:

pg_dump --format=custom --no-owner \
--host task-manager-db.example.internal \
--username prefect \
--dbname prefect \
--file prefect-$(date -u +%Y%m%dT%H%M%SZ).dump

Upload the dump beside the Neo4j artifact, using whichever client your storage provider supports.

Step 3: Verify what you captured​

The backup command's exit status is not enough. Exit code 1 means either that the backup failed or that it succeeded while some servers were unreachable, and there is no exit code that separates the two. Passing several members makes the second case more likely, not less.

Read the command's own output for servers it could not reach, then confirm the objects landed:

aws s3 ls s3://my-infrahub-backups/manual/ --recursive --human-readable

Record the timestamp of each artifact and which endpoint served it. Nothing else does this for you, and a recovery point you cannot state is not a recovery point.

Step 4: Plan and rehearse the restore​

Decide the restore route now, while the databases are healthy, and rehearse it against a disposable database:

  • If your servers can reach the bucket by the time you restore, seed from the artifact with CREATE OR REPLACE DATABASE ... OPTIONS { existingData: 'use', seedURI: '...' }. That is the path infrahub-backup restore automates, so at that point you no longer need this procedure.
  • If they cannot, restore on the server itself with the vendor restore command, which needs filesystem access to the server's store directory. dbms.recreateDatabase() is a further Cypher-level route the vendor documents for both standalone and clustered servers.
  • Restore the PostgreSQL dump with pg_restore against your task manager database.
warning

Whichever route you take, confirm the database came online. A seed is downloaded and validated when the database starts, not when the statement returns, so a failed fetch leaves the database offline with a statusMessage of Unable to start database rather than failing the statement. Check SHOW DATABASES for currentStatus and statusMessage before you call the restore done.

Returning to the supported path​

This procedure is a stopgap, and the gap it covers is narrow: your Neo4j servers cannot reach an object store, or lack the provider tooling and credentials to fetch from one. Once either is arranged, infrahub-backup create and infrahub-backup restore handle the whole round trip, with metadata, checksums, retention and a restore that verifies the database came online. Revisit the prerequisites in Prepare an external database for backup and restore when your database estate changes.