Gaurav Varma

Rails 6.1 introduces powerful upgrades to multi-database setups — including per-database role switching and horizontal sharding, giving you more precise control over where and how queries are executed.

Background

Rails already supported multiple databases with support for roles like writing and reading. But until now, switching between those roles applied globally — affecting all connections across all databases.

What’s New in Rails 6.1?

Role and shard switching can now be applied per connection class (instead of globally).
You can route queries independently across shards and replicas for each database.

To enable this, set the following config in application.rb:

1config.active_record.legacy_connection_handling = false

Example Setup

1production:
2  primary:
3    database: primary_database
4  primary_replica:
5    database: primary_database
6    replica: true
7  primary_shard_one:
8    database: primary_shard_one
9  primary_shard_one_replica:
10    database: primary_shard_one
11    replica: true
12
13  vehicles:
14    database: vehicles_database
15  vehicles_replica:
16    database: vehicles_database
17    replica: true
18  vehicles_shard_one:
19    database: vehicles_shard_one
20  vehicles_shard_one_replica:
21    database: vehicles_shard_one
22    replica: true

Model Structure

1# Primary DB base class
2class ApplicationRecord < ActiveRecord::Base
3  self.abstract_class = true
4
5  connects_to shards: {
6    default: { writing: :primary, reading: :primary_replica },
7    shard_one: { writing: :primary_shard_one, reading: :primary_shard_one_replica }
8  }
9end
10
11# Vehicles DB base class
12class VehiclesRecord < ApplicationRecord
13  self.abstract_class = true
14
15  connects_to shards: {
16    default: { writing: :vehicles, reading: :vehicles_replica },
17    shard_one: { writing: :vehicles_shard_one, reading: :vehicles_shard_one_replica }
18  }
19end
20
21class User < ApplicationRecord; end
22class Car < VehiclesRecord; end

Behavior: Before vs After

With legacy_connection_handling = true (old behavior):

1ApplicationRecord.connected_to(role: :reading, shard: :shard_one) do
2  User.first # hits shard_one
3  Car.first  # hits shard_one
4end

With legacy_connection_handling = false (new behavior):

1VehiclesRecord.connected_to(role: :reading, shard: :shard_one) do
2  User.first # still hits primary replica
3  Car.first  # hits vehicles_shard_one
4end

Each abstract class manages its own connection context!

When to Use

You have multiple databases with different sharding or replica strategies.
You want to avoid side effects of global connection switching.
You want queries to go to the correct database/shard even when deeply nested.

Summary

Rails 6.1 lets you switch roles and shards per database, making horizontal scaling and data isolation easier than ever. It’s a great addition for apps with growing data or high-performance needs.

For more details, check out the PR #40370.

Rails 6.1 enables per-database connection switching & sharding