A MongoDB database client for D, built on vibe.d. Speaks the modern wire protocol and supports MongoDB servers up to 8.0.
This is the driver behind vibe-d:mongodb. It used to live inside the vibe.d repository and now has
its own, so it can be released and tested against the full range of MongoDB servers independently.
The vibe.db.mongo module names and the API are unchanged.
"dependencies": {
"vibe-mongodb": "~>2.0.0"
}Depending on vibe-d:mongodb keeps working too: that subpackage forwards to this one.
Topology and connections
- Server Discovery and Monitoring (SDAM) with per server health monitors and cooldown handling
- Replica sets, including primary step down detection, arbiter awareness and stale primary demotion
- Sharded clusters and load balanced mode
- Read preferences with tag sets and
maxStalenessSeconds mongodb+srvDNS seedlist resolution- Connection quarantine and recovery from dead connections
- Wire protocol compression (
OP_COMPRESSED), with credential and handshake commands exempted
Operations
- MongoDB 8 server level
bulkWrite, including upserted ids, unacknowledged writes anderrInfopropagation - Retryable writes with topology refresh on step down
- Read concern and write concern throughout
- Change streams at collection, database and client level
- GridFS
- Index management
Sessions and consistency
- Server sessions with pooling
- Multi document transactions, with
withTransactionRetrypreserving the original error - Causal consistency through cluster time gossiping
- Stable API (
apiVersion) and session timeout handling
Security
- SCRAM-SHA-1 and SCRAM-SHA-256 authentication
- X.509 authentication
- TLS, with optional certificate verification
- Client side field level encryption, with a key vault interface
Every release is tested against each of these in CI.
| MongoDB server | Status |
|---|---|
| 3.6 | Tested |
| 4.0 | Tested |
| 4.2 | Tested |
| 4.4 | Tested |
| 5.0 | Tested |
| 6.0 | Tested |
| 7.0 | Tested |
| 8.0 | Tested |
Features that the server does not offer are detected at runtime rather than assumed. Transactions and
change streams need a replica set or a sharded cluster, and server level bulkWrite needs 8.0.
import vibe.db.mongo.mongo;
auto client = connectMongoDB("127.0.0.1");
auto users = client.getCollection("myapp.users");
users.insertOne(["name": "Peter", "city": "Bucharest"]);
auto peter = users.findOne(["name": "Peter"]);
if (!peter.isNull)
logInfo("found %s", peter["city"].get!string);Connection strings are supported in full:
auto client = connectMongoDB("mongodb://user:password@host1,host2/?replicaSet=rs0&readPreference=secondaryPreferred");
auto srv = connectMongoDB("mongodb+srv://user:password@cluster.example.com/");
auto direct = connectMongoDB("mongodb://db-service:27017/?directConnection=true");directConnection=true talks to the one named host and skips replica-set discovery, for when a
member must be reached under a name the set does not advertise or a specific member (a secondary,
a hidden node) must be addressed directly. It requires a single host and cannot be combined with
mongodb+srv:// or loadBalanced=true.
MongoClient runs background monitor tasks, so it is meant to be created once and shared between
fibers in a thread. When you need a client with a bounded lifetime, scopedMongoDB returns a handle
that stops those monitors when it leaves scope:
auto client = scopedMongoDB("127.0.0.1");
auto users = client.getCollection("myapp.users");Transactions need a replica set member or a mongos:
auto session = client.startSession();
session.startTransaction();
orders.insertOne(Bson(["item": Bson("cigar"), "qty": Bson(12)]),
InsertOneOptions.init, &session);
session.commitTransaction();
session.endSession();Every operation that can take part in a transaction accepts a MongoClientSession* as its last
argument.
No code changes are needed. Either keep depending on vibe-d:mongodb, or replace it with
vibe-mongodb in your dub.json. Module names are the same, so imports stay as they are.
vibe-mongodriver was the name of this package before it moved into the vibe-d organization. Its
modules lived under vibe.db.mongodriver. Switch the dependency to vibe-mongodb and rename the
imports:
find . -name '*.d' -exec sed -i -E 's/vibe\.db\.mongodriver\b/vibe.db.mongo/g' {} +InsertOneResult.insertedId and UpdateResult.upsertedIds hold BsonObjectID values again, as
in vibe-d:mongodb. Code that relied on them carrying ids of any BSON type should read
insertedIdValue and upsertedIdValues instead.
Unit tests need nothing but a compiler:
dub testThe integration suite lives in tests/ as 19 independent dub projects. It needs mongod,
mongodump from the MongoDB database tools, and either the legacy mongo shell (servers up to 5.0)
or mongosh (6.0 and later) on PATH:
./run-ci.sh # unit tests, then every integration project
PARTS=unittests ./run-ci.sh # unit tests only
PARTS=mongo ./run-ci.sh # integration tests onlyMost projects have their server started and stopped for them. The ones needing unusual setup, such as
replica sets, authentication modes or a load balancer, bring their own run.sh. Tests that require a
capability the running server does not have will skip themselves rather than fail.
import-upstream.sh applies a commit from a vibe.d checkout that touches the old mongodb/
subpackage to this repository, translating paths as it goes:
./import-upstream.sh <upstream-sha> ~/src/vibe.dThe MongoDB driver was originally written as part of vibe.d by
Sönke Ludwig and contributors. This repository preserves that history: the commits here are the real
ones, filtered out of the vibe.d tree with git-filter-repo, not a flattened import.
docs/history-map.txt maps every commit in this repository back to its original SHA in
gedaiu/vibe.d, so provenance stays traceable. Those SHAs predate the move back to the
vibe.db.mongo module names.
MIT. See LICENSE.txt.