Documentation
Start with the project README for the problem nonodb solves, quick-start instructions, and a feature overview.
Guides
Section titled “Guides”| Guide | Audience | Contents |
|---|---|---|
| Architecture | Maintainers, advanced users | Process model, LMDB layout, write path, indexes, search, aggregation, crash safety |
| Multiple databases | Operators, application developers | Separate LMDB environments, URL routing, create/drop, CLI, GUI, migration, backup |
| Adaptive writer | Operators, performance reviewers | Adaptive group-commit window, latency/throughput tuning, metrics and limits |
| GUI console | Operators, application developers | Embedded local React console, data editing, collection settings, SQL, map/metrics |
| HTTP API | All client authors | Operations, request/response formats, filters, updates, aggregation, errors |
| MongoDB compatibility | Evaluators, migrating teams | Documented MongoDB-compatible subset, supported drivers, known differences, and migration assessment |
| SQL queries | Analysts, reporting jobs, application developers | SELECT, INSERT, UPDATE, DELETE, filters, aggregates, parameters, limits, client examples |
| Vault collections | Application developers, security reviewers | Optional whole-document encryption, tenant keys, restrictions, operations, key rotation |
| Document TTL | Application developers, operators | Collection defaults, per-document overrides, update semantics, background expiry, limits |
| Dates and time zones | Application developers | BSON-compatible dates, RFC 3339 input, filtering, indexes, sorting, timezone semantics |
| Numbers and decimals | Application developers | Exact numeric comparison, Decimal128, arithmetic, NaN/Infinity, index compatibility, long text limits |
| BSON scalar types | Application developers | $numberInt/$numberLong, $type, binary/UUID, ObjectId, Timestamp, MinKey/MaxKey, index compatibility |
| Clients | Application developers | Python, Rust, Node.js and Go: install, connection, CRUD, batches, indexes, search, aggregation |
| Migration and import | Application developers, operators | MongoDB, PostgreSQL, SQLite, CSV conversion; NDJSON format; import manifest; validation and cutover |
| Authentication and permissions | Operators, security reviewers | Principals, scopes, hashed tokens, certificate registry, lockout, reloads, audit log |
| Security checks | Operators, security reviewers, maintainers | Local security regression checks, LiveAPISec audit method, results, hardening gaps, production checklist |
| Monitoring and alerting | Operators, SRE | Health/readiness, Prometheus endpoint, metrics:read token, OpenTelemetry Collector, disk/snapshot metrics, alerts |
| Mutual TLS | Operators, security reviewers | Private CA setup, client certificates, fingerprint mapping, revocation, rotation, troubleshooting |
| Python client | Python developers | Connection, CRUD, upsert, indexes, search, batches, cache, FastAPI |
| Background jobs | Application developers, operators | Durable jobs, workers, leases, retries, cron/systemd, languages |
| Outbox events | Application developers, operators | Atomic data + events, automatic collection events, source-side filters, polling consumers, checkpoints, event worker CLI, TTL, systemd |
| Conditional subscriptions | Application developers | Conditions over collection state, count thresholds, edge-triggered mode, events, clients |
| Streaming outbox events | Application developers | Long-poll watch, NDJSON/SSE streams, resume tokens, filters, truncation, Python/Rust/Node.js/Go examples |
| CLI | Operators | Administration, map resize, backup verification, restore drills, inspect, raw requests |
| Operations | Operators, SRE | Configuration, deployment, security, snapshots, monitoring, capacity, troubleshooting |
| Docker Compose quick start | Operators, developers | Self-contained Compose stack, auth initialization, GUI, updates, backups, troubleshooting |
| Raspberry Pi with Docker | Operators, edge deployments | 64-bit Raspberry Pi 4/5 setup, SSD data directory, SSH tunnels, updates, troubleshooting |
| Volume compression | Operators, SRE | ZFS/Btrfs compression, Docker bind mounts and named volumes, verification, benchmarking, migration |
| Free-tier and low-cost VM deployment | Operators, small deployments | Oracle Cloud, GCP, AWS, DigitalOcean, small profile, Cloud Run read replicas, Spaces backups, restore |
| Backup and restore | Operators, SRE | Online backup, GUI backup/import, snapshots, verification, restore drills, Docker, vault keys, authorization state, recovery |
| Replication and cluster guide | Operators, SRE | Primary/replica setup, TLS, CLI, GUI, quorum failover, monitoring, backup differences, troubleshooting |
| Replication design | Maintainers, advanced users | Ordered operation log, apply rules, epochs, snapshots, quorum design, metrics |
| Benchmarks | Evaluators, maintainers | Environment, methodology, throughput, latency, memory, large-data results |
| Development | Contributors | Repository layout, build, tests, scripts, conventions |
| Roadmap and limits | Everyone | Supported features, deliberate limitations, future work |
Common tasks
Section titled “Common tasks”- Download prebuilt binaries: README — Prebuilt binaries
- Run on Linux, macOS or Windows: README — Quick start
- Run with Docker: README — Run with Docker
- Run a self-contained Docker Compose stack: Docker Compose quick start
- Run on Raspberry Pi 4/5 with Docker: Raspberry Pi with Docker
- Run on a free-tier or low-cost VM: Free-tier and low-cost VM deployment
- Run several databases in one daemon: Multiple databases
- Open the local GUI: GUI console
- Pick a client: Clients — Python, Rust, Node.js, Go
- Connect with a MongoDB driver: MongoDB compatibility
- Run a SQL query or simple write: SQL queries
- Import data from another database: Migration and import
- Expose nonodb to Python workers: Python client
- Run background jobs and schedulers: Background jobs
- Consume change events: Outbox events
- React to collection conditions: Conditional subscriptions
- Stream events with a resume token: Streaming outbox events
- Secure a deployment: Authentication and authorization and TCP/TLS
- Run security checks: Security checks
- Tune writer latency: Adaptive writer
- Set up client certificates: Mutual TLS
- Store sensitive tenant data encrypted: Vault collections
- Expire documents automatically: Document TTL
- Filter and index timestamps: Dates and time zones
- Store money and exact decimals: Numbers and decimals
- Use binary, UUID, ObjectId, or
$type: BSON scalar types - Back up and restore: Backup and restore
- Set up replication and a cluster: Replication and cluster guide
- Import a backup as a new database: Import wizard
- Tune timeouts for index builds: Timeouts
- Understand memory usage: Capacity and memory
- Reduce disk usage with filesystem compression: Volume compression
- Reproduce performance numbers: Benchmarks