Local filesystem
file:// stores a namespace in a directory on local disk. It uses the same
commit protocol as the object-store backends: every manifest pointer is
created exactly once, with O_CREAT | O_EXCL providing the
PUT-if-absent guarantee that S3 provides with If-None-Match: *.
import namidb
db = namidb.Client("file:///var/lib/namidb?ns=prod") # absolute pathdb = namidb.Client("file://./data?ns=dev") # relative to the working directorynamidb-server --store "file:///var/lib/namidb?ns=prod" --auth-token "$NAMIDB_AUTH_TOKEN"namidb run --store "file:///var/lib/namidb?ns=prod" "MATCH (n) RETURN count(n) AS n"The directory is created if it does not exist. One directory can hold many
namespaces side by side (/var/lib/namidb/prod, /var/lib/namidb/staging,
…). See Storage URIs for
the layout inside a namespace.
One writer per namespace
Only one process may write a namespace at a time. A process that opens it
for writing (a server, a CLI run, a writable Python Client, an MCP
server) claims it and fences the previous writer. To read a namespace that
another process is writing, open it with
namidb.Client(uri, read_only=True); see
Embedded Python.
Docker volumes
The official image runs as uid/gid 65532 and owns /var/lib/namidb:
# A named volume inherits the right ownership:docker run -v namidb-data:/var/lib/namidb -e NAMIDB_AUTH_TOKEN \ namidb/namidb-server:3.3.0 --store "file:///var/lib/namidb?ns=prod"
# A bind mount needs the ownership fixed once on the host:sudo chown -R 65532:65532 /srv/namidbdocker run -v /srv/namidb:/var/lib/namidb -e NAMIDB_AUTH_TOKEN \ namidb/namidb-server:3.3.0 --store "file:///var/lib/namidb?ns=prod"Named volumes created root-owned by images older than 2.2.0 need the same
chown.
FUSE and network filesystems
Bind mounts backed by FUSE (for example Docker Desktop’s file sharing on
macOS) and some network filesystems report unstable file metadata. Data files
are written once under fresh names, so NamiDB pins reads to the immutable path
rather than to the stat-derived ETag, and such mounts work. Set
NAMIDB_LOCAL_ETAG_PIN=1 to restore ETag pinning, for example if something
other than NamiDB rewrites files in place under the store directory (it
should not).
The filesystem must honour exclusive create (O_CREAT | O_EXCL) for the
commit protocol to be safe. Local disks do; check before pointing two hosts
at one shared network directory, and remember that only one of them may write
a given namespace.
Scratch space
Flush and compaction write temporary files. The Python client puts them in
<root>/.namidb-spool next to the graph by default; the server uses
NAMIDB_SPOOL_DIR (/var/tmp for the bare binary, /var/tmp/namidb-spool
in the image). Keep the spool on disk, not on a RAM-backed tmpfs. See
Memory and caches.
Backups
Do not copy the directory of a namespace that is open for writing: a copy
taken mid-commit can capture an inconsistent set of files. Use
namidb backup, or the server’s online backup endpoint, which pin a
consistent version. See Backup and restore.