Backup y restore
Un backup de NamiDB es un namespace autocontenido en otra ubicación: la versión fijada del manifest más cada archivo de datos, side-car y segmento del WAL que necesita. Puedes abrirlo, consultarlo o restaurarlo en cualquier lugar al que pueda apuntar un URI de almacenamiento.
Los backups son consistentes y seguros contra un origen en vivo. La copia fija una versión del manifest con un lease de retención durable que la compactación y el sweep respetan, así que no hace falta pausar al writer. El resultado refleja exactamente la versión fijada: las escrituras confirmadas hasta ella (incluido el WAL sin flush) y nada posterior.
| Herramienta | Backup | Restore |
|---|---|---|
namidb backup / namidb restore (CLI) | Cualquier URI de origen a cualquier URI de destino (--as-of para un instante anterior) | En un destino fuera de línea |
POST /v0/admin/backup (servidor) | El namespace del servidor a un URI de la allowlist (as_of para un instante anterior) | — |
POST /:namespace/v0/admin/restore (servidor multi-tenant) | — | En un namespace nuevo del servidor en ejecución |
Con la 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 | Significado |
|---|---|
--from, --to | URIs de los namespaces de origen y destino. Pueden usar backends distintos (de S3 a un disco local, por ejemplo). |
--version <N> | Copia esa versión del manifest en lugar de la actual. |
--as-of <instante> | Copia el namespace tal como estaba en este instante RFC 3339 (puntos de restauración). Excluyente con --version. |
--force | Continúa aunque el destino ya contenga un namespace. |
--verify | Vuelve a abrir el destino y comprueba que cada objeto referenciado existe y no está vacío. |
Si una compactación y un sweep compiten con la fijación y eliminan un objeto a mitad de la copia, el backup falla de forma visible (not found) en lugar de producir una copia parcial; vuelve a ejecutarlo.
Con el servidor (en línea)
El endpoint de administración copia con las credenciales del propio servidor, así que está desactivado hasta que defines una 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}| Campo del cuerpo | Por defecto | Significado |
|---|---|---|
to | obligatorio | URI del namespace de destino dentro de la allowlist. |
version | la actual | Versión del manifest a copiar. |
as_of | — | Copia el namespace tal como estaba en un punto de restauración: un instante RFC 3339, que se resuelve a la versión más reciente confirmada en ese instante o antes, o una versión del manifest como entero JSON. Excluyente con version. Ver Puntos de restauración. |
force | false | Sobrescribe un destino que ya tiene un namespace. |
verify | false | Vuelve a leer y comprueba cada objeto copiado. |
En modo multi-tenant usa POST /:namespace/v0/admin/backup (o la forma con
header). Lee el estado confirmado del namespace sin abrirlo, así que un
namespace en frío sigue en frío, y se respetan los tokens con alcance por
namespace.
| Estado | Significado |
|---|---|
| 200 | Listo: source_version, source_created_at (cuándo se confirmó esa versión), objects_copied, bytes_copied. |
| 400 | to inválido (o nombre de namespace inválido); code: "invalid_as_of" (no es un instante ni una versión, o se envió junto con version); code: "as_of_in_future". |
| 403 | Token de solo lectura, endpoint desactivado o to fuera de la allowlist. |
| 404 | code: "restore_point_unavailable": as_of es anterior a la ventana de puntos de restauración (el cuerpo trae earliest y latest de la ventana); code: "namespace_not_found": el namespace no tiene un manifest confirmado. |
| 409 | El destino ya tiene un namespace y force no está definido; la versión fijada se recuperó a mitad de la copia; o verify encontró una discrepancia. |
| 503 | Otro backup o restore tuvo el permiso por más de 30 s. Se ejecuta una copia por proceso a la vez. |
| 500 / 507 | Otros fallos (507 por almacenamiento insuficiente). |
La allowlist
--backup-target-uri (NAMIDB_BACKUP_TARGET_URI) es el límite de
seguridad: las credenciales del servidor escriben dondequiera que apunte
to, así que to (y el from de un restore) se compara con el prefijo
componente por componente:
- el mismo esquema y bucket (o cuenta, o host);
- una ruta igual o por debajo de la ruta del prefijo, sin segmentos vacíos,
.ni..(incluidas sus formas con percent-encoding); enfile://la ruta resuelta, incluidos los symlinks, debe quedar dentro del directorio del prefijo; - exactamente los parámetros de consulta del prefijo con los mismos
valores, en cualquier orden, más solo
ns(onamespace).
Así que pon las opciones del store en el prefijo y repítelas en cada
petición. Una petición no puede elegir su propio endpoint, region,
allow_http ni 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:9000Los rechazos son 403 con el motivo, por ejemplo
destination is outside the --backup-target-uri allowlist (…): path segment .. is not allowed.
Puntos de restauración (point-in-time)
El estado de un namespace en un instante es la versión del manifest más reciente confirmada en ese instante o antes. Normalmente el sweep recupera las versiones antiguas cuando ningún lector las necesita. Con la retención de puntos de restauración el servidor conserva en cambio cada versión de una ventana, y todo lo que esas versiones referencian, así que un backup puede copiar el namespace exactamente como estaba en cualquier instante dentro de ella, sin importar lo que se haya escrito, borrado, hecho flush o compactado desde entonces.
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_RETENTIONrecibe una duración (24h,7d);0s, el valor por defecto, la desactiva.- El loop de mantenimiento avanza la ventana antes de cada sweep, así que
necesita
--compaction-intervalmayor que cero. El servidor se niega a arrancar con una retención yNAMIDB_COMPACTION_INTERVAL=0s. - La ventana empieza vacía cuando se activa la retención por primera vez
y se llena a partir de ahí. Volver a
0libera la ventana la próxima vez que arranca el loop de mantenimiento. POST /v0/admin/backupsigue necesitando--backup-target-uri. Listar la ventana no.
Listar la ventana: GET /v0/admin/restore-points
Solo tokens de lectura y escritura. limit (1–1000, 100 por defecto) y
before (solo versiones menores: pasa el next_before de la página
anterior) recorren los puntos, del más reciente al más antiguo.
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}Cada commit, flush, compactación y sentencia DDL es un punto de
restauración. Se puede copiar cualquier instante desde earliest.created_at
hasta ahora. Con la retención desactivada, enabled es false,
retention_secs y lease_expires_at son null, y la ventana es solo la
versión actual. Cada punto listado cuesta una lectura de manifest, así que
usa limit=1 cuando solo importan los límites. Errores: 400
code: "invalid_limit"; 403 con un token de solo lectura; 404
code: "namespace_not_found" cuando el namespace no tiene un manifest
confirmado.
Backup a un instante
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 y source_created_at indican a qué versión se resolvió el
instante. Un instante anterior a la ventana responde 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" }}Para completar un restore a un punto en el tiempo, restaura ese backup como
cualquier otro: fuera de línea con namidb restore, o en un namespace nuevo
de un servidor multi-tenant.
Un backup justo en el borde de la ventana puede competir con el avance de la
ventana; en ese caso falla con 409 y un reintento vuelve a resolver el
instante.
Desde la CLI
La CLI lee la ventana directamente del store, así que funciona sobre un namespace que mantiene un servidor con retención:
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 imprime 20 puntos por defecto (--limit). backup --as-of
falla con los límites de la ventana cuando el instante queda fuera de ella.
Servidores multi-tenant
Usa /:namespace/v0/admin/restore-points y /:namespace/v0/admin/backup
(o las rutas sin prefijo con X-NamiDB-Namespace). Listar no abre un
namespace en frío. Cada namespace tiene su propia ventana, que avanza solo
mientras el namespace está abierto; uno desalojado durante más tiempo que la
ventana empieza una ventana nueva cuando vuelve a abrirse. Mientras estuvo
cerrado no se escribió nada, así que no se pierde ningún instante intermedio.
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}'Costo de almacenamiento
La ventana conserva todo lo que el namespace escribe durante la retención
(más --sweep-min-age): un cuerpo de manifest y un segmento del WAL por
commit, cada salida de flush y cada archivo de datos que una compactación
reemplazó. Eso es aproximadamente
retención × tasa de ingesta × amplificación de escritura de la compactación,
más commits × tamaño del manifest, sobre los datos vivos. Por ejemplo, un
namespace que ingiere 1 GiB al día con una ventana de 7 días conserva del
orden de 20 GiB de historial. El sweep y una apertura en frío listan
manifest/ y wal/, que crecen con la cantidad de commits conservados.
Cada sweep registra restore_window_retained y restore_window_bytes, los
objetos conservados solo por la ventana.
Mezclar versiones es seguro: un motor anterior a 3.3.0 trata el lease de la ventana como un lease de retención común, que conserva estrictamente más.
Inspeccionar un backup
Un backup es un namespace normal. Ábrelo en solo lectura para que la inspección no lo modifique:
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())Restaurar un servidor single-tenant
Un servidor single-tenant siempre tiene abierto su único namespace, así que no tiene endpoint de restore. Restaura fuera de línea:
# 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 bytesEl destino debe estar fuera de línea: nada bloquea a un writer concurrente
durante un restore. Para restaurar junto a los datos en vivo, restaura en
un namespace nuevo (?ns=prod-restored) y cambia los clientes hacia él.
Restaurar en un namespace nuevo (multi-tenant)
Un servidor multi-tenant guarda los namespaces en la raíz de su store, que la CLI no puede direccionar en object stores, así que restaura a través del servidor:
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}fromdebe estar dentro de la misma allowlist de--backup-target-uri.versionyverifyopcionales, igual que en el backup. No hayforce. La respuesta traesource_version(0: el namespace restaurado empieza en la versión 0) ysource_created_at.- El destino no debe existir. 409 cuando está abierto, abriéndose o siendo desalojado, ya en proceso de restauración, o ya tiene datos. Para restaurar sobre un namespace existente, borra sus objetos por fuera, sin ningún servidor que lo tenga abierto, y luego restaura.
- Mientras se ejecuta la copia, las peticiones que abrirían el destino reciben 503, así que nada puede crear un namespace vacío por debajo. La copia continúa si el cliente se desconecta.
- Un restore fallido o interrumpido se puede reintentar: limpia lo que escribió. No envíes tráfico al destino hasta que el restore termine bien.
| Estado | Significado |
|---|---|
| 404 | from no contiene ningún backup (o no la version pedida); se comprueba antes de escribir nada. En un servidor single-tenant la ruta no existe. |
| 409 | El destino existe o está ocupado; la versión de origen se recuperó a mitad de la copia; discrepancia de verify. |
| 403, 400, 503, 500 / 507 | Igual que en el backup. |
Programación
Haz backups de forma programada desde cron, un job de CI o tu orquestador, con un destino fechado por ejecución, y verifica:
#!/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}"Haz expirar los backups antiguos con una regla de ciclo de vida en el bucket o prefijo de backups (nunca en el de producción), y prueba un restore con regularidad.