ShardHandler

This gem is a simple sharding solution for Rails applications. It was created to be used in multitenant applications, where data is partitioned across a few databases but accessed through the same ActiveRecord model. Basically, this gem is a nice connection switcher for ActiveRecord.

Keep in mind that this gem is tested only with PostgreSQL databases.

The documentation is available on RubyDoc.info.

Add this line to your application's Gemfile:

gem 'shard_handler'

And then execute:

$ bundle

Or install it yourself as:

$ gem install shard_handler

First you must create an abstract model that will switch between shard connections:

class Shard < ShardHandler::Model
  self.abstract_class = true
end

Create a YAML file like this one:

# config/shards.yml
development:
  shard1: # shard name
    adapter: postgresql
    database: shard_db_1
    username: postgres
    # ...
  shard2:
    adapter: postgresql
    database: shard_db_2
    username: postgres
    # ...

And configure your Shard model:

# config/initializers/shard_handler.rb
Shard.setup(Rails.application.config_for(:shards))

Any model that has data shared across shards and requires a shard connection must inherit from your abstract model:

class Message < Shard
end

class Contact < Shard
end

To execute a query in a shard, you must wrap your code inside a block passed for .using, like this:

user = User.first

Shard.using(:shard1) do
  puts user.messages.pluck(:title)
  puts user.contacts.pluck(:email)
end

After checking out the repo:

1. Install dependencies using bin/setup.
2. Create these 2 files: spec/database.yml and spec/shards.yml and configure them with your PostgreSQL database. There are examples at spec/database.yml.example and spec/shards.yml.example. Important: these databases will be destroyed and recreated on test execution.
3. Run specs using bundle exec rake spec to make sure that everything is fine.

You can use bin/console to get an interactive prompt that will allow you to experiment.

If you are the maintainer of this project:

1. Update the version number in lib/shard_handler/version.rb.
2. Make sure that all tests are green (run bundle exec rake spec).
3. Execute bundle exec rake release to create a git tag for the version, push git commits and tags, and publish the gem on RubyGems.org.

To see what is going on in a PostgreSQL database, you can enable a more verbose log for the database:

# %d = database name
# %l = session line number
# %x = transaction ID (0 if none)
log_line_prefix = '%d %l %x - '
log_statement = 'all'

After restarting your database, the log will be like this:

my_db 1 0 - LOG:  statement: SELECT foo FROM bar

There are more options available, please take a look at PostgreSQL docs.

Bug reports and pull requests are welcome on GitHub at https://github.com/locaweb/shard_handler.

The gem is available as open source under the terms of the MIT License.