Multiple databases for Rails 🎉
Clone or download


🔥 Multiple databases for Rails

One of the easiest ways to scale your database is to move large, infrequently-joined tables to a separate database. ActiveRecord supports multiple databases, but Rails doesn’t provide a way to manage them. Multiverse changes this.

Works with Rails 4.2+

Build Status


Add this line to your application’s Gemfile:

gem 'multiverse'

Getting Started

In this example, we’ll have a separate database for our e-commerce catalog that we’ll call catalog.

The first step is to generate the necessary files.

rails generate multiverse:db catalog

This creates a CatalogRecord class for models to inherit from and adds configuration to config/database.yml. It also creates a db/catalog directory for migrations and schema.rb to live.

rails and rake commands run for the original database by default. To run commands for the new database, use the DB environment variable. For instance:

Create the database

DB=catalog rails db:create

Create a migration

DB=catalog rails generate migration add_name_to_products

Run migrations

DB=catalog rails db:migrate


DB=catalog rails db:rollback


Also works for models

DB=catalog rails generate model Product

This generates

class Product < CatalogRecord

Web Servers

For web servers that fork, be sure to reconnect after forking (just like you do with ActiveRecord::Base)


In config/puma.rb, add inside the on_worker_boot block

CatalogRecord.establish_connection :"catalog_#{Rails.env}"


In config/unicorn.rb, add inside the before_fork block


And inside the after_fork block

CatalogRecord.establish_connection :"catalog_#{Rails.env}"



Rails fixtures work automatically.

Database Cleaner

Database Cleaner supports multiple connections out of the box.

cleaner = DatabaseCleaner[:active_record, {model: CatalogRecord}]
cleaner.strategy = :transaction do
  # code

Read more here


View the changelog


Everyone is encouraged to help improve this project. Here are a few ways you can help: