---
title: Install & Build
description: Build the omgdb binary from source with the Rust toolchain, run the quality gates, and read the honest v0.0 status and limitations
---

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](https://rustup.rs) 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`:

```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:

```sh
cargo build --release
```

This produces the `omgdb` binary:

```text
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:

```sh
./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](/docs/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:

```sh
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`](https://github.com/casey/just) installed:

```sh
just check
```

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

| Gate | Command | Purpose |
|------|---------|---------|
| Format | `cargo fmt --all -- --check` | Verify formatting without modifying files. |
| Lint | `cargo clippy --all-targets --all-features -- -D warnings` | Warnings are errors. |
| Test | `cargo test --all` | Full test suite across the workspace. |
| Docs | `cargo doc --no-deps --all-features` | Public items must stay documented. |
| Doctests | `cargo test --doc --all` | Run documentation examples. |

> **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.

### No paged binary store yet — the in-process engine holds state in RAM

A write-capable in-process open (`Store::open`) replays the operation log into memory and holds the dataset in RAM, so it cannot exceed available memory. The CLI and MCP server do not pay a full replay per command: they work through direct log/cache paths backed by five rebuildable cache sidecars that sit next to the log (see [storage](/docs/storage/)). What is missing is a paged or memory-mapped binary store — that is the main gap to production scale. Durable single-document writes are fsync-bound — the same physical wall every embedded database hits — so use the batch paths (`insert-many`, `import-jsonl`) for bulk loads.

### Indexes — implemented, with edges

Ordered secondary indexes ship in **single-field**, **compound**, **unique** (single-field and compound), and **partial** (including partial unique) variants, accelerating top-level **equality**, **`$in`** (as a union of equality buckets), **range** (`$gt`/`$gte`/`$lt`/`$lte`), and **multikey** (per-element, on array fields) predicates, plus index-ordered sorts when a safe index exists. The edges: index keys cover top-level fields only; index scans return a candidate superset and re-filter for exact semantics; a partial index is used only when the query provably implies its predicate. An exact-`_id` `find` short-circuits to the primary key — no index on `_id` is ever needed. See [indexes](/docs/indexes/) for the full model.

### 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](/docs/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](/docs/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](/docs/aggregation/) 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](/docs/cli/)), and the [MCP server](/docs/mcp/). 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](/docs/quickstart/) to create a store, insert documents, and run your first query.