This add-on is operated by ObjectLabs

Power your app with the fastest-growing MongoDB-as-a-Service in the world.


Last Updated: 18 March 2014

add-on database mongodb nosql

Table of Contents

MongoLab is a fully-managed cloud database service featuring highly-available MongoDB databases, automated backups, web-based tools, 24/7 monitoring, and expert support. By hosting MongoDB on MongoLab’s Database-as-a-Service (DBaaS) platform, Heroku users are free to focus their attention on product development instead of operations.

Through the MongoLab add-on, Heroku users can instantly have MongoDB databases running on Amazon EC2 and available for their Heroku applications.

Adding MongoLab

You can add MongoLab to your app either through the add-on catalog or through the heroku command.

To add our free, Sandbox plan (the default):

$ heroku addons:add mongolab

Please note that Sandbox databases should not be used in production, as they are intended for development/testing environments that do not require high availability.

To add another plan, for example our shared-cluster-large Cluster plan which provides high-availability:

$ heroku addons:add mongolab:shared-cluster-large

You can find the complete list of plans that we offer in Heroku add-on catalog here.

Getting your connection URI

The MongoLab add-on contributes one config variable to your Heroku environment: MONGOLAB_URI.

Use the heroku config command to view your app’s config variables.

$ heroku config | grep MONGOLAB_URI
MONGOLAB_URI => mongodb://

The URI contains all the MongoDB connection information you will need to connect to your database. Most client libraries support using the URI directly. However, some will require pulling the components of the URI apart. In case you need to do that for your library, the MONGOLAB_URI is in the below format.

URI format for Single-node plan:


URI format for Cluster plan:


Connecting to your MongoDB instance

You have many options for connecting your Heroku app to your MongoDB instance. We’ve provided some information and help for the ones that have gained the most traction in the Heroku MongoDB community.

MongoDB Ruby Driver

The Ruby driver is officially supported by 10gen, the maker of MongoDB. It is a robust interface to MongoDB but does not provide Object Document Mapper (ODM) features.

If performance is critical for your app, we strongly recommend installing the optional bson_ext gem in addition to the required mongo gem:

$ gem install mongo
$ gem install bson_ext

The Ruby driver does not yet have a way of getting a DB object back directly from a URI. Thus, to use the MONGOLAB_URI you will have to do some parsing.

The code below demonstrates connecting to MongoLab using the Ruby driver and printing out the names of all the collections in your database.

require 'mongo'
include Mongo

mongo_uri = ENV['MONGOLAB_URI']
db_name = mongo_uri[%r{/([^/\?]+)(\?|$)}, 1]
client = MongoClient.from_uri(mongo_uri)
db = client.db(db_name)
db.collection_names.each { |name| puts name }


Mongoid is a MongoDB ODM for Ruby that makes it very easy to get going. We have written an extensive post on running Mongoid3 in production. Simply install the mongoid gem, generate the config, and edit the production config to use the MONGOLAB_URI.

Your Gemfile should include:

source ''
gem 'mongoid'

The production configuration for the config/mongoid.yml is as follows:

# mongoid 3.x
# As discussed in:
      # The standard MongoDB connection URI allows for easy
      # replica set connection setup.
      # Use environment variables or a config file to keep your
      # credentials safe.
      uri: 'mongodb://username:password@host1:port1,host2:port2/database'

        # The default consistency is :eventual, which reads from
        #secondaries when possible.
        # Strong forces reads to primary.
        # We recommend using strong consistency.
        consistency: :strong

        # max_retries specifies the number of times to attempt
        # an operation before giving up.
        max_retries: 30

        # retry_interval specifies the number of seconds to wait
        # before retrying a single operation.
        retry_interval: 1

        # The default timeout is 5, which is the time in seconds
        # for an operation to time out.
        # We recommend 15 because it allows for plenty of time
        # in most operating environments.
        # Mongoid doubles the configured value (known issue) so
        # 15 results in a timeout of 30s.
        # Note that if you have a long-running query
        # (over 30 seconds), it will time out.
        # See our example for long-running queries in the blog
        # post referenced above.
        timeout: 15

Further documentation on Mongoid configuration and options can be found on the Mongoid’s Getting Started page.

Using MongoLab’s admin tools for MongoDB

MongoLab provides an easy-to-use web interface for visually managing MongoDB instance(s) and application data. Our user interface is seamlessly integrated with Heroku’s.

Accessing the admin GUI

To access the MongoLab UI:

  1. Log in to Heroku
  2. Select your app
  3. Under the “Add-ons” section, click on your MongoLab add-on

Alternatively, you can use the heroku command:

$ heroku addons:open mongolab

Taking backups

Using MongoLab’s admin UI to schedule backups

  1. On the home page of our admin GUI, click on the row representing your database
  2. Click on the “Backups” tab
  3. Click on the “Schedule one-time mongodump” button
  4. Once the backup is complete, click on the down-arrow icon to download this backup to your local machine

This backup will be in the form of a binary dump, the output of MongoDB’s mongodump utility.

Alternatively, you can also use this same “Backups” tab to schedule recurring backups to either a secure MongoLab container on Amazon S3, Rackspace Cloud Files, etc. or to a cloud storage container of your own.

If you choose to store your MongoLab backups in your own Amazon S3 container, we highly recommend that you secure your S3 bucket.

What if I don’t create a custom backup plan?

We take periodic system-wide backups of all of our servers on shared virtual machines. Regardless of what database plan you have or whether you have defined custom backups, we backup every server on shared virtual machines regularly for disaster recovery purposes.

In the event that you accidentally delete or corrupt your database, you can contact us, and we will do our best to restore it for you from one of our system backups. We will be able to help you much more quickly if you provide us with your connection URI; please mask your credentials though!

That being said, we strongly recommend using our admin UI to schedule backups into one of MongoLab’s secure Amazon S3 buckets or your own S3 bucket so that you can schedule them at a frequency that makes sense for your app and transfer/restore backups without waiting for our assistance.

Setting up MongoDB Monitoring System (MMS)

MongoDB, Inc. provides a MongoDB Monitoring Service (MMS) which collects key database metrics and displays them both historically and graphically.

Our Cluster plan, shared-cluster-large, includes an MMS agent that MongoLab will run on your behalf to monitor your database. Although our Single-node plans do not come with MMS, rest-assured that MongoLab monitors all of our users’ databases 100% of the time.

How to access MMS Monitoring

Here are instructions to set up access to MMS Monitoring.

Ensuring high availability

Our Cluster plan, shared-cluster-large, provides multi-zone automatic failover.

Steps to test failover on Cluster plan databases

  1. Sign-in to MongoLab’s admin UI

  2. Ask your current primary to step down by clicking on the “Servers” tab, clicking on the row representing your current primary, click on the “Tools” tab and issuing the replSetStepDown command.

  3. Observe your application continuing to work after about 30 seconds of connection hiccups. You should not need to restart your application.

  4. Repeat steps 2 & 3 until you’re satisfied

Please note that failover is not seamless - the driver will hiccup. We can talk to you about best practices around implementing retry loops if that makes sense for your application if you email

Changing or upgrading plans

If you are already using MongoLab as an add-on for your Heroku app and would like to change plans, please review the plans we offer on Heroku here and then follow the steps outlined below. If you’re looking for a MongoDB setup that’s not yet available on Heroku, you can review our full product offering at MongoLab’s website here.

Please do not hesitate to contact if you would like help figuring out what setup makes the most sense for your specific use case.

Steps to change plans on Heroku

  1. Stop your app and any other processes writing to your database
  2. Backup your database using mongodump
  3. Remove your existing add-on
  4. Add a new add-on (see available plans here)
  5. Restore your database using mongorestore
  6. Change your connection string info in your app
  7. Restart your app

Here’s an example of what you would type:

$ mongodump -h -d heroku_app1234 -u heroku_app1234 -p random_password -o dump-dir
$ heroku addons:remove mongolab
$ heroku addons:add mongolab:shared-cluster-large
$ mongorestore -h <new host>:<new port> -d heroku_app1234 -u heroku_app1234 -p <new_password> dump-dir/heroku_app1234

If you’d like us to help you with this process or would like to discuss other options for minimizing downtime while changing plans, please contact

Where will be my database be hosted?

MongoDB databases provisioned through Heroku’s MongoLab add-on program will always be hosted on Amazon EC2 (where the Heroku platform itself is hosted) to minimize network latency and data transfer costs.

More specifically, your MongoDB database will be hosted either in Amazon’s US East (Virginia) region or in Amazon’s Europe (Ireland) depending on which region you selected when you originally created your Heroku app.

What version of MongoDB will my database be running?

MongoDB databases provisioned through Heroku’s MongoLab add-on program will always be on MongoLab’s default version. Our default version is posted here.