ActiveRecord Shards is an extension for ActiveRecord that provides support for sharded database and slaves. Basically it is just a nice way to switch between database connection. We've made the implementation very small, and have tried not to reinvent any wheels already present in ActiveRecord.

ActiveRecord Shards has used and tested on Rails 2.3.x, 3.0.x, and 3.2.x and has in some form or another been used on in production on a large rails app for more than a year.

$ gem install active_record_shards

and make sure to require 'active_record_shards' in some way.

Add the slave and shard configuration to config/database.yml:

production:
  adapter: mysql
  encoding: utf8
  database: my_app_main
  pool: 5
  host: db1
  username: root
  password:
  slave:
    host: db1_slave
  shards:
    1:
      host: db_shard1
      database: my_app_shard
      slave:
        host: db_shard1_slave
    2:
      host: db_shard2
      database: my_app_shard
      slave:
        host: db_shard2_slave

basically connections inherit configuration from the parent the configuration file.

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 model that live on the shared database must be marked as not_sharded:

class Account < ActiveRecord::Base
  not_sharded
  
  has_many :projects
end

class Project < ActiveRecord::Base
  belongs_to :account
end

So in this setup the accounts live on the shared database, but the projects are sharded. If accounts had a shard_id column, you could lookup the account in a rack middleware and switch to the right shard:

class AccountMiddleware
  def initialize(app)
    @app = app
  end
  
  def call(env)
    account = lookup_account(env)
    
    if account
      ActiveRecord::Base.on_shard(account.shard_id) do
        @app.call(env)
      end
    else
      @app.call(env)
    end
  end
  
  def lookup_account(env)
    ...
  end
end

Any where in your app, you can switch to the slave databases, by wrapping you code an on_slave block:

ActiveRecord::Base.on_slave do
  Account.find_by_big_expensive_query
end

This will perform the query on the slave, and mark the returned instances as read only. There is also a shortcut for this:

Account.on_slave.find_by_big_expensive_query

Copyright (c) 2011 Zendesk. See LICENSE for details.

Mick Staugaard, Eric Chapweske