Saltearse al contenido

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.

HerramientaBackupRestore
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

Ventana de terminal
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
FlagSignificado
--from, --toURIs 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.
--forceContinúa aunque el destino ya contenga un namespace.
--verifyVuelve 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:

Ventana de terminal
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"
Ventana de terminal
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}
Campo del cuerpoPor defectoSignificado
toobligatorioURI del namespace de destino dentro de la allowlist.
versionla actualVersió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.
forcefalseSobrescribe un destino que ya tiene un namespace.
verifyfalseVuelve 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.

EstadoSignificado
200Listo: source_version, source_created_at (cuándo se confirmó esa versión), objects_copied, bytes_copied.
400to 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".
403Token de solo lectura, endpoint desactivado o to fuera de la allowlist.
404code: "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.
409El 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.
503Otro backup o restore tuvo el permiso por más de 30 s. Se ejecuta una copia por proceso a la vez.
500 / 507Otros 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); en file:// 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 (o namespace).

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

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

Ventana de terminal
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 recibe 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-interval mayor que cero. El servidor se niega a arrancar con una retención y NAMIDB_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 0 libera la ventana la próxima vez que arranca el loop de mantenimiento.
  • POST /v0/admin/backup sigue 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.

Ventana de terminal
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

Ventana de terminal
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 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:

Ventana de terminal
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
Ventana de terminal
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 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.

Ventana de terminal
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}'

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

Ventana de terminal
# 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

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

Ventana de terminal
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 debe estar dentro de la misma allowlist de --backup-target-uri.
  • version y verify opcionales, igual que en el backup. No hay force. La respuesta trae source_version (0: el namespace restaurado empieza en la versión 0) y source_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.
EstadoSignificado
404from 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.
409El destino existe o está ocupado; la versión de origen se recuperó a mitad de la copia; discrepancia de verify.
403, 400, 503, 500 / 507Igual 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/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}"

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.