Skip to content

URI grammar

The URI is how every NamiDB client — Python, Rust, CLI, namidb-server — addresses a namespace on a backend. The URI carries both the bucket/path and the namespace.

Schemes

Scheme	Backend
`memory://<ns>`	In-process, ephemeral — testing only
`file:///abs/dir?ns=<ns>`	Local filesystem with CAS via `flock` + atomic rename
`s3://<bucket>[/<prefix>]?ns=<ns>`	AWS S3, Cloudflare R2, MinIO, Tigris, LocalStack
`gs://<bucket>[/<prefix>]?ns=<ns>`	Google Cloud Storage
`az://<account>/<container>[/<prefix>]?ns=<ns>`	Azure Blob Storage

Query-string flags

Common across S3-compatible backends:

Flag	Purpose
`?ns=<name>`	Required. Names the namespace inside the bucket/prefix.
`&region=<aws-region>`	Region. For R2 use `auto`.
`&endpoint=<https-url>`	Override the endpoint (R2, MinIO, LocalStack, Tigris, S3-compatible).
`&allow_http=true`	Permit `http://` endpoints (LocalStack, local MinIO).

GCS-specific:

Flag	Purpose
`&service_account=<path>`	Override `GOOGLE_APPLICATION_CREDENTIALS`.

Azure-specific:

Flag	Purpose
`&use_emulator=true`	Talk to Azurite (the local emulator).

Examples

AWS S3

s3://my-bucket/data?ns=prod&region=us-west-2

Cloudflare R2

s3://my-bucket?ns=prod
   &endpoint=https://<ACCOUNT_ID>.r2.cloudflarestorage.com
   &region=auto

Google Cloud Storage

gs://my-bucket/data?ns=prod

gs://my-bucket?ns=prod&service_account=/etc/gcs-key.json

Azure Blob

az://myacct/mycontainer?ns=prod

az://devstoreaccount1/mycontainer?ns=test&use_emulator=true

MinIO (local)

s3://namidb?ns=dev
   &endpoint=http://127.0.0.1:9000
   &region=us-east-1
   &allow_http=true

LocalStack (S3 mock for tests)

s3://namidb-dev?ns=local
   &endpoint=http://localhost:4566
   &allow_http=true
   &region=us-east-1

Local filesystem

file:///var/lib/namidb?ns=prod
file://./data?ns=dev

Ephemeral memory

memory://acme

See also