URIs de almacenamiento
Todos los puntos de entrada de NamiDB (el Client de Python,
namidb --store, namidb-mcp --store, namidb-server --store) aceptan el
mismo URI. El URI elige el backend, en qué parte de él viven los datos y el
namespace.
| Esquema | Backend | Ejemplo |
|---|---|---|
memory:// | En el proceso, efímero | memory://demo |
file:// | Sistema de archivos local | file:///var/lib/namidb?ns=prod |
s3:// | AWS S3 y servicios compatibles con S3 | s3://my-bucket/graphs?ns=prod®ion=us-east-1 |
gs:// | Google Cloud Storage | gs://my-bucket?ns=prod |
az:// | Azure Blob Storage | az://myaccount/mycontainer?ns=prod |
Gramática
memory://<ns> or memory://?ns=<ns>file:///<absolute-dir>?ns=<ns> or file://./<relative-dir>?ns=<ns>s3://<bucket>[/<prefix>]?ns=<ns>[®ion=…][&endpoint=…][&allow_http=true]gs://<bucket>[/<prefix>]?ns=<ns>[&service_account=/path/key.json]az://<account>/<container>[/<prefix>]?ns=<ns>[&endpoint=…][&allow_http=true][&use_emulator=true]| Parámetro | Esquemas | Significado |
|---|---|---|
ns (o namespace) | todos | Nombre del namespace. Obligatorio salvo en la forma memory://<ns> y en modo multi-tenant. |
region | s3 | Región; reemplaza a AWS_DEFAULT_REGION / AWS_REGION. Usa auto para Cloudflare R2. |
endpoint | s3, az | URL de un endpoint personalizado (R2, MinIO, Tigris, LocalStack, Azurite…). |
allow_http | s3, az | true / 1 / yes permite HTTP plano hacia el endpoint. |
service_account | gs | Ruta a una clave JSON de service account. |
use_emulator | az | true para hablar con el emulador Azurite. |
Los parámetros desconocidos se ignoran, salvo en memory://, donde un
error de tipeo es un error. Los valores con caracteres especiales deben
codificarse con percent-encoding.
Nombres de namespace
[a-z0-9][a-z0-9_-]{0,62}: de 1 a 63 caracteres entre letras minúsculas,
dígitos, - y _, empezando con una letra o un dígito. Un nombre inválido
se rechaza al parsear el URI:
bad namespace 'Bad': invalid identifier: namespace 'Bad' must start with [a-z0-9]Comprueba los nombres con namidb namespace-check <name>.
Dónde van los objetos
| URI | Objetos del namespace prod |
|---|---|
file:///var/lib/namidb?ns=prod | /var/lib/namidb/prod/… |
s3://bucket?ns=prod (sin prefijo) | s3://bucket/tenants/prod/… |
s3://bucket/graphs?ns=prod | s3://bucket/graphs/prod/… |
gs://…, az://… | La misma regla que s3://: tenants/<ns>/ sin prefijo, <prefix>/<ns>/ con uno |
Servidor --multi-tenant | <ns>/… en la raíz del directorio, bucket o contenedor (no se usa el prefijo del URI) |
Dentro del directorio de un namespace:
| Ruta | Contenido |
|---|---|
manifest/v<N>.json | Versiones inmutables del manifest |
manifest/pointer/p<N>.json | Punteros versionados escritos con PUT-if-absent; el más alto es el vigente |
manifest/current.json | Copia de conveniencia del puntero vigente |
manifest/pins/ | Leases de retención de los backups y de los lectores de solo lectura |
wal/ | Segmentos del write-ahead log |
sst/level<N>/ | Archivos de datos inmutables y sus side-cars (Parquet, índices y filtros) |
Trátalos como opacos. Nunca los edites ni los borres a mano mientras algún proceso tenga el namespace abierto; usa backup y restore para copiar namespaces.
Credenciales
| Backend | De dónde salen las credenciales |
|---|---|
s3:// | Las variables estándar de AWS: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, opcionalmente AWS_SESSION_TOKEN, AWS_DEFAULT_REGION / AWS_REGION; o el rol de la instancia / tarea / pod (EC2, ECS, EKS, Lambda). |
gs:// | GOOGLE_APPLICATION_CREDENTIALS (ruta a un archivo de clave), el parámetro service_account= o las credenciales por defecto del entorno. |
az:// | AZURE_STORAGE_ACCOUNT_NAME con AZURE_STORAGE_ACCOUNT_KEY (o AZURE_STORAGE_ACCESS_KEY), un token SAS u otras credenciales que las convenciones del SDK de Azure leen del entorno. |
file://, memory:// | Ninguna. |
Las credenciales nunca van en el URI.
Permisos que el motor necesita sobre el bucket o contenedor: leer, escribir
(incluida la creación condicional), borrar y listar objetos bajo el
prefijo. En AWS eso es s3:GetObject, s3:PutObject, s3:DeleteObject y
s3:ListBucket, más s3:AbortMultipartUpload para la carga de archivos
grandes.
Ajuste del cliente de object store
Estas variables de entorno se aplican a cada store s3://, gs:// y
az:// que abre el proceso (incluido el mantenimiento). Sin definir, se
usan los valores por defecto del cliente object_store (30 s por petición,
un presupuesto de reintentos de 180 s).
| Variable | Significado |
|---|---|
NAMIDB_STORE_REQUEST_TIMEOUT | Timeout por petición, p. ej. 30s o 500ms (los números solos son segundos). |
NAMIDB_STORE_RETRY_TIMEOUT | Tiempo total dedicado a reintentar una operación. |
NAMIDB_STORE_MAX_RETRIES | Máximo de reintentos por operación. |
Bájalos solo cuando prefieras fallar rápido antes que esperar una larga tormenta de reintentos, y dimensiónalos con holgura: las cargas grandes durante la compactación usan el mismo cliente.
Elegir un backend
- En memoria para tests y demos.
- Sistema de archivos local para una sola máquina.
- Object stores (S3, R2, GCS, Azure, Tigris) para durabilidad y para moverte entre máquinas.
- MinIO para un bucket compatible con S3 en tu propio hardware.