SecantusDB

Warning

Alpha software — not for production use.

SecantusDB is in early development. The API surface and on-disk format can change between point releases. It exists today as a developer tool for exercising application code against a MongoDB-shaped surrogate; it is not a database for storing data you can’t recreate.

A surrogate single-node MongoDB server in Python. SecantusDB speaks the subset of the MongoDB wire protocol that pymongo emits, so application test suites can talk to it instead of standing up a real mongod.

The audience is developers who want fast, ephemeral, in-process MongoDB behaviour for tests. SecantusDB is intentionally scoped to single-node operation — replica sets, sharding, and other cluster-only features are out of scope by design — so it stays simple, fast, and easy to embed.

What it is

from pymongo import MongoClient
from secantus import SecantusDBServer

with SecantusDBServer(port=0) as server:
    client = MongoClient(server.uri)
    db = client["mydb"]
    db["users"].insert_one({"_id": 1, "name": "Joe"})
    assert db["users"].find_one({"_id": 1})["name"] == "Joe"

That’s it. No mongod to install, no port conflicts, no test isolation gymnastics — every SecantusDBServer(port=0) gets its own OS-assigned port and its own :memory: WiredTiger storage, so suites run cleanly under pytest-xdist.

What’s in scope

The subset of MongoDB that pymongo actually drives:

• Connection handshake (hello / isMaster / ping / buildInfo / …).

• CRUD: insert, find, update, delete, findAndModify, count, drop.

• Cursors with getMore / killCursors (with a 10-minute idle TTL).

• Aggregation pipelines and the expression language they need.

• Indexes — single-field, compound, mixed-direction, partial, TTL — with a real query planner that chooses the right index and reports it through explain.

See Indexes and Aggregation for the full inventory, and Compatibility for what’s intentionally not supported.

What’s out of scope

Anything that depends on cluster topology — replica sets, sharding, change streams, oplog tailing — and anything tangential to test-harness use:

• Authentication (SCRAM / x509 / LDAP / Kerberos).

• TLS / SSL.

• Text search and geo indexes.

• $where (no JS runtime).

• Real transaction rollback (we accept commitTransaction / abortTransaction but operations take effect immediately).

If a test depends on those features, it needs a real mongod. SecantusDB is the right tool when the test is exercising your application’s MongoDB usage, not the database’s clustering or auth.

Quick links

• Installation — pip install and the WiredTiger build prerequisites.

• Quickstart — embedding in tests, running standalone.

• Examples — connect, insert, index, query, drop.

• Architecture — wire / commands / query / aggregate / storage layers.

• Indexes — single-field, compound, mixed-direction, partial, TTL, hint, sort acceleration, explain.

• Aggregation — supported pipeline stages and expression operators.

• Compatibility — known divergences from real MongoDB.

• API reference — SecantusDBServer, Storage, public surface.

License

GPL-2.0-only. SecantusDB depends on (and intends to bundle) the WiredTiger storage engine, which is itself GPL-2/GPL-3, so the combined work is GPL.