Introducing MongoClient



Today we are releasing updated versions of most of the officially supported MongoDB drivers with new error checking and reporting defaults. See below for more information on these changes, and check your driver docs for specifics.

Over the past several years, it’s become evident that MongoDB’s previous default behavior (where write messages did not wait for a return code from the server by default) wasn’t intuitive and has caused confusion for MongoDB users. We want to rectify that with minimal disruption to the MongoDB apps already in production.


First, I  thought it would be interesting to share the history behind the previous default behavior, and why and how we are changing it.

The old behavior goes back to the very beginning of 10gen, before Dwight and I imagined MongoDB as a stand-alone database. When we first started 10gen in the fall of 2007, we set out to build a full platform as a service stack with MongoDB as the data layer. This was a fully hosted system (still open source), that encompassed a load balancer, auto scaling application server and data tier. The application side was a full server side JavaScript environment.

Every request into 10gen was an http request.  So you can imagine a controller for doing some user analytics could act like this:



  { _id : db.getParameter( “sect” ) } , 
  { $inc : { count : 1 } } , /*upsert*/true );
  { _id : db.getParameter( “page” ) } , 
  { $inc : { count : 1 } } , true );

Writes in that system did not individually wait for a response from the database.  However, the application server itself always checked the database for any errors that occurred during the entire page load (using getLastError and getPrevError) so that the user/system would be notified of any issues.  Developers could of course also call getLastError whenever they wanted.  This worked great in the platform, as we were able to control the whole access pattern.

In January of 2009, we decided for a variety of reasons to only focus on the data tier (MongoDB).  At that time, a number of people had been using MongoDB in production for almost a year as part of the full stack, and a lot more were very interested in using it standalone.

Over the course of the next few months, we wrote the initial implementations of the Java, Python, Ruby and PHP drivers.  All of those drivers used the same network protocol as the original application server, which has non-synchronous write operations.  It seemed natural to us at the time given the background, but it is clear that this is not intuitive for new users of MongoDB who had never used the full stack.

New Behavior

Going forward, the default clearly has to be to wait for the database to acknowledge all writes; that is much more intuitive. Just flipping the default however, would be backward breaking for apps in production.

The change we’re going to make is to add a new top level connection class in each driver.  For example, in Java, previously you would do:

Mongo mongo = new Mongo( “mongoserver” );

That class, Mongo, will maintain the old default, and become deprecated.

For new code, you will do:

MongoClient mongo = new MongoClient( “mongoserver” );

which will default to a WriteConcern of 1.  Everything else will be the same.

The old class will remain for quite a while (but not forever), so that we won’t break old code right now.  As another benefit, every single driver will use MongoClient so for the first time at least the top level class will have the same name across the board.  All documentation, tutorials, and sample code have been changed accordingly. 

More Information

  • For driver downloads, docs, and tutorials, please visit the drivers page on the MongoDB wiki.
  • For bug reports and feature requests please visit
  • For any other feedback, please leave a comment on this post or in our user forum.

We appreciate your continued support and feedback on MongoDB.

- Eliot and the MongoDB Team