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.
| Scheme | Backend | Example |
|---|---|---|
memory:// | In-process, ephemeral | memory://demo |
file:// | Local filesystem | file:///var/lib/namidb?ns=prod |
s3:// | AWS S3 and S3-compatible services | 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 |
Grammar
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]| Parameter | Schemes | Meaning |
|---|---|---|
ns (or namespace) | all | Namespace name. Required except in memory://<ns> form and in multi-tenant mode. |
region | s3 | Region; overrides AWS_DEFAULT_REGION / AWS_REGION. Use auto for Cloudflare R2. |
endpoint | s3, az | Custom endpoint URL (R2, MinIO, Tigris, LocalStack, Azurite…). |
allow_http | s3, az | true / 1 / yes permits plain HTTP to the endpoint. |
service_account | gs | Path to a service-account JSON key. |
use_emulator | az | true 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
| URI | Objects 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=prod | s3://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:
| Path | Contents |
|---|---|
manifest/v<N>.json | Immutable manifest versions |
manifest/pointer/p<N>.json | Versioned pointers written with PUT-if-absent; the highest is current |
manifest/current.json | Convenience 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
| Backend | Where 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).
| Variable | Meaning |
|---|---|
NAMIDB_STORE_REQUEST_TIMEOUT | Per-request timeout, e.g. 30s or 500ms (bare numbers are seconds). |
NAMIDB_STORE_RETRY_TIMEOUT | Total time spent retrying one operation. |
NAMIDB_STORE_MAX_RETRIES | Maximum 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
- In-memory for tests and demos.
- Local filesystem for one machine.
- Object stores (S3, R2, GCS, Azure, Tigris) for durability and moving between machines.
- MinIO for an S3-compatible bucket on your own hardware.