ActiveRecord Shards is an extension for ActiveRecord that provides support for sharded database and replicas. Basically it is just a nice way to switch between database connections. We've made the implementation very small, and have tried not to reinvent any wheels already present in ActiveRecord.
ActiveRecord Shards has been used and tested on Rails 5.x and 6.0, and has in some form or another been used in production on large Rails apps for several years.
Rails 6.1 introduced new connection handling and support for sharding. Apps are encouraged to migrate to the native sharding logic but ActiveRecord Shards supports Rails 6.1 when
legacy_connection_handling is set to
true. For more information see Rails 6.1 installation and Rails' multiple databases guide.
$ gem install active_record_shards
and make sure to require 'active_record_shards' in some way.
Rails 6.1 & 7.0 installation
Rails 6.1 & 7.0 are only supported with
legacy_connection_handling set to
Enable the legacy handling in your configuration files e.g.
config/application.rb by setting:
config.active_record.legacy_connection_handling = true
ActiveRecord::Base.legacy_connection_handling = true
Add the replica and shard configuration to config/database.yml:
basically connections inherit configuration from the parent configuration file.
ActiveRecord Shards also patches migrations to support running migrations on a shared (not sharded) or a sharded database. Each migration class has to specify a shard spec indicating where to run the migration.
Valid shard specs:
:none- Run this migration on the shared database, not any shards
:all- Run this migration on all of the shards, not the shared database
Create a table for the shared (not sharded) model
class CreateAccounts < ::Migration
create_table :accounts do |t|
# This is NOT necessary for the gem to work, we just use it in the examples below demonstrating one way to switch shards
t.integer :shard_id, null: false
Create a table for the sharded model
class CreateProjects < ::Migration
create_table :projects do |t|
Normally you have some models that live on a shared database, and you might need to query this data in order to know what shard to switch to. All the models that live on the shared database must be marked as not_sharded:
class Account < ::Base
class Project < ::Base
So in this setup the accounts live on the shared database, but the projects are sharded. If accounts have a shard_id column, you could lookup the account in a rack middleware and switch to the right shard:
@app = app
account = lookup_account(env)
You can switch to the replica databases at any point by wrapping your code in an on_replica block:
This will perform the query on the replica, and mark the returned instances as read-only. There is also a shortcut for this:
If you do not want instances returned from replicas to be marked as read-only, this can be disabled globally:
ActiveRecordShards.disable_replica_readonly_records = true
Show if a query went to primary or replica in the logs:
Copyright (c) 2011 Zendesk. See LICENSE for details.
Mick Staugaard, Eric Chapweske