Skip to content

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.

ToolBackupRestore
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

Terminal window
namidb backup \
--from "s3://graphs?ns=prod&region=us-east-1" \
--to "s3://graph-backups/2026-11-01?ns=prod&region=us-east-1" \
--verify
backed up s3://graphs?ns=prod&region=us-east-1 (source version 5) -> s3://graph-backups/2026-11-01?ns=prod&region=us-east-1
5 objects, 1122 bytes
FlagMeaning
--from, --toSource 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.
--forceProceed even if the destination already holds a namespace.
--verifyRe-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:

Terminal window
namidb-server --store "s3://graphs?ns=prod&region=us-east-1" \
--auth-tokens-file /etc/namidb/tokens.json \
--backup-target-uri "s3://graph-backups/namidb?region=us-east-1"
Terminal window
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&region=us-east-1", "verify": true}'
# {"bytes_copied":651,"objects_copied":4,"source_created_at":"2026-11-01T02:00:03.118294551Z","source_version":1}
Body fieldDefaultMeaning
torequiredDestination namespace URI inside the allowlist.
versioncurrentManifest 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.
forcefalseOverwrite a destination that already has a namespace.
verifyfalseRe-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.

StatusMeaning
200Done: source_version, source_created_at (when that version was committed), objects_copied, bytes_copied.
400Invalid to (or namespace name); code: "invalid_as_of" (not an instant or a version, or sent with version); code: "as_of_in_future".
403Read-only token, endpoint disabled, or to outside the allowlist.
404code: "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.
409Destination already has a namespace and force is unset; the pinned version was reclaimed mid-copy; or verify found a mismatch.
503Another backup or restore held the permit for more than 30 s. One copy runs per process at a time.
500 / 507Other 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); on file:// 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 (or namespace).

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-1
accepted: s3://graph-backups/namidb/acme?ns=acme&region=us-east-1
refused: s3://graph-backups/namidb/../live?ns=acme&region=us-east-1 (.. segment)
refused: s3://graph-backups/namidb-evil/x?ns=acme&region=us-east-1 (outside the path)
refused: s3://graph-backups/namidb/x?ns=acme&region=us-east-1&endpoint=http://10.0.0.5:9000

Refusals 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.

Terminal window
namidb-server --store "s3://graphs?ns=prod&region=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_RETENTION takes a duration (24h, 7d); 0s, the default, turns it off.
  • The maintenance loop advances the window before each sweep, so it needs --compaction-interval above zero. The server refuses to start with a retention and NAMIDB_COMPACTION_INTERVAL=0s.
  • The window starts empty when retention is first turned on and fills up from there. Setting it back to 0 releases the window when the maintenance loop next starts.
  • POST /v0/admin/backup still 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.

Terminal window
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

Terminal window
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&region=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:

Terminal window
namidb restore-points --from "s3://graphs?ns=prod&region=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:00
Terminal window
namidb backup --from "s3://graphs?ns=prod&region=us-east-1" \
--to "s3://graph-backups/prod-before-delete?ns=prod&region=us-east-1" \
--as-of 2026-11-04T06:54:20Z --verify

restore-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.

Terminal window
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&region=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&region=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&region=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:

Terminal window
# 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&region=us-east-1" \
--to "s3://graphs?ns=prod&region=us-east-1" \
--force --verify
# 3. Start the server again.
restored s3://graph-backups/2026-11-01?ns=prod&region=us-east-1 (source version 1) -> s3://graphs?ns=prod&region=us-east-1
4 objects, 651 bytes

The 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:

Terminal window
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&region=us-east-1", "verify": true}'
# {"bytes_copied":658,"objects_copied":4,"source_version":0}
  • from must sit inside the same --backup-target-uri allowlist.
  • Optional version and verify as for backup. There is no force. The response carries source_version (0: the restored namespace starts at version 0) and source_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.
StatusMeaning
404from holds no backup (or not the requested version); checked before anything is written. On a single-tenant server the route does not exist.
409Target exists or is busy; source version reclaimed mid-copy; verify mismatch.
403, 400, 503, 500 / 507As 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/sh
set -eu
DAY=$(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&region=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.