Skip to content

Storage URIs

Every NamiDB entry point (the Python Client, namidb --store, namidb-mcp --store, namidb-server --store) takes the same URI. The URI picks the backend, where in it the data lives, and the namespace.

SchemeBackendExample
memory://In-process, ephemeralmemory://demo
file://Local filesystemfile:///var/lib/namidb?ns=prod
s3://AWS S3 and S3-compatible servicess3://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

Grammar

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]
ParameterSchemesMeaning
ns (or namespace)allNamespace name. Required except in memory://<ns> form and in multi-tenant mode.
regions3Region; overrides AWS_DEFAULT_REGION / AWS_REGION. Use auto for Cloudflare R2.
endpoints3, azCustom endpoint URL (R2, MinIO, Tigris, LocalStack, Azurite…).
allow_https3, aztrue / 1 / yes permits plain HTTP to the endpoint.
service_accountgsPath to a service-account JSON key.
use_emulatoraztrue to talk to the Azurite emulator.

Unknown parameters are ignored, except on memory://, where a typo is an error. Values with special characters must be percent-encoded.

Namespace names

[a-z0-9][a-z0-9_-]{0,62}: 1 to 63 characters of lowercase letters, digits, - and _, starting with a letter or digit. An invalid name is rejected when the URI is parsed:

bad namespace 'Bad': invalid identifier: namespace 'Bad' must start with [a-z0-9]

Check names with namidb namespace-check <name>.

Where the objects go

URIObjects for namespace prod
file:///var/lib/namidb?ns=prod/var/lib/namidb/prod/…
s3://bucket?ns=prod (no prefix)s3://bucket/tenants/prod/…
s3://bucket/graphs?ns=prods3://bucket/graphs/prod/…
gs://…, az://…Same rule as s3://: tenants/<ns>/ without a prefix, <prefix>/<ns>/ with one
--multi-tenant server<ns>/… at the root of the directory, bucket or container (the URI’s prefix is not used)

Inside a namespace directory:

PathContents
manifest/v<N>.jsonImmutable manifest versions
manifest/pointer/p<N>.jsonVersioned pointers written with PUT-if-absent; the highest is current
manifest/current.jsonConvenience copy of the current pointer
manifest/pins/Retention leases held by backups and read-only readers
wal/Write-ahead log segments
sst/level<N>/Immutable data files and their side-cars (Parquet, index and filter files)

Treat these as opaque. Never edit or delete them by hand while any process has the namespace open; use backup and restore to copy namespaces.

Credentials

BackendWhere credentials come from
s3://The standard AWS variables: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, optional AWS_SESSION_TOKEN, AWS_DEFAULT_REGION / AWS_REGION; or the instance / task / pod role (EC2, ECS, EKS, Lambda).
gs://GOOGLE_APPLICATION_CREDENTIALS (path to a key file), the service_account= parameter, or the environment’s default credentials.
az://AZURE_STORAGE_ACCOUNT_NAME with AZURE_STORAGE_ACCOUNT_KEY (or AZURE_STORAGE_ACCESS_KEY), a SAS token, or other credentials the Azure SDK conventions read from the environment.
file://, memory://None.

Credentials never go in the URI.

Permissions the engine needs on the bucket or container: read, write (including conditional create), delete and list objects under the prefix. On AWS that is s3:GetObject, s3:PutObject, s3:DeleteObject and s3:ListBucket, plus s3:AbortMultipartUpload for large-file uploads.

Object-store client tuning

These environment variables apply to every s3://, gs:// and az:// store opened by the process (maintenance included). Unset means the object_store client defaults (30 s per request, a 180 s retry budget).

VariableMeaning
NAMIDB_STORE_REQUEST_TIMEOUTPer-request timeout, e.g. 30s or 500ms (bare numbers are seconds).
NAMIDB_STORE_RETRY_TIMEOUTTotal time spent retrying one operation.
NAMIDB_STORE_MAX_RETRIESMaximum retries per operation.

Lower them only when you would rather fail fast than wait out a long retry storm, and size them generously: large uploads during compaction use the same client.

Pick a backend