MongoLab

This add-on is operated by ObjectLabs

Fully managed MongoDB-as-a-Service

MongoLab

Last Updated: 25 March 2015

add-on database mongodb nosql

Table of Contents

MongoLab is a fully managed cloud database service featuring automated provisioning and scaling of MongoDB databases, backups, 24/7 monitoring and alerting, MongoDB GUI tools, 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.

Existing MongoLab users

If you already have an account with MongoLab, you can find steps to connect to your Heroku application to your MongoLab database in our connection documentation. You will need to configure your MongoDB driver to use the connection URI.

To protect your database, it’s best practice to store your database credentials in a Heroku config variable. This allows you to avoid hard coding credentials directly in your application code. For example, you may run:

$ heroku config:set PROD_MONGODB=mongodb://dbuser:dbpass@host1:port1,host2:port2/dbname

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://heroku_app1234:random_password@ds029017.mongolab.com:29017/heroku_app1234

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:

mongodb://dbuser:dbpass@host:port/dbname

URI format for Cluster plan:

mongodb://dbuser:dbpass@host1:port1,host2:port2/dbname

Connecting to your MongoDB instance

You have many options for connecting your Heroku app to your MongoDB instance. To help out new developers, we have set up the MongoLab Language Center which demonstrates how to connect and query a MongoDB database in C#, Java, Node.js, PHP, Python and Ruby.

You’ll notice that in our driver examples we use a string (in the standard URI format) to connect. Simply replace this with the connection URI you’ve obtained from the above Getting your connection URI step and you’re good to go. Be sure to reach out to support@mongolab.com if you need any help!

Below, we’ve provided some information and help for the drivers that have gained the most traction in the Heroku MongoDB community.

MongoDB Ruby Driver

The Ruby driver is officially supported by MongoDB, Inc., 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 }

Mongoid3

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 'http://rubygems.org'
gem 'mongoid'

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

# mongoid 3.x
#
# As discussed in: http://blog.mongolab.com/2014/02/mongodb-driver-tips-tricks-mongoid-3
#
production:
 sessions:
   default:
     # 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'

     options:
       # 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

       # Set this to ensure that your writes are a round-trip operation
       # and are confirmed by the system.
       safe: true

       # refresh_interval specifies the number of seconds to cache server information.
       # Lowering this number will help the driver recover more quickly from changes to replica set reconfiguration
       refresh_interval: 10

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

Mongoid4

For those using Mongoid 4, the production configuration for the config/mongoid.yml is as follows:

# mongoid 4.x
#
production:
 sessions:
   default:
     # The standard MongoDB connection URI allows for easy
     # replica set connection setup.
     # Use environment variables or a config file to keep your
     # credentials safe e.g. <%= ENV['MONGOLAB_URI'] %>.
     uri: 'mongodb://username:password@host1:port1,host2:port2/database'

     options:
       # 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

       # refresh_interval specifies the number of seconds to cache server information.
       # Lowering this number will help the driver recover more quickly from changes to replica set reconfiguration
       refresh_interval: 10

       # pool_size default size is 5 connections.
       # If you're running a lot of threads, you may consider increasing pool_size
       # to the number of threads you're running e.g.
       # poolsize: <%= ENV['NUM_THREADS'] %>

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.

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 support@mongolab.com.

Changing or upgrading plans

MongoLab supports automated plan changes between any of our multi-node plans. To change to/from a single-node plan, a manual process is required.

Changing between multi-node cluster plans

From your app’s Heroku dashboard, click the Edit button in the Add-ons list, then select the MongoLab plan to request. We will update you by email as the upgrade occurs.

We perform plan changes using a rolling node replacement. This process preserves high availability and does not require that we update your connection string. However, a replica set failover is necessary to complete the plan change. A failover will leave the cluster without a primary for 5-20 seconds, but if your application/driver is configured to gracefully handle failover events, the process is relatively seamless.

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 support@mongolab.com if you would like help figuring out what setup makes the most sense for your specific use case.

Changing to or from a single-node plan 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 ds029007.mongolab.com:29007 -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 support@mongolab.com.

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. You can visit our homepage to learn more about MongoLab on AWS.

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.