mongodb-bson

MongoDB C++ Rules

Instance Initialization

// ❌ WRONG - Crashes
mongocxx::uri uri{"mongodb://localhost:27017"};
client_ = std::make_unique<mongocxx::client>(uri);

// ✅ CORRECT
#include "../../include/mongodb.h"
mongocxx::instance& instance = MongoDBInstance::getInstance();
mongocxx::uri uri{"mongodb://localhost:27017"};
client_ = std::make_unique<mongocxx::client>(uri);

BSON: Use Basic Builder for Complex Documents

Never use stream builder for nested documents or updates — it causes data corruption.

// ❌ WRONG - Stream builder corrupts; ALL FIELDS GET DELETED
document setDoc{};
setDoc << "field1" << value1 << "field2" << value2;  // Not finalized!
document updateDoc{};
updateDoc << "$set" << setDoc << finalize;  // Passing unfinalized doc!
// Result: document becomes { _id: ObjectId(...) } - ALL DATA LOST!

// ✅ CORRECT - Basic builder
using bsoncxx::builder::basic::kvp;
auto setFields = bsoncxx::builder::basic::document{};
setFields.append(kvp("field1", value1));
setFields.append(kvp("field2", value2));
auto updateDoc = bsoncxx::builder::basic::document{};
updateDoc.append(kvp("$set", setFields.extract()));
collection.update_one(filter, updateDoc.extract());

• Use basic builder for $set, $push, $pull, nested docs.
• Call .extract() on each subdocument before adding to parent.
• Stream builder ONLY for simple, flat filters (e.g. document{} << "email" << "[email protected]" << "active" << true << finalize for find_one).

When to Use Each Builder

Use Case	Builder	Why
Complex updates ($set, $push, etc.)	Basic Builder	Prevents data corruption
Nested documents (arrays, subdocuments)	Basic Builder	Explicit extraction required
Multiple operators in one update	Basic Builder	Safer composition
Simple flat queries/filters	Stream Builder	More concise
Production database operations	Basic Builder	Safer and maintainable

DON'T: Mix Builder Types

// ❌ BAD
document streamDoc{};
basic::document basicDoc{};
streamDoc << "$set" << basicDoc;  // Wrong!