Announcing Ruby Driver 2.0, a Rewrite

Sign up for our monthly newsletter

Thanks for subscribing to the newsletter. This is your channel for getting the latest notifications of server and driver releases, details on local MongoDB events, updates on education programs, and the skinny on all things MongoDB.

The MongoDB Engineering Journal

How rubyists are using MongoDB today

Given that the majority of the Ruby community is using Ruby on Rails, the interface for most Ruby users to MongoDB is the mongoid gem, an Object-Document-Mapper that allows Rails to work with the database. This gem is independent of the mongo and bson gems. The mongo gem is the official driver to MongoDB and the bson gem is the serializer/deserializer between BSON documents and Ruby hashes.

As I wrote last year, rubyists are at a great advantage in using MongoDB because they already make frequent use of document objects (i.e. Ruby hashes) and build Object-oriented applications. On the other hand, rubyists have been at a disadvantage because their main entry point to the database, Mongoid, is not an official product of MongoDB Inc. and support for it is not guaranteed by the company.

That is all going to change with the release of the new Ruby driver, version 2.0.

The disjoint Ruby community

Durran Jordan authored Mongoid 6 years ago to be Rails' Active Record replacement for MongoDB. Mongoid aimed to provide a similar API to Active Record, and it’s largely due to this gem that MongoDB had adoption in the Ruby (i.e. Rails) community. Mongoid then evolved through several releases and eventually came to use its own driver, Moped. Mongoid versions 3.0 and higher use this separate driver.

The MongoDB Ruby community then split into a three different cohorts, using the following different gem combinations:

Ruby/Rails users:

mongoid version >= 3.0

moped

bson version >= 2.0

Ruby/Rails users:

mongoid version < 3.0

mongo 1.x series

bson 1.x series

Ruby users:

mongo 1.x series

bson 1.x series

Over the course of time, the MongoDB server became increasingly rich in functionality and the list of driver requirements grew. Moped subsequently fell behind in feature completion and the Ruby community became stuck; Rails and Ruby users had to choose between using the most recent version of Mongoid and a feature incomplete driver (moped), or an older version of Mongoid and the most recent official MongoDB Inc. driver (mongo).

Centralizing the community

Durran and the Ruby team decided that the best solution would be to officially work together on building a new driver and getting Mongoid version >= 5.0 to use it. That way, the Ruby team, now benefiting from Durran’s expertise, could support the majority of rubyists using MongoDB and dissipate much of the confusion caused by saturating the community with a plethora of gems having overlapping purposes.

The team built a new bson gem last year and Mongoid is already using it. bson gem version >= 2.0 is the rewrite. The new driver also uses this new bson gem.

This table illustrates just how much more feature-rich the new Ruby driver is, compared to Moped.

Feature

Mongo

Moped

CR Auth

x

x

GSSAPI Auth

x

SCRAM-SHA-1 Auth

x

X509 Auth

x

Plain/LDAP Auth

x

Basic CRUD

x

x

Query Framework Fluent API

x

x

Write Commands

x

x

Bulk API

x

Connection Pooling

x

x

Asynchronous Server Monitoring

x

Aggregation Framework Fluent API

x

Map/Reduce Fluent API

x

Event Framework for External Hooks

x

Logging Instrumentation

x

x

GridFS API

x

Index Management API

x

x

BSON 2.x

x

x

SSL Connections

x

x

Unix Socket Connections

x

Tag sets in read preferences

x

Proper nearest read preference

x

SDAM spec implementation

x

Server Selection spec implementation

x

CRUD spec implementation

x

The new Ruby driver

The new Ruby driver is not a refactor, it is a complete rewrite. The design is cleaner and the API is more intuitive than that of the old driver. The Ruby team is confident that the completed product is strong, as the team members collectively have experience maintaining the current driver for many years (mongo), building a community driver (moped), and creating an ODM (mongoid). The new driver is more approachable and easier to maintain, and that’s good for everyone in the Ruby community.

The 1.x series bson gem code is actually inside the 1.x series ruby driver repository and the two are always released in parallel.

The 2.0 series bson gem can be found in a separate repository. The team realized that this made more sense, as the driver depends on the bson gem and there is no gain from coupling the codebases.

Notable Improvements in the MongoDB Ruby driver vs. Moped

The MongoDB drivers team wrote and published various specifications for driver behavior over the last year. Among them are the Server Discovery and Monitoring (SDAM) spec and the Server Selection spec. Implementation of these specifications in the new Ruby driver alleviates some frustrations expressed by Moped users. For example, Moped doesn't have support for failover so when one or more servers are not reachable, scans to update the driver's view of the cluster state block regular database operations. The SDAM spec describes a method of asynchronous monitoring that avoids this scenario completely in the new Ruby driver.

Moped also falls short on a lot of essential functionality for supporting server version 3.0. For example, it simply doesn’t support authentication with MongoDB 3.0 or recent versions of the wire protocol (which includes commands such as listCollections, listIndexes, and the ability to do bulk writes). Integrating Mongoid with Ruby driver 2.0 will bring a lot of this functionality and forward-compatibility to the ODM.

Why upgrade Mongoid? Why upgrade to the new driver?

There are many reasons to upgrade to mongo gem version 2.0 and to mongoid gem version 5.0, when it’s released. First off, these versions support MongoDB 3.0. Secondly, the driver rewrite incorporates a lot of improvements and design changes we’ve learned are critical from collectively having maintained a Ruby interface to MongoDB for years. Following these releases, we will turn our focus to maintaining the rewrite and Mongoid 5.0 and will put the 1.x series of the driver into maintenance mode. New features will not be added and development work will consist only of bug fixes and minimal features necessary for supporting the most recent version of the server. The same can be said of Moped; this community driver will go into maintenance mode and will only exist to support the Mongoid 3.x - 4.x series.

Help us test it out!

Calling all mongoid and mongo gem users! We need your help trying out the new driver either independently or under mongoid 5.0’s covers. The mongo gem 2.0 series is now available in RubyGems. To get it, simply do

gem install mongo

The mongoid gem version 5.0 will be available soon as a beta release in RubyGems and we’d welcome your help testing it as well.