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.

Installation

Add this line to your application's Gemfile:

gem 'shard_handler'

And then execute:

$ bundle

Or install it yourself as:

$ gem install shard_handler

Usage

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

Development

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.

Releasing a new version

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.

Debugging PostgreSQL

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.

Contributing

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

License

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