Moving Mongoid In-House

Durran Jordan


One of the benefits of being part of an open-source community is that we have incredible 3rd-party contributions from our community. The more traction these tools gain, the more we need to be able to support them as part of the MongoDB ecosystem, which means being able to push bug fixes, schedule releases, and generally drive the product forward.

In this post we’ll discuss one of these projects, Mongoid, an ODM developed by the Ruby community.

What is Mongoid, and who uses it?

The Ruby community has a variety of developer tools for MongoDB. Developers who prefer to access the database via the driver level use the official MongoDB Ruby driver, and those who prefer to leverage an ODM like Mongoid instead. Mongoid provides an Active Record interface for working with documents as domain models in the application, as well as providing features such as a query DSL, schema constraints, and relational database style relations.

The Challenge

There were two major steps to bringing Mongoid in-house. The first was to make the core driver’s API flexible enough for an ODM’s needs. The second was to do an entire rewrite of the BSON library in order to make it both extensible and easily maintainable. The greatest challenge was making sure all of this happened with as little disruption as possible for both Ruby driver and Mongoid users.

The Strategy

We decided to rewrite the core BSON library in Ruby, separating it from the codebase and giving it its own release schedule. The focus of the rewrite was to make it more Ruby-like, following the patterns set forth by existing JSON and YAML implementations. Upon completion this was immediately included in Mongoid and Moped.

Once the BSON library was rewritten, the next step was to do a complete rewrite of the core Ruby driver. The driver was not only rewritten to meet the needs of Mongoid’s API, but it was also the first Ruby driver release to comply with the MongoDB driver team’s cross-platform driver specifications. With these enhancements, the new driver was made a dependency of Mongoid master and released with Mongoid 5.

The last steps were administrative, and included the migration of the Mongoid website at to the MongoDB ecosystem documentation, the migration of all issues into the official MongoDB Jira project, and the move of the repo to the official MongoDB Github organization.


Upgrading to Mongoid 5 requires minimal effort. The bulk of upgrading efforts will entail changing mongoid.yml, as all of the configuration options have changed with Mongoid 5. Also note that the references to session are now replaced with client, as the underlying entry point to the driver is now a Mongo::Client and not a Moped::Session.

The new mongoid.yml configuration can be found in the Mongoid 5 documentation.

The small number of API changes that need to be addressed are:

  • find_and_modify has been removed and replaced with 3 options: find_one_and_update, find_one_and_delete and find_one_and_replace.
  • text_search has been removed as it is now a $text option in a query from 2.6 on.
  • first and last no longer add an _id sort when no sorting options have been provided. In order to guarantee that a document is the first or last, it needs to now contain an explicit sort.

Lastly, support for MongoDB 2.2 and lower is removed to fall in line with the MongoDB versions that the core driver supports.


The currently live is powered by Mongoid 5.


We now officially support Mongoid 5, and will continue to support all future versions. Previous versions of Mongoid running on Moped are not supported. To report an issue or request a feature, please open a ticket at the Mongoid Jira Project.

Want more MongoDB? Read our white paper to learn about the latest features in MongoDB 3.0.
What's new in MongoDB 3.0

About the Author - Durran Jordan

Durran is a software engineer in the MongoDB integrations and Ruby driver teams, focused on developing 3rd party integrations with MongoDB and tools in the Ruby developer community, respectively. He is the original author of Mongoid and has been active in its development over the past 6 years.