Skip to content
NamiDB NamiDB

Local filesystem (file://)

For development, single-machine deployments, and CI fixtures.

import namidb as tg


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


# Relative paths work too:
client = tg.Client("file://./data?ns=dev")

How CAS works on a filesystem

NamiDB implements manifest CAS on a local filesystem via:

  • Per-namespace flock(2) for write-side serialisation
  • Atomic rename(2) for the manifest swap

This passes the same concurrency test suite as s3://. Single- writer-per-namespace + epoch fencing applies identically.

When to use it

  • CI fixtures — durable, no network, fast.
  • Single-machine production — when “all my data fits on one disk and one process” is the right shape.
  • Local development — when you want to test the full LSM cycle (flush, compaction, snapshot lifetime) without spinning up MinIO.

Layout on disk

/var/lib/namidb/{namespace}/
├── manifest.json
├── manifest.lock      ← flock target
├── wal/
└── sst/

You can aws s3 sync between file:// and s3:// paths to migrate.

What you give up

  • Durability beyond the disk. No replication, no multi-AZ, no versioning. Whatever your filesystem and your backup story give you, that’s what NamiDB gives you.
  • Multi-machine reads. A file:// namespace is owned by one host. Two hosts mounting the same NFS / EFS path are not supported (NFS flock semantics aren’t strict enough).

See also