Install & Build

OMGDB ships as source. There is no installer, prebuilt package, or language binding yet — you build the omgdb binary from the Cargo workspace with the stable Rust toolchain. This page covers the prerequisites, the release build, the quality gates the project runs on every commit, and an honest account of what the current v0.0 release does and does not do.

Prerequisites

You need the Rust toolchain. The workspace targets stable Rust, edition 2021, with a minimum supported Rust version (MSRV) of 1.89 — 1.89 is required for File::try_lock, which backs the single-process advisory store lock.

The repository pins the channel and components in rust-toolchain.toml:

[toolchain]
channel = "stable"
components = ["rustfmt", "clippy"]

If you use rustup, the correct toolchain and components are selected automatically when you build inside the repository.

Build the release binary

Clone the repository, then build from the workspace root:

cargo build --release

This produces the omgdb binary:

target/release/omgdb        # Linux / macOS
target/release/omgdb.exe    # Windows

The binary is always named omgdb (not omg). Confirm the build and list the available subcommands:

./target/release/omgdb --help

Tip: The release profile enables thin LTO and a single codegen unit, so a release build takes noticeably longer than a debug build (cargo build) but produces a faster binary. For local exploration a debug build at target/debug/omgdb is fine.

Once the binary exists, follow the quickstart to create your first store. The example store path used throughout the docs is app.omgdb.

Quality gates

OMGDB enforces a set of gates on every commit, run in CI on Linux, Windows, and macOS plus an MSRV check. You can run the core gates directly:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all

A justfile runs the complete CI gate set — formatting, lints, tests, and docs — in the same order as CI. If you have just installed:

just check

The check recipe runs the following gates, failing on the first red one:

Note: Library code uses thiserror for errors and avoids unwrap/expect on its code paths; anyhow is used only in the binary. Keep these conventions when contributing or the gates will reject the change.

Status & limitations

OMGDB is an early project (v0.0). The durability and codec layers are hardened — crash recovery, an opt-in repair tool, a bit-exact deterministic canonical codec proven by a property test, a crash-truncation matrix that truncates the log at every byte offset, and Linux/Windows/macOS + MSRV CI. Despite that, OMGDB is not yet production-ready at scale because of the deliberate, documented limitations below. Read these before relying on it.

In-memory state — does not scale beyond RAM

The entire dataset is held in memory and rebuilt by replaying the whole operation log on open. There is no paged or memory-mapped binary store yet, so a store cannot exceed available memory. This is the main gap to production scale.

No compound, unique, or partial indexes

Ordered secondary indexes accelerate top-level equality, range ($gt/$gte/$lt/$lte), and multikey (per-element, on array fields) predicates. Everything else falls back to a scan:

• Compound (multi-field) indexes are not implemented — multi-field predicates scan.
• Unique indexes are not implemented.
• Partial indexes are not implemented.

Primary _id lookups are O(log n). See indexes for what is supported today.

Single-process exclusive lock

A store takes an exclusive advisory lock on open, so a second process attempting to open the same store is cleanly refused. There is no multi-reader or multi-writer concurrency model — use one process at a time. Within that process, the single-writer &mut borrow serializes transactions, giving serializable isolation. See transactions.

Baseline embedder — not a neural model

Vector search uses a pluggable Embedder trait, but the bundled implementation is HashingEmbedder: a deterministic, dependency-free bag-of-words hashing embedder. It is a reproducible baseline, not a real neural model. Embeddings can be persisted, synced, and staleness-checked with provenance, and search uses flat exact cosine kNN.

Limitation: A real model (for example, ONNX all-MiniLM-L6-v2) is planned as a drop-in for the Embedder trait but is not yet implemented. HNSW / approximate vector indexes are also planned (not yet implemented) — vector search currently uses flat exact cosine ranking only.

MongoDB-compatible subset, not full MongoDB

OMGDB implements a single-node, MongoDB-compatible subset of the document/query API. The following are deliberately out of scope for an embedded engine and are not implemented:

• Sharding
• Replication / replica sets
• Change streams and cross-node oplog tailing
• Cluster auth / roles

The aggregation pipeline implements the common stages, not all of them.

No language binding or installer

There is no TypeScript / Node binding and no native (napi) binding yet — a Node/TS binding is a planned (not yet implemented) item. The real programmatic surfaces are the Rust crates, the omgdb CLI (see the CLI reference), and the MCP server. There is also no installer or distributable package: you build from source as described above.

License

OMGDB is dual-licensed under MIT OR Apache-2.0 — at your option. Both LICENSE-MIT and LICENSE-APACHE are included in the repository. Unless you state otherwise, any contribution you submit for inclusion is dual-licensed under the same terms.

Next steps

With the binary built, continue to the quickstart to create a store, insert documents, and run your first query.