Deployment shape
Deploy ZeeDB as an embedded library or run zeedb serve for language-independent HTTP access. The server guide covers local development, bearer authentication, TLS, Docker, and hosted deployment. The remaining guidance applies to the storage directory in either mode.
For containerized applications, persist the dedicated database directory beyond a container’s disposable writable layer. Each directory still has one process owner; mounting the same directory into several writers does not make the engine distributed.
The current validation does not certify container storage drivers or network filesystems. Choose and test a supported local filesystem/device setup for your environment.
Directory selection
Resolve an explicit application data path from configuration. Avoid the repository root, a directory mixed with unrelated JSON/log files, or an empty-path fallback.
if dataPath == "" {
return errors.New("database path is required")
}
db, err := zeedb.Open(dataPath, options)Relative paths resolve from the process working directory, which may differ between development shells, services, and containers. Prefer a deliberately configured absolute path in deployments.
Ownership and permissions
The engine requests 0700 for new directories and 0600 for created files. Existing permissions are not automatically rewritten, and Windows access control is governed by ACLs rather than these Unix mode bits alone.
Run under the account intended to own the files. Protect the directory with OS access controls and use platform/storage encryption if required. Values and keys are not encrypted by ZeeDB.
Do not delete LOCK to “release” a database. The OS releases a terminated owner’s lock; a live owner must close normally. On Unix, replacing a locked inode can defeat pathname-based expectations.
Keep options with application configuration
Persist the options needed to reopen existing records outside the engine. The file format does not save your deployment’s original key/value/data/WAL budgets as a reusable settings document.
A CLI command uses default budgets, so it may not open data produced under larger custom Go options. Use a diagnostic Go program with the original options when appropriate.
See configuration and troubleshooting before lowering limits on existing data.
Disk and memory headroom
Plan for the old table, newly written table, WAL, metadata, and encoding overhead to coexist during checkpointing. Keep roughly two live tables plus WAL and metadata as an initial planning model, then measure actual workloads.
Logical resource counters are not exact heap/RSS or filesystem quotas. The complete table index, maps, copies, recovery buffers, concurrent results, and Go allocator overhead all consume memory.
Startup and shutdown
Startup verifies the entire table and replays the WAL; startup time therefore grows with persisted data. Open before admitting application work and surface recovery failures as startup failures.
On shutdown, stop intake, drain/cancel background producers, wait for handle users, then close and preserve the first close error. Do not remove the real data directory on exit; removal is only used by the runnable temporary examples.
What remains to validate
Supported process-kill tests are not sudden-power-loss or device-failure certification. Windows directory fsync is unavailable in this implementation. Backups, migrations, sustained stress, and every deployment storage stack need their own evidence before a production-readiness claim.