Skip to content

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 path
db = namidb.Client("file://./data?ns=dev") # relative to the working directory
Terminal window
namidb-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:

Terminal window
# 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/namidb
docker 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.