MongoHQ is a cloud-based hosted database solution that allows you to quickly and easily create and get your apps up and running with MongoDB. Through the MongoHQ add-on for Heroku, you can, with just a couple of steps, have a MongoDB instance running and available for your Heroku applications.

Adding MongoHQ to Your App

To add MongoHQ to your Heroku application, simply install the MongoHQ add-on:

$ heroku addons:add mongohq:free

This will provision a database with MongoHQ and set the heroku evironment variable MONGOHQ_URL with a mongodb connect string.

Using MongoHQ from Ruby

Gem Options and Setup

You have a couple of options when deciding what method you will use for connecting your application to your Mongo database. We will highlight these choices and you can use the gem that you feel works best for what you are trying to accomplish.

MongoMapper

The mongo_mapper gem by John Nunemaker is a Ruby object mapper for Mongo. It allows you to maintain the same ActiveRecord structure that you are familiar with in Rails, but utilize MongoDB instead.

Mongoid

The mongoid gem by Durran Jordan is a robust ODM framework that acts as an API to connect to documents within MongoDB.

Mongo Ruby Driver

If you are using mongo in such a way that you don’t need an ODM then you can simply connect with the ruby driver for MongoDB. The mongo gem maintained by Kyle Banker of 10gen is an active project. More information about it can be found at MongoDB.

Using the MongoMapper Gem in Rails

In config/environment.rb:

# in your initializer block
config.gem "mongo_mapper"

In config/initializers/mongo.rb:

MongoMapper.config = { 
  Rails.env => { 'uri' => ENV['MONGOHQ_URL'] || 
                          'mongodb://localhost/sushi' } }

MongoMapper.connect(Rails.env)

For more information on using MongoMapper to set up a basic application with Rails and MongoDB, we encourage you to check out Ryan Bates’ screencast.

Using the Mongo Ruby Driver

If you are using Ruby driver version >= 0.19:

require 'uri'
require 'mongo'

uri = URI.parse(ENV['MONGOHQ_URL'])
conn = Mongo::Connection.from_uri(ENV['MONGOHQ_URL'])
db = conn.db(uri.path.gsub(/^\//, ''))

If you are using Ruby driver version < 0.19:

require 'uri'
require 'mongo'

uri = URI.parse(ENV['MONGOHQ_URL'])
conn = Mongo::Connection.new(uri.host, uri.port)
db = conn.db(uri.path.gsub(/^\//, ''))
db.authenticate(uri.user, uri.password)

Using MongoHQ from Java

MongoDB offers a standard Java client. In order to use this client in your project you have to declare the dependency in your build and initialize the connection from the environment variable that Heroku provides to your application.

Sample code for the MongoDB demo Java application is available on GitHub.

Add the Mongo Java driver to Your Pom.xml

Add the following dependency to your pom.xml:

<dependency>
    <groupId>org.mongodb</groupId>
    <artifactId>mongo-java-driver</artifactId>
    <version>2.7.2</version>
</dependency>

Use MongoDB in your application

URI mongoURI = new URI(System.getenv("MONGOHQ_URL"));

MongoURI mongoURI = new MongoURI(System.getenv("MONGOHQ_URL"));
DB db = mongoURI.connectDB();
db.authenticate(mongoURI.getUsername(), mongoURI.getPassword());  
//Use the db object to talk to MongoDB
Set<String> colls = db.getCollectionNames();

Using MongoDB with Spring

Use the following Java Configuration class to set up a DB object as a singleton Spring bean:

@Configuration
public class SpringConfig {
    @Bean
    public DB getDb() throws UnknownHostException, MongoException {
        MongoURI mongoURI = new MongoURI(System.getenv("MONGOHQ_URL"));
        DB db = mongoURI.connectDB();
        db.authenticate(mongoURI.getUsername(), mongoURI.getPassword());
        
        return db;
    }
}

or the following XML configuration file:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
  xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xmlns:context="http://www.springframework.org/schema/context"
  xsi:schemaLocation="http://www.springframework.org/schema/beans
      http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
      http://www.springframework.org/schema/context
      http://www.springframework.org/schema/context/spring-context-3.0.xsd">

    <context:annotation-config/>
    <context:property-placeholder/>
  
    <bean id="mongoURI" class="com.mongodb.MongoURI">
      <constructor-arg value="${MONGOHQ_URL}"/>
    </bean>
  
    <!-- create db object by calling getDB on mongo bean -->
    <bean id="db" class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
      <property name="targetObject"><ref local="mongoURI"/></property>
      <property name="targetMethod"><value>connectDB</value></property>
    </bean>  
 
    <!-- call authenticate on db object -->
    <bean id="authenticateDB"
        class="org.springframework.beans.factory.config.MethodInvokingFactoryBean">
        <property name="targetObject"><ref local="db" /></property>
        <property name="targetMethod">
            <value>authenticate</value>
        </property>
        <property name="arguments">
            <list>
                <value>#{ @mongoURI.getUsername() }</value>
                <value>#{ @mongoURI.getPassword() }</value>
            </list>
        </property>
    </bean>
</beans>

Sample code

To see a complete, working example, check out the sample code in github. The readme explains more about the example.

Logging into MongoHQ

You can log in through the Single Sign On feature of MongoHQ and Heroku in the following way:

1. Log into your Heroku account.
2. Once logged in, click on the app that has your MongoHQ add-on.
3. Once there, click on the dropdown labled “Add-ons” in the top-right of the screen.
4. Select MongoHQ.

Upgrading

We’re currently working on better integration with MongoHQ to allow seamless add-on upgrades. In the meantime, you’ll need to do the following:

1. Backup your database. You can use the instructions above to get a local mongodump
2. Remove the add-on (heroku addons:remove mongohq:basic)
3. Upgrade the add-on (heroku addons:add mongohq:small)
4. Restore your database using mongorestore

Known Issues

If you see the following error in your logs

Mongo::ConfigurationError (Trying to connect directly to slave; if this is what you want, specify :slave_ok => true.):

try updating your mongo gem to the latest. You can do this by specifying a newer version of mongo in your .gems manifest or Gemfile. 1.0.7 and later should work.