Backup and restore
A NamiDB backup is a self-contained namespace at another location: the pinned manifest version plus every data file, side-car and WAL segment it needs. You can open it, query it, or restore it anywhere a storage URI can point.
Backups are consistent and safe against a live source. The copy pins a manifest version with a durable retention lease that compaction and the sweep honour, so no writer pause is needed. The result reflects the pinned version exactly: committed writes up to it (unflushed WAL included), nothing after it.
| Tool | Backup | Restore |
|---|---|---|
namidb backup / namidb restore (CLI) | Any source URI to any destination URI (--as-of for an earlier instant) | Into an offline destination |
POST /v0/admin/backup (server) | The server’s namespace to an allowlisted URI (as_of for an earlier instant) | — |
POST /:namespace/v0/admin/restore (multi-tenant server) | — | Into a new namespace on the running server |
With the CLI
namidb backup \ --from "s3://graphs?ns=prod®ion=us-east-1" \ --to "s3://graph-backups/2026-11-01?ns=prod®ion=us-east-1" \ --verifybacked up s3://graphs?ns=prod®ion=us-east-1 (source version 5) -> s3://graph-backups/2026-11-01?ns=prod®ion=us-east-1 5 objects, 1122 bytes| Flag | Meaning |
|---|---|
--from, --to | Source and destination namespace URIs. They may use different backends (S3 to a local disk, for example). |
--version <N> | Copy that manifest version instead of the current one. |
--as-of <instant> | Copy the namespace as it was at this RFC 3339 instant (restore points). Exclusive with --version. |
--force | Proceed even if the destination already holds a namespace. |
--verify | Re-open the destination and check every referenced object exists and is non-empty. |
If a compaction and sweep race the pin and remove an object mid-copy, the backup fails loudly (not found) instead of producing a partial copy; run it again.
With the server (online)
The admin endpoint copies through the server’s own credentials, so it is disabled until you set an allowlist:
namidb-server --store "s3://graphs?ns=prod®ion=us-east-1" \ --auth-tokens-file /etc/namidb/tokens.json \ --backup-target-uri "s3://graph-backups/namidb?region=us-east-1"curl -s -X POST localhost:8080/v0/admin/backup \ -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \ -d '{"to": "s3://graph-backups/namidb/2026-11-01?ns=prod®ion=us-east-1", "verify": true}'# {"bytes_copied":651,"objects_copied":4,"source_created_at":"2026-11-01T02:00:03.118294551Z","source_version":1}| Body field | Default | Meaning |
|---|---|---|
to | required | Destination namespace URI inside the allowlist. |
version | current | Manifest version to copy. |
as_of | — | Copy the namespace as it was at a restore point: an RFC 3339 instant, resolved to the newest version committed at or before it, or a manifest version as a JSON integer. Exclusive with version. See Restore points. |
force | false | Overwrite a destination that already has a namespace. |
verify | false | Re-read and check every copied object. |
In multi-tenant mode use POST /:namespace/v0/admin/backup (or the header
form). It reads the namespace’s committed state without opening it, so a cold
namespace stays cold, and namespace-scoped tokens are enforced.
| Status | Meaning |
|---|---|
| 200 | Done: source_version, source_created_at (when that version was committed), objects_copied, bytes_copied. |
| 400 | Invalid to (or namespace name); code: "invalid_as_of" (not an instant or a version, or sent with version); code: "as_of_in_future". |
| 403 | Read-only token, endpoint disabled, or to outside the allowlist. |
| 404 | code: "restore_point_unavailable": as_of is older than the restore point window (the body carries the window’s earliest and latest); code: "namespace_not_found": the namespace has no committed manifest. |
| 409 | Destination already has a namespace and force is unset; the pinned version was reclaimed mid-copy; or verify found a mismatch. |
| 503 | Another backup or restore held the permit for more than 30 s. One copy runs per process at a time. |
| 500 / 507 | Other failures (507 for insufficient storage). |
The allowlist
--backup-target-uri (NAMIDB_BACKUP_TARGET_URI) is the security boundary:
the server’s credentials write wherever to points, so to (and a
restore’s from) is checked against the prefix component by component:
- the same scheme and bucket (or account, or host);
- a path at or below the prefix’s path, with no empty,
.or..segments (percent-encoded forms included); onfile://the resolved path, symlinks included, must stay inside the prefix directory; - exactly the prefix’s query parameters with the same values, in any order,
plus only
ns(ornamespace).
So put the store options in the prefix and repeat them in every request. A
request cannot choose its own endpoint, region, allow_http or
service_account.
prefix: s3://graph-backups/namidb?region=us-east-1accepted: s3://graph-backups/namidb/acme?ns=acme®ion=us-east-1refused: s3://graph-backups/namidb/../live?ns=acme®ion=us-east-1 (.. segment)refused: s3://graph-backups/namidb-evil/x?ns=acme®ion=us-east-1 (outside the path)refused: s3://graph-backups/namidb/x?ns=acme®ion=us-east-1&endpoint=http://10.0.0.5:9000Refusals are 403 with the reason, for example
destination is outside the --backup-target-uri allowlist (…): path segment .. is not allowed.
Restore points (point in time)
A namespace’s state at an instant is the newest manifest version committed at or before it. Normally the sweep reclaims old versions once no reader needs them. With restore point retention the server keeps every version of a window instead, and everything those versions reference, so a backup can copy the namespace exactly as it was at any instant inside it, whatever was written, deleted, flushed or compacted since.
namidb-server --store "s3://graphs?ns=prod®ion=us-east-1" \ --auth-tokens-file /etc/namidb/tokens.json \ --backup-target-uri "s3://graph-backups/namidb?region=us-east-1" \ --restore-point-retention 7d--restore-point-retention/NAMIDB_RESTORE_POINT_RETENTIONtakes a duration (24h,7d);0s, the default, turns it off.- The maintenance loop advances the window before each sweep, so it needs
--compaction-intervalabove zero. The server refuses to start with a retention andNAMIDB_COMPACTION_INTERVAL=0s. - The window starts empty when retention is first turned on and fills
up from there. Setting it back to
0releases the window when the maintenance loop next starts. POST /v0/admin/backupstill needs--backup-target-uri. Listing the window does not.
List the window: GET /v0/admin/restore-points
Read-write tokens only. limit (1–1000, default 100) and before (only
versions below it: pass the previous page’s next_before) page through the
points, newest first.
curl -s "localhost:8080/v0/admin/restore-points?limit=2" -H "Authorization: Bearer $ADMIN_TOKEN"{ "enabled": true, "retention_secs": 604800, "lease_expires_at": "2026-11-11T07:08:07Z", "earliest": { "version": 0, "created_at": "2026-11-04T06:53:07.699556648Z" }, "latest": { "version": 2, "created_at": "2026-11-04T06:53:11.764359941Z" }, "points": [ { "version": 2, "created_at": "2026-11-04T06:53:11.764359941Z" }, { "version": 1, "created_at": "2026-11-04T06:53:07.714138144Z" } ], "next_before": 1}Every commit, flush, compaction and DDL statement is a restore point. Any
instant from earliest.created_at to now can be copied. With retention off,
enabled is false, retention_secs and lease_expires_at are null,
and the window is just the current version. Each listed point costs one
manifest read, so use limit=1 when only the bounds matter. Errors: 400
code: "invalid_limit"; 403 for a read-only token; 404
code: "namespace_not_found" when the namespace has no committed manifest.
Back up as of an instant
curl -s -X POST localhost:8080/v0/admin/backup \ -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \ -d '{"to": "s3://graph-backups/namidb/prod-before-delete?ns=prod®ion=us-east-1", "as_of": "2026-11-04T06:53:09Z", "verify": true}'# {"bytes_copied":781,"objects_copied":4,"source_created_at":"2026-11-04T06:53:07.714138144Z","source_version":1}source_version and source_created_at say which version the instant
resolved to. An instant before the window answers 404:
{ "code": "restore_point_unavailable", "error": "`as_of` is outside the restore point window (versions 0 to 2, …)", "earliest": { "version": 0, "created_at": "2026-11-04T06:53:07.699556648Z" }, "latest": { "version": 2, "created_at": "2026-11-04T06:53:11.764359941Z" }}To finish a point-in-time restore, restore that backup like any other:
offline with namidb restore, or into a new namespace on a
multi-tenant server. A backup
at the very edge of the window can race the window moving past it; it then
fails with 409 and a retry resolves the instant again.
From the CLI
The CLI reads the window straight from the store, so it works on a namespace that a server with retention keeps:
namidb restore-points --from "s3://graphs?ns=prod®ion=us-east-1"restore point window: retention 604800s, lease expires 2026-11-11T07:09:15+00:00 earliest v0 at 2026-11-04T06:54:15.675743809+00:00 latest v3 at 2026-11-04T06:54:22.754928510+00:00 v3 2026-11-04T06:54:22.754928510+00:00 v2 2026-11-04T06:54:19.725732876+00:00 v1 2026-11-04T06:54:18.697514012+00:00 v0 2026-11-04T06:54:15.675743809+00:00namidb backup --from "s3://graphs?ns=prod®ion=us-east-1" \ --to "s3://graph-backups/prod-before-delete?ns=prod®ion=us-east-1" \ --as-of 2026-11-04T06:54:20Z --verifyrestore-points prints 20 points by default (--limit). backup --as-of
fails with the window’s bounds when the instant is outside it.
Multi-tenant servers
Use /:namespace/v0/admin/restore-points and /:namespace/v0/admin/backup
(or the unprefixed routes with X-NamiDB-Namespace). Listing does not open
a cold namespace. Each namespace keeps its own window, which advances only
while the namespace is open; one evicted for longer than the window starts a
fresh window when it next opens. Nothing was written while it was closed, so
no instant in between is lost.
curl -s -X POST localhost:8080/acme/v0/admin/backup \ -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \ -d '{"to": "s3://graph-backups/namidb/acme-before-delete?ns=acme®ion=us-east-1", "as_of": "2026-11-04T06:53:09Z"}'curl -s -X POST localhost:8080/acme-restored/v0/admin/restore \ -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \ -d '{"from": "s3://graph-backups/namidb/acme-before-delete?ns=acme®ion=us-east-1", "verify": true}'Storage cost
The window keeps everything the namespace writes during the retention (plus
--sweep-min-age): one manifest body and one WAL segment per commit, every
flush output, and every data file a compaction superseded. That is roughly
retention × ingest rate × compaction write amplification, plus
commits × manifest size, on top of the live data. For example, a namespace
that ingests 1 GiB a day with a 7-day window keeps on the order of 20 GiB of
history. The sweep and a cold open list manifest/ and wal/, which grow
with the number of commits kept. Each sweep logs restore_window_retained
and restore_window_bytes, the objects kept only for the window.
Mixing releases is safe: an engine older than 3.3.0 treats the window’s lease as an ordinary retention lease, which keeps strictly more.
Inspect a backup
A backup is a normal namespace. Open it read-only so the inspection does not change it:
import namidb
snap = namidb.Client("s3://graph-backups/2026-11-01?ns=prod®ion=us-east-1", read_only=True)print(snap.cypher("MATCH (n) RETURN count(n) AS nodes").first())Restore a single-tenant server
A single-tenant server always has its one namespace open, so it has no restore endpoint. Restore offline:
# 1. Stop the server that owns the namespace.# 2. Restore over it (--force because the destination exists):namidb restore \ --from "s3://graph-backups/2026-11-01?ns=prod®ion=us-east-1" \ --to "s3://graphs?ns=prod®ion=us-east-1" \ --force --verify# 3. Start the server again.restored s3://graph-backups/2026-11-01?ns=prod®ion=us-east-1 (source version 1) -> s3://graphs?ns=prod®ion=us-east-1 4 objects, 651 bytesThe destination must be offline: nothing fences a concurrent writer during
a restore. To restore next to the live data instead, restore into a new
namespace (?ns=prod-restored) and switch clients over.
Restore into a new namespace (multi-tenant)
A multi-tenant server keeps namespaces at the root of its store, which the CLI cannot address on object stores, so restore through the server:
curl -s -X POST localhost:8080/acme-restored/v0/admin/restore \ -H "Authorization: Bearer $ADMIN_TOKEN" -H 'Content-Type: application/json' \ -d '{"from": "s3://graph-backups/namidb/acme-nightly?ns=acme®ion=us-east-1", "verify": true}'# {"bytes_copied":658,"objects_copied":4,"source_version":0}frommust sit inside the same--backup-target-uriallowlist.- Optional
versionandverifyas for backup. There is noforce. The response carriessource_version(0: the restored namespace starts at version 0) andsource_created_at. - The target must not exist. 409 when it is open, being opened or evicted, already being restored, or already has data. To restore over an existing namespace, delete its objects out of band with no server holding it, then restore.
- While the copy runs, requests that would open the target get 503, so nothing can create an empty namespace underneath it. The copy continues if the client disconnects.
- A failed or interrupted restore can be retried: it cleans up what it wrote. Route no traffic to the target until the restore succeeds.
| Status | Meaning |
|---|---|
| 404 | from holds no backup (or not the requested version); checked before anything is written. On a single-tenant server the route does not exist. |
| 409 | Target exists or is busy; source version reclaimed mid-copy; verify mismatch. |
| 403, 400, 503, 500 / 507 | As for backup. |
Scheduling
Back up on a schedule from cron, a CI job or your orchestrator, with a dated destination per run, and verify:
#!/bin/shset -euDAY=$(date -u +%F)curl -fsS -X POST "http://127.0.0.1:8080/v0/admin/backup" \ -H "Authorization: Bearer $NAMIDB_ADMIN_TOKEN" -H 'Content-Type: application/json' \ -d "{\"to\": \"s3://graph-backups/namidb/$DAY?ns=prod®ion=us-east-1\", \"verify\": true}"Expire old backups with a lifecycle rule on the backup bucket or prefix (never on the live one), and test a restore regularly.