PoloDB: an embedded document database with a MongoDB-shaped API

A document database that lives in your process

PoloDB is an embedded document database for Rust with a MongoDB-like API, and it stores BSON documents locally. The homepage is polodb.org, the licence is Apache 2.0, and the current version is 5.3.0, published on 2026-07-26 after 5.2.0 earlier in July and 5.1.4 in May 2025.

The embedded part is the defining characteristic. There is no server to run, no port to configure, and no network hop between your application and the data. The data is a directory on disk, and the database handle is an ordinary Rust value you pass around.

The feature list is short and it is a list of the MongoDB surface area that has been reimplemented. There is an embedded, typed Rust API built around serde and BSON. There are MongoDB-like CRUD, query, update, index, and aggregation APIs. There are explicit transactions and automatic per-operation transactions. There is concurrent use through clonable database handles. The storage is RocksDB-backed persistent storage. There is a standalone server for supported MongoDB driver operations. And there are experimental Python bindings built from the same Rust core.

The word embedded also implies the boundary. A separate process holding the data is a different product with different failure modes, and the Python bindings are explicitly experimental, as is the standalone server's protocol coverage. The topics attached to the repository say localfirst and nosql, and that combination is the whole pitch: a database designed to sit inside a local-first application rather than behind a network.

The typed Rust API, in about thirty lines

The quick start is the clearest possible demonstration of the model, and it is worth reading because it shows the shape of the whole API.

use polodb_core::{bson::doc, CollectionT, Database};
use serde::{Deserialize, Serialize};

#[derive(Debug, Serialize, Deserialize)]
struct Book {
    title: String,
    author: String,
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let db = Database::open_path("./data/books")?;
    let books = db.collection::<Book>("books");

    books.insert_one(Book {
        title: "The Three-Body Problem".to_string(),
        author: "Liu Cixin".to_string(),
    })?;

    let book = books.find_one(doc! {
        "author": "Liu Cixin",
    })?;

    println!("{book:?}");
    Ok(())
}

Three details carry the design. Database::open_path takes a path, so a database is a directory. The collection method is generic over the document type, so books is a collection of Book and not a collection of BSON documents with a runtime type tag, and that is what the embedded, typed Rust API built around serde means in practice. And the query is a BSON doc rather than a string, so the compiler checks the shape of the filter.

The insert returns a Result and the find_one returns an Option inside a Result, so the API uses Rust error handling throughout rather than MongoDB's callback style. The CollectionT trait is what makes the generic collection work, and it is imported explicitly alongside Database and the bson module.

The result of find_one is a typed Book, so a document that does not match the declared struct is a deserialization error rather than a value with the wrong fields. That is the practical difference between a typed embedded store and a raw BSON wrapper.

RocksDB, and the cost of the first build

PoloDB v5 uses RocksDB as its storage backend, and there is a consequence that catches people out. A database path is a directory, not a single portable database file, and the first build compiles the bundled RocksDB sources and can take several minutes.

Both of those facts follow from the choice of storage engine. A directory of files rather than one file means you cannot simply copy a database to a new machine as a single artefact, you have to copy the directory, and it means the on-disk format is RocksDB's rather than something PoloDB defines. The compilation cost follows from vendoring RocksDB through a sys crate, which is the same pattern the Cargo workspace shows with a src/librocksdb-sys member.

The build requirements are listed explicitly: a Rust toolchain, a C/C++ build toolchain, and Clang or libclang for the bundled RocksDB bindings. The libclang requirement is the one that surprises people, because bindgen needs it to parse the RocksDB headers, and it is a dependency you may not have on a minimal CI image.

The consequence for a continuous integration setup is that the first build on a fresh cache is slow, and that the CI image needs the C toolchain and libclang installed. Neither is a blocker, but both need to be planned for rather than discovered on a first pull request.

The alternative to compiling RocksDB from source is a system RocksDB or a prebuilt binary, and the project has chosen the vendored path, which trades build time for reproducibility across platforms.

The standalone server, and what it does not do

PoloDB can also run as a standalone server, and the install is two commands.

cargo install polodb --version 5.3.0
polodb serve --path ./data/server --host 127.0.0.1 --port 27017

The default port of 27017 is MongoDB's, which tells you what the compatibility goal is. The server implements the subset of the MongoDB wire protocol used by its supported commands, and the README says plainly that it is not a drop-in replacement for a full MongoDB server.

That caveat is the important sentence, and it should be read as a design statement rather than a limitation to apologise for. The same Rust core backs both the embedded library and the server, and the package table shows the split: polodb_core is the published embedded Rust database library, polodb is the published standalone server and CLI, and py-polodb is the experimental Python bindings developed in the repository.

The Python bindings being marked experimental in the same table as a published package is a useful signal about what is stable. A Python user gets the API but not the same guarantees, and the project status section says the Python bindings are tested on Python 3.12 through 3.14.

Release binaries for the standalone server are published for macOS x64, Linux x64, and Windows x64 on the GitHub Releases page, which is a smaller platform set than the Rust CI matrix, and that is worth checking if you plan to run the server rather than embed the library.

What is not there yet, and the maturity signals

The project status section is candid in a way that is worth reading carefully before you build on it.

Rust CI currently covers Ubuntu x64, Ubuntu ARM64, macOS, and Windows. Python bindings are tested on Python 3.12 through 3.14. And the sentence that matters: indexes, aggregation, the standalone server, and language bindings continue to evolve, so test the behavior your application depends on before using PoloDB in production.

The roadmap section says the same thing in the form of a list of what is explicitly not part of the current stable feature set. Mobile SDKs, additional language bindings, encryption, multikey indexes, and alternative storage backends require further design.

Encryption being on that list is the one to plan around. For a local-first application holding anything sensitive, the absence of at-rest encryption in the storage engine is a significant gap, and the project says so rather than leaving you to find out. If encryption matters, that is a reason to choose a different store, or to encrypt at a layer above the database.

The alternative storage backends item is also worth a note. A single storage engine is a limitation for a project that might want a different one for a different use case, and the fact that alternative backends are on the roadmap rather than merely unsupported suggests the storage layer is designed to be replaceable, but that is a design intention rather than a shipped capability.

The overall shape is a young but unusually honest project. Version 5.3.0, a five version series, an experimental language binding, an explicitly partial wire protocol, and encryption on the not-yet list.

Editorial conclusion

Adopt PoloDB if you want a local-first document store inside a Rust application and want the query vocabulary your team already knows from MongoDB. Do not adopt it as a MongoDB replacement, since the server implements only a subset of the wire protocol and encryption is not part of the stable feature set. Verify first that the build cost is acceptable, because the first build compiles the bundled RocksDB sources and can take several minutes.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. PoloDB/PoloDB on GitHub
3. Project website
4. README
5. Releases