Python

SecantusDB Python DB

The reference implementation — a real MongoDB server in pure Python, embeddable in two lines from any test or app, with the broadest feature surface and the SQL/PostgreSQL frontend. Backed by the same WiredTiger engine MongoDB uses.

pip install SecantusDB Read the Python docs

Drop-in for `pymongo`

Same wire protocol, same handshake, same error codes. The application code is byte-identical — only the setup line changes.

Normal MongoDB requires mongod running on :27017

from pymongo import MongoClient

client = MongoClient("mongodb://localhost:27017")
db = client["mydb"]
db["users"].insert_one({"_id": 1, "name": "Joe"})
assert db["users"].find_one({"_id": 1})["name"] == "Joe"

Embedded SecantusDB no external process — in your test or app

from pymongo import MongoClient
from secantus import SecantusDBServer

with SecantusDBServer(port=27017) 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"

Quickstart Examples

Why the Python DB

Production-grade engineering — real wire protocol, real WiredTiger storage — scoped today to test and dev environments. Each panel links to the reference docs.

Drop-in wire protocol

Speaks MongoDB OP_MSG / OP_QUERY on a real TCP socket. pymongo, the Go driver, mongosh, and mongodump all connect with no code changes.

Architecture →

Single-node by design

No replica sets, no sharding, no cluster topology to model. Within single-node scope SecantusDB is a faithful surrogate — same handshake, same error codes.

Compatibility →

Python-native & embeddable

Start a server in two lines from any test or app. No mongod to install, no port juggling, parallel-test friendly. Or run it as a standalone daemon (secantusdb).

Quickstart →

Real WiredTiger storage

The same C library MongoDB ships with, vendored and built into the wheel. B-trees, page eviction, write-ahead logging, durability — all real.

Storage architecture →

Aggregation pipeline

Full pipeline — $match, $group (every mongod accumulator), $lookup with index-driven joins, $facet, $bucket, $densify, $fill, $merge, $out, $graphLookup, $geoNear. Same expression language as mongod.

Aggregation reference →

Geospatial — `2d` & `2dsphere`

$geoWithin, $geoIntersects, $near, $nearSphere, $geoNear all accelerated by either index type. S2 cell coverings for GeoJSON; quadtree-decomposed Z-order ranges for legacy [x, y] pairs. Compound geo+scalar indexes work too.

Geospatial reference →

Native TLS & mTLS

Wraps accepted sockets in TLS before the wire protocol starts — no reverse proxy required. Add a CA bundle for mTLS (transport-layer client-cert verification). SCRAM-SHA-256 still identifies the user on top.

Configure TLS →

Change streams

Oplog-backed, single-node. watch() at collection / db / cluster scope, resume tokens, fullDocument: "updateLookup", pre-images via changeStreamPreAndPostImages, awaitData blocking.

Change-streams reference →

Conformance-tested

Validated against the unmodified pymongo, mongo-go-driver, mongo-node-driver, mongo-ruby-driver, mongo-java-driver, and mongo-rust-driver test suites, plus PHP feature smokes. The pass rates are the honest compatibility gauge.

Validation summary →

Performance

A like-for-like benchmark currently has the Python DB ~6×–21× slower per operation than mongod — the storage engine is the same WiredTiger C library, but the layers above it are Python. CRUD reads sit near the low end; bulk update / delete and aggregation at the high end. The trade is conformance and WiredTiger durability over per-op latency — for ephemeral test and dev data, the wall-clock difference rarely matters. Need raw speed? That's what Rust DB is for. Benchmark & methodology →

It speaks SQL too

The Python DB is the home of the SQL/PostgreSQL frontend: the same WiredTiger data is reachable over the PostgreSQL wire protocol — psql, psycopg, SQLAlchemy — and a document written with pymongo reads back as a row. Validated against psycopg 3's own unmodified test suite and the sqllogictest corpus.

SQL / PostgreSQL interface →

Get it

Embedded (two lines)

pip install SecantusDB
# then in your test or app:
with SecantusDBServer(port=0) as server:
    client = MongoClient(server.uri)

Standalone daemon

secantusd-py --port 27017 --storage-path ./data
# PostgreSQL wire:
secantusd-py-pg --port 5432 --storage-path ./data

Python DB documentation: Quickstart · The two servers · SQL interface · Backup & PITR · Feature comparison