Introducing the Legacy C++ Driver 1.0



The C/C++ Driver team at MongoDB is pleased to announce the 1.0 release of the legacy C++ driver. The legacy C++ driver provides a (mostly) compatible interface to previous releases of the C++ driver with many bugfixes, additional features, and a simplified implementation. In this post we will explain the reasons for creating the legacy C++ driver, the major improvements it offers, and our roadmap for the project going forward.

The Road to the Legacy Driver

For much of MongoDB’s history, the C++ driver was developed within the server repository. The server contains an internal client library used by the mongo shell and the mongos query router. The C++ driver was initially a separate build target that exposed this internal library to developers of standalone C++ applications that connected to MongoDB.

However, using the server codebase as the basis of the driver had several consequences that negatively affected developer experience. For one, building and installing the C++ driver required the full server source code, making it unnecessarily difficult for C++ developers to get up and running. Much of the driver was shaped by implementation details of mongod and mongos, making it bloated and difficult to learn. Additionally, the driver lacked important features such as support for bulk writes. Overall, the usability, design and feature set of the C++ driver significantly lagged the drivers for other popular languages like Python, Java, and Ruby.

Maintaining the driver as a component of the server codebase also put the needs of the server in conflict with that of the driver. Sometimes the server required changes to the codebase that were undesirable for users of the driver, and at other times there were changes desired by driver users that were unsuitable for the server. In other words, it was the was the worst of both worlds.

As numerous StackOverflow and mongodb-user posts from unhappy developers indicated, connecting an application to MongoDB with the C++ driver was not a positive experience. By the MongoDB 2.6 release, it was finally decided that this state of affairs was untenable.

The Fork

In April 2014, with a mixture of SCons, git, and shell incantations, the minimal set of source files needed to build the driver was forked from the 2.6 codebase into a separate project. As detailed in an earlier post, we decided to maintain three branches of the C++ driver from that point forward:

  • 26compat - a largely unchanged version of the driver with some changes backported from the server
  • legacy - a mostly backwards compatible version of the driver to be actively developed and improved
  • master - An entirely new and modern MongoDB driver written in C++11
Since the initial fork, there has been a frenzy of activity on the legacy branch of the C++ driver. To give a high-level overview:
  • 320 JIRA issues resolved as “Fixed”
  • 474 commits
  • 402 files changed, 29,635 insertions, 19,003 deletions
  • 14 contributors, 6 with more than 5 commits

What are the major improvements?

The surface area of the driver has been greatly reduced, with fewer client headers and functions published as part of the API, and a great deal of unnecessary functionality has been removed. The build system has been reworked as well, with idiosyncratic targets like ‘smokeCppUnitTests’ replaced with more obvious ones like ‘unit’. We’ve also added support for MongoDB 3.0 features. While there were breaking changes to the API, we believe that consumers of the 2.6 driver should have a fairly easy time migrating to the legacy 1.0 driver.

Here is a list of some of the major improvements made to the legacy driver:

  • Acknowledged writes are now the default
  • Support for all write concern types
  • Full support for write commands and bulk writes
  • New helpers for using the MongoDB Aggregation Pipeline
  • Support for SCRAM-SHA-1, the new default authentication mechanism in MongoDB 3.0
  • Support for big endian architectures (tested on SPARC)
  • The driver’s test-suite now uses mongo-orchestration to run tests against multiple versions of MongoDB standalones, replica sets, and sharded clusters
  • New helpers for writing Geospatial queries
  • Greatly simplified build process
  • Improved support for building the driver as a shared library

What’s next for the legacy driver?

Now that the legacy driver has stabilized, we will limit future changes to bug fixes and backports of relevant server commits. In addition, the driver will be updated as needed to support communication with MongoDB 3.2.

What about the C++11 driver?

Future development efforts will be focused on the master branch of the driver, which will feature a completely new API based on C++11 and other modern C++ design principles. A forthcoming blog post will provide an in-depth description of the new driver’s design and features.

We want your feedback!

We also would like to hear feedback from the community on the legacy driver - please reach out to the developers on the mongodb-user list with any questions, or file tickets for any bugs on the JIRA tracker in the CXX project. We also welcome pull requests submitted on the driver’s GitHub page.

If you’re interested in learning more about the architecture of MongoDB, download our guide:

Download the Architecture Guide

About Adam Midvidy

Adam Midvidy is an engineer on the MongoDB Platforms Team and a contributor to the Legacy C++ Driver.