Saltearse al contenido

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.

EsquemaBackendEjemplo
memory://En el proceso, efímeromemory://demo
file://Sistema de archivos localfile:///var/lib/namidb?ns=prod
s3://AWS S3 y servicios compatibles con S3s3://my-bucket/graphs?ns=prod&region=us-east-1
gs://Google Cloud Storagegs://my-bucket?ns=prod
az://Azure Blob Storageaz://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>[&region=…][&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ámetroEsquemasSignificado
ns (o namespace)todosNombre del namespace. Obligatorio salvo en la forma memory://<ns> y en modo multi-tenant.
regions3Región; reemplaza a AWS_DEFAULT_REGION / AWS_REGION. Usa auto para Cloudflare R2.
endpoints3, azURL de un endpoint personalizado (R2, MinIO, Tigris, LocalStack, Azurite…).
allow_https3, aztrue / 1 / yes permite HTTP plano hacia el endpoint.
service_accountgsRuta a una clave JSON de service account.
use_emulatoraztrue 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

URIObjetos 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=prods3://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:

RutaContenido
manifest/v<N>.jsonVersiones inmutables del manifest
manifest/pointer/p<N>.jsonPunteros versionados escritos con PUT-if-absent; el más alto es el vigente
manifest/current.jsonCopia 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

BackendDe 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).

VariableSignificado
NAMIDB_STORE_REQUEST_TIMEOUTTimeout por petición, p. ej. 30s o 500ms (los números solos son segundos).
NAMIDB_STORE_RETRY_TIMEOUTTiempo total dedicado a reintentar una operación.
NAMIDB_STORE_MAX_RETRIESMá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