🔥 Multiple databases for Rails
ActiveRecord supports multiple databases, but Rails < 6 doesn’t provide a way to manage them. Multiverse changes this.
Plus, it’s easy to upgrade to Rails 6 when you get there.
Works with Rails 4.2+
Add this line to your application’s Gemfile:
gem 'multiverse'
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
Rollback
DB=catalog rails db:rollback
Also works for models
DB=catalog rails generate model Product
This generates
class Product < CatalogRecord
end
Only necessary in Rails < 5.2
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
CatalogRecord.connection.disconnect!
And inside the after_fork
block
CatalogRecord.establish_connection :"catalog_#{Rails.env}"
Rails fixtures work automatically.
Note: Referential integrity is not disabled on additional databases when fixtures are loaded, so you may run into issues if you use foreign keys.
After running migrations for additional databases, run:
DB=catalog rails db:test:prepare
Database Cleaner supports multiple connections out of the box.
cleaner = DatabaseCleaner[:active_record, {model: CatalogRecord}]
cleaner.strategy = :transaction
cleaner.cleaning do
# code
end
There are a few features that aren’t supported on additional databases.
- Pending migration check
schema_cache.yml
Also note that ActiveRecord::Migration.maintain_test_schema!
doesn’t affect additional databases.
Rails 6 provides a way to manage multiple databases 🎉
To upgrade from Multiverse, nest your database configuration in config/database.yml
:
# this should be similar to default, but with migrations_paths
catalog_default: &catalog_default
adapter: ...
pool: <%= ENV.fetch("RAILS_MAX_THREADS") { 5 } %>
migrations_paths: db/catalog_migrate
development:
primary:
<<: *default
database: ...
catalog:
<<: *catalog_default
database: ...
test:
primary:
<<: *default
database: ...
catalog:
<<: *catalog_default
database: ...
production:
primary:
<<: *default
database: ...
catalog:
<<: *catalog_default
database: ...
Then change establish_connection
in app/models/catalog_record.rb
to:
class CatalogRecord < ActiveRecord::Base
establish_connection :catalog
end
And move:
db/catalog/migrate
todb/catalog_migrate
db/catalog/schema.rb
todb/catalog_schema.rb
(ordb/catalog/structure.sql
todb/catalog_structure.sql
).
Then remove multiverse
from your Gemfile. 🎉
Now you can use the updated commands:
rails db:migrate # run all
rails db:migrate:catalog # runs catalog only
Generate migrations with:
rails generate migration add_name_to_products --database=catalog
And models with:
rails generate model Product --database=catalog --parent=CatalogRecord
Happy scaling!
View the changelog
Everyone is encouraged to help improve this project. Here are a few ways you can help:
- Report bugs
- Fix bugs and submit pull requests
- Write, clarify, or fix documentation
- Suggest or add new features