Introducing the New C++ Driver



This post introduces an entirely new MongoDB C++ driver. We describe the new driver, provide examples, and invite users for feedback on the new driver.

In a previous post we announced the legacy-1.0 release of the legacy C++ Driver, a simplified fork of the internal client library of the MongoDB server. To remind readers of the current branches of the C++ driver:

  • 26compat - a largely unchanged version of the driver as of MongoDB 2.6 (April 2014) with some changes backported from the server.
  • legacy - an improved derivative of the client from the server codebase with a mostly backwards compatible interface. This branch will be actively developed and improved through the release of MongoDB 3.2.
  • master - The entirely new and modern MongoDB driver we are introducing in this article.

While the legacy-1.0 release brought many improvements, the API of the legacy C++ driver is still constrained by design decisions made long ago. In the years since the original DBClientConnection was designed, the arrival of C++11 (and now C++14) has brought with it major changes in C++ library design. To capitalize on these modern C++ features and design idioms, and to build on all that we have learned in the past 5 years, the C++ driver team has recently begun development of a new, modern driver adhering to current MongoDB driver standards. While the legacy driver will still receive bugfixes and limited backports of relevant server changes, development of new features and functionality will take place primarily on the ‘master’ branch.

Project Overview

The new driver consists of two separate libraries, bsoncxx, a BSON manipulation library,and mongocxx, the MongoDB client. These libraries wrap the corresponding C driver libraries, libbson and libmongoc. Using the existing C libraries as a base gives the new C++ driver a high-performance and well tested implementation. At the same time, the use of the C libraries in the implementation is opaque to consumers of the library, and the driver’s interfaces are carefully designed to permit other potential backends.

API Examples

Here is an example that uses the C++ Driver to print all the documents in a collection:

mongocxx::driver::client c{“mongo://”};
auto col = c[“testdb”][“testcol”];
for (auto doc : col.find({}) {
    std::cout << bsoncxx::to_json(doc) << std::endl;

The find method on collection returns a cursor object. As cursor implements begin() and end() methods that return a cursor::iterator, we can use the range-based for loop added in C++11 to succinctly iterate over the documents in the collection

In the next example (continued from above), we insert a document into our collection:

bsoncxx::builder::stream::document doc;
doc << “mykey” << “myvalue” 
    << “mynum” << 1;
optional<result::insert_one> res = col.insert_one(doc);

We use the builder::stream BSON interface supplied by bsoncxx to construct a document. We insert it using the insert_one method, which returns an optional1 that will be engaged with a result::insert_one when it is an acknowledged write (true by default).

This is just a small sample of the new API. To see a more comprehensive set of examples, look in the examples directory of the source tree, or browse the documentation.


Unlike the legacy driver, which is provided only as source code with no guarantees of ABI stability, the new driver will be versioned both at the API and ABI level. In the future, when the driver’s interfaces have stabilized, we hope to distribute the driver via package managers. We hope that this developer-friendly approach will greatly simplify writing and distributing applications that use the driver.

Build System Improvements

While the legacy driver uses a slimmed-down derivative of the server’s SCons-based build system, the new driver is built with CMake. This allows us to generate a Ninja build file for speedy incremental builds. Additionally, CMake can easily generate project files for IDEs such as XCode, Eclipse and Visual Studio. We also provide pkg-config files and CMake Find modules for bsoncxx and mongocxx that will make it simple for developers to include the new driver in their applications.

So Which Driver Should I Use?

  • If you are prototyping or experimenting, can tolerate breaking changes, and do not require a stable release stream, use the new driver.
  • If you are maintaining an existing application, or developing a new application that will be going into production in the next few months, use the legacy driver.
  • If you are using an older driver in production and cannot currently migrate to the legacy driver, continue to use the 26compat driver.

Future Work and Feedback

The new driver is currently under active development. Currently, only a subset of the approved MongoDB driver specifications are implemented. We anticipate issuing the first unstable release of the new C++ driver in Spring 2015. We plan to add support for additional functionality such as GridFS, authentication, and geospatial queries as the MongoDB drivers team standardizes on interfaces for these features.

The C++ driver development team is very interested in early feedback on the design and implementation of the new driver. Community feedback will help us determine what additional features will make it into the upcoming unstable release. Users experimenting with the driver are welcome to post general feedback and comments on the mongodb-dev mailing list; bug reports should be directed to the driver’s JIRA Project.