Skip to content
NamiDB NamiDB

Local filesystem

file:// opens a namespace on a local directory. NamiDB wraps object_store::local::LocalFileSystem with its own LocalFileObjectStore, which adds per-namespace flock locking plus atomic rename(2) to implement manifest CAS — the same correctness primitive S3 conditional writes give you on a real bucket.

Use it for single-machine deployments, CI fixtures that need persistence, dev work without a bucket, and anywhere a full object store is overkill.

URI shape

Absolute path:

file:///abs/dir?ns=<namespace>

Relative path:

file://./rel?ns=<namespace>

The leading file:/// (three slashes) is followed by the absolute path; file://./ (two slashes plus ./) starts from the current working directory.

Examples

import namidb


# Absolute path.
client = namidb.Client("file:///var/lib/namidb?ns=prod")


# Relative path.
client = namidb.Client("file://./data?ns=dev")
Terminal window
namidb run --store "file:///var/lib/namidb?ns=prod" \
  "CREATE (a:Person {name: 'Alice'})"


namidb run --store "file:///var/lib/namidb?ns=prod" \
  "MATCH (p:Person) RETURN p.name"
use namidb::storage::{parse_uri, WriterSession};


let (store, paths) = parse_uri("file:///var/lib/namidb?ns=prod")?;
let mut writer = WriterSession::open(store, paths).await?;

Concurrency

The local backend implements the same single-writer-per-namespace invariant as the cloud backends:

  • Compare-and-swap on the manifest uses flock(2) plus rename(2).
  • Two processes can both open a WriterSession against the same file:// URI; the first to commit wins, the second sees a fenced epoch.
  • The local backend passes the same concurrency test suite as the s3:// backend.

Permissions

NamiDB needs read, write, and flock permission on the directory you point at. The directory is created on first open if missing (intermediate mkdir -p semantics).

A file:// namespace is just a directory tree. Backups are cp -r, rsync, tar, or anything else that preserves file content.

When to choose file://

  • Development. No bucket to configure.
  • CI fixtures. Persistent across multiple processes in the same test job; deterministic, repeatable.
  • Single-machine deployments. When durability is bounded by your disk and that’s enough.
  • Migration staging. Build a namespace locally, then aws s3 sync the directory to a real bucket — the on-bucket layout is identical.

What’s next