Backup and restore
Portable, cryptographically verifiable backups. Online capture, offline restore, and integrity refuse on any file drift. The same shape is available on managed cloud and on self-hosted deployments.
Contents
Guarantees at a glance
Online capture
Writer stays online during backup. Concurrent reads continue against the checkpointed view.
Cryptographic lineage
Every archive ships a manifest that hashes every file the archive should restore to.
Integrity refuse
Restore fails hard on any file drift. There is no "restore with a warning" path.
Full audit trail
The append-only history log is included, so the bitemporal audit chain survives restore end-to-end.
Managed cloud
On managed cloud, backups run for you. The signup tier and pricing page describe the current cadence and retention window; the shape below is what the platform commits to regardless of tier.
Trigger a backup from the dashboard
Open the graph, click Backups, and click Take backup now. The archive appears in the list when it lands in object storage. Each entry shows the point-in-time timestamp, the archive size, and the lineage hash.
Trigger a backup over the API
The endpoint below is the same on managed cloud and on self-host. On managed cloud, output_path is optional — if you omit it the archive is written to the managed backup store and returned in the list of managed archives. If you pass a presigned_put_url, the archive is streamed straight into your own bucket.
Self-host
On self-host you own where the archives land. The engine exposes one endpoint for backup and one for restore. Both are authenticated as admin operations.
POST /graphs/{name}/backup
Takes a live graph and writes a portable archive. The writer stays online; a short flush checkpoint captures a consistent view of the graph, then the archive streams out while ordinary reads continue against the checkpointed state.
Request body — JSON:
Response — JSON on success, HTTP 200:
Archive shape. The archive is a gzipped tar stream. It contains:
- The current published snapshot — the immutable point-in-time view of the graph as of
captured_at. - Every prior snapshot the current snapshot depends on for its hardlink chain (see Snapshot chain).
- The full history log — the append-only bitemporal audit trail (see Bitemporal history is included).
- Any pending durability frames not yet folded into the snapshot, so restore reproduces the exact state at
captured_at. - The lineage manifest — a signed list of every file in the archive with its expected content hash.
- Schema, index definitions, per-graph configuration, and the embeddings registry needed to reopen the graph.
The archive is portable. It can be moved between machines, uploaded to cold storage, or restored into a different self-host deployment or into managed cloud — the format does not depend on the machine that produced it.
POST /graphs/{name}/restore
Restore is offline for the target graph name and creates a new graph. It refuses if the target name already exists, so you cannot silently clobber a live graph. To restore over an existing graph, restore under a new name first and then swap.
Request body — JSON:
Response — JSON on success, HTTP 200:
What restore does. The engine walks every file in the archive, re-hashes it, and compares against the lineage manifest. Any mismatch is a hard error and the graph will not open. Once the archive verifies, any in-flight recovery frames present in the archive replay automatically, so the graph opens at exactly the state the backup captured.
Failure modes are typed. If the archive is truncated, if the lineage manifest is missing, if a file hash drifts, or if the target name already exists, the response is a stable, subcoded error. Callers can branch on the subcode without parsing English strings; see the Cypher reference and stable error contract.
Bitemporal history is included
InvariantDB is a bitemporal database. Every write records both when it was true (valid time) and when the system learned about it (recorded time). That history lives in an append-only log inside the graph. It is the source of truth for AT VALID, AT RECORDED, and OVER VALID BETWEEN queries, and for tamper-evident audit chain verification.
Every archive contains the full history log. Restore reproduces the full audit trail end-to-end — not just the current snapshot. After a restore:
AT VALIDandAT RECORDEDqueries return the same answers they returned before the backup was taken.db.verifyAclChainre-verifies the audit chain over the restored state; the entry count is identical to the pre-restore chain for the same range of history.db.beliefLineagewalks every belief chain in the archive with no truncation.
An archive that would not reproduce the audit chain byte-for-byte is refused at write time, so a corrupt archive never reaches your object store.
AT VALID and AT RECORDED. Backup + restore is the durability substrate underneath. You do not need to restore an old archive to see what the graph looked like last Tuesday — you query the live graph with AT RECORDED <last Tuesday>. See Bitemporal.
Snapshot chain
The graph on disk is a chain of immutable, versioned snapshots. Each snapshot is a full point-in-time view. Between snapshots, the engine reuses unchanged data across versions so on-disk footprint stays compact even as history grows.
A backup archive preserves that chain end-to-end. Every archive is a full, self-contained point-in-time snapshot — not a delta against a previous archive. Two consequences for operators:
- Any one archive can restore the graph. You never need to hold a chain of archives to reconstruct a point in time. Nightly archive N is sufficient by itself.
- Archive size grows with history, not with snapshot count. The archive holds the union of unique content across the chain, not one copy per snapshot.
Restore reconstructs the chain on the target machine, then opens the graph against the current snapshot. Prior snapshots remain readable, so any AT RECORDED query that ran before the backup runs against the restored graph too.
Encryption at rest
On managed cloud, every archive is encrypted at rest with a per-account key managed by the platform. Encryption is transparent — the archive is decrypted when you initiate a restore, and never leaves the platform in cleartext.
On self-host, encryption at rest is the operator's responsibility for the archive itself. The engine writes the archive to output_path; wrap that path in an encrypted volume, encrypted object storage, or a pre-signed upload to an encrypted bucket, and encryption at rest is covered.
Cryptographic erasure — the GDPR Article 17 mechanism where a subject's data becomes unrecoverable across every archive by destroying the per-subject wrapping key — applies to backups by design. Once db.destroySubjectKey runs, that subject's encrypted properties are irrecoverable in every archive that was written before or after the destruction, without touching the archives themselves. See Crypto-shred.
Retention
Retention is a policy on the archive index. There are three ways to set it:
- Per-tier default. Managed cloud tiers ship with a default retention window applied to nightly automated archives. See the pricing page for the current windows.
- Per-graph override. Override retention on a specific graph in the dashboard, or via configuration on self-host. This is the right knob for a graph with legal-hold or contractual retention requirements.
- Support-managed extension. Manual backups have no automatic expiry — they persist until you delete them. To pin a specific archive against tier-default expiry, ask support to flag it.
Retention on self-host is entirely operator-controlled — the engine writes archives to the path you specify and never deletes them.
Cross-region disaster recovery
What is available today:
- Cross-region archive storage. Managed cloud archives can be replicated to a second region on request. The archives are portable; restoring in a second region is the ordinary restore path with the archive path pointing at the second-region object store.
- Cross-region reader replicas. The high-availability cluster can layer bounded-staleness reader replicas in remote regions. Combined with cross-region archive storage, that covers the reader-side of a cross-region failover.
- Writer failover across regions is a per-contract topology — not a checkbox — because the correct write-quorum and consistency guarantees depend on your data-residency requirements. Ask.
Backup + restore + verify roundtrip
End-to-end example against a self-host deployment. The same shape works against managed cloud — substitute your endpoint and API key.
1. Take a backup
The response reports the bytes written. The archive itself carries the lineage manifest as its verification anchor.
2. Restore under a new name
A 200 with a returned current_snapshot_seq means every file in the archive re-hashed to the value in the lineage manifest and the graph is open at that snapshot. Any drift is a hard error; the graph is not created.
3. Verify the restored graph
Step 2 already did this. The engine walked every file in the archive, re-hashed it against the lineage manifest, and refused to publish the graph if any file drifted. A 200 on /restore means integrity verified end-to-end. For an ongoing check, schedule a restore-into-scratch on a cadence that matches your RPO — the restore path is the honest verifier.
4. Verify the audit chain survived
Because the archive included the full history log, the tamper-evident audit chain over the restored graph is byte-identical to the original. Re-verify with a single procedure call:
status should read clean, and entries should count every ACL audit event that had been recorded when the backup was taken. brokenAtEventId and reason are null on a clean chain; on a tampered chain they carry the event where verification failed.
5. (Optional) Roundtrip a specific belief
To prove a specific decision survived the roundtrip, walk the belief lineage on both graphs and compare:
Same output on my-graph and on my-graph-verify. That is the practical demonstration that the archive preserved the full bitemporal and provenance trail.
Related
- Operations — general operator surface for liveness, deploys, and rollback.
- High availability — strongly-consistent replication and reader scale-out for cross-node durability.
- Bitemporal — point-in-time queries served against the live graph, not against archives.
- Provenance — belief lineage and evidence chains that are preserved end-to-end across restore.
- Crypto-shred — GDPR Article 17 cryptographic erasure that applies across every backup.
- Design principles — the capability-level guarantees the backup format commits to.
Backup + restore is single-graph, single-node disaster recovery. Multi-region and quorum-replicated topologies for continuous availability live on the high-availability cluster page. Detailed operator procedures ship with your production contract.