Rails 3 - Getting Started

It's not difficult to use MongoDB with Rails 3. Most of it comes down to making sure that you're not loading ActiveRecord and understanding how to use Bundler, the new Ruby dependency manager.

Install the Rails 3 Pre-release

If you haven't done so already, install the Rails 3 pre-release. This requires installing the dependencies manually and then installing the Rails 3 pre-release gem:

# Use sudo if your setup requires it
gem install tzinfo builder i18n memcache-client rack \
  rake rack-test rack-mount erubis mail text-format \
  thor bundler

gem install rails --prerelease

Configure your application

The important thing here is to avoid loading ActiveRecord. One way to do this is with the --skip-activerecord switch. So you'd create your app skeleton like so:

rails my_app --skip-activerecord

Alternatively, if you've already created your app (or just want to know what this actually does), have a look at config/application.rb and change the first lines from this:

require "rails/all"

to this:

require "action_controller/railtie"
require "action_mailer/railtie"
require "active_resource/railtie"
require "rails/test_unit/railtie"

It's also important to make sure that the reference to active_record in the generator block is commented out:

# Configure generators values. Many other options are available, be sure to check the documentation.
# config.generators do |g|
#   g.orm             :active_record
#   g.template_engine :erb
#   g.test_framework  :test_unit, :fixture => true
# end

As of this this writing, it's commented out by default, so you probably won't have to change anything here.

Bundle and Initialize

The final step involves bundling any gems you'll need and then creating an initializer for connecting to the database.

Bundling

Edit Gemfile, located in the Rails root directory. By default, our Gemfile will only load Rails:

gem "rails", "3.0.0.beta"

Normally, using MongoDB will simply mean adding whichever OM framework you want to work with, as these will require the "mongo" gem by default.

# Edit this Gemfile to bundle your application's dependencies.

source 'http://gemcutter.org'

gem "rails", "3.0.0.beta"
gem "mongo_mapper"

However, there's currently an issue with loading mongo_ext, as the current gemspec isn't compatible with the way Bundler works. We'll be fixing that soon; just pay attention to this issue.

In the meantime, you can use the following work-around:

# Edit this Gemfile to bundle your application's dependencies.

require 'rubygems'
require 'mongo'
source 'http://gemcutter.org'

gem "rails", "3.0.0.beta"
gem "mongo_mapper"

Requiring rubygems and mongo before running the gem command will ensure that mongo_ext is loaded. If you'd rather not load rubygems, just make sure that both mongo and mongo_ext are in your load path when you require mongo.

Once you've configured your Gemfile, run the bundle installer:

bundle install

Initializing

Last item is to create an initializer to connect to MongoDB. Create a Ruby file in config/initializers. You can give it any name you want; here we'll call it config/initializers/mongo.rb:

MongoMapper.connection = Mongo::Connection.new('localhost', 27017)
MongoMapper.database = "#myapp-#{Rails.env}"

if defined?(PhusionPassenger)
   PhusionPassenger.on_event(:starting_worker_process) do |forked|
     MongoMapper.connection.connect_to_master if forked
   end
end

Running Tests

A slight modification is required to get rake test working (thanks to John P. Wood). Create a file lib/tasks/mongo.rake containing the following:

namespace :db do
  namespace :test do
    task :prepare do
      # Stub out for MongoDB
    end
  end
end

Now the various rake test tasks will run properly. See John's post for more details.

ActiveModel Compatibility

ActiveModel is a series of interfaces designed to make any object-mapping library compatible with the various helper methods across the Rails stack. To see the status of ActiveModel integration on the various object mappers, see our object mappers page.

Briefly, Mongoid supports ActiveModel via a prerelease branch. MongoMapper will be adding support in the near future. In the meantime, use the MongoMapper Rails 3 Branch.

Conclusion

That should be all. You can now start creating models based on whichever OM you've installed.

Note that this document is a work in progress. If you have any helpful comments, please add them below.

See also

• Rails 3 App skeleton with MongoMapper
• Rails 3 Release Notes