File: README — Documentation for ar-octopus (0.0.28)

# Octopus - Easy Database Sharding for ActiveRecord

Octopus is a better way to do Database Sharding in ActiveRecord. Sharding allows multiple databases in the same rails application. While there are several projects that implement Sharding (e.g. DbCharmer, DataFabric, MultiDb), each project has its own limitations. The main goal of octopus project is to provide a nice and clean way of doing Database Sharding.

## Feature list: The design of the api is made to be simple as possible. Octopus is focusing in the end user, giving the power of multiple databases, but with reliable code and flexibility. Octopus is focused on Rails 3, but is compatible with Rails 2.x.

Octopus supports:

Sharding (with multiple shards, and grouped shards).
Replication (Master/slave support, with multiple slaves).
Moving data between shards with migrations.
Tools to manage database configurations. (soon)

### Replication When using replication, all writes queries will be sent to master, and read queries to slaves. More info could be found at: <a href=“wiki.github.com/tchandy/octopus/replication”> Wiki</a>

### Sharding

When using sharding, you need to specify what shard the query will be sent. Octopus support selecting the shard inside a controller, or manually in each object. More could be found at <a href="http://wiki.github.com/tchandy/octopus/sharding"> Wiki</a>

## Install

### Rails 2.x

Install the octopus gem: <pre> sudo gem install ar-octopus </pre>

Add this line to enviroment.rb: <pre>config.gem ‘ar-octopus’, :lib => “octopus”</pre>

### Rails 3.x

Add this line to Gemfile: <pre>gem ‘ar-octopus’, :require => “octopus”</pre>

Runs a bundle install: <pre>bundle install</pre>

## How to use Octopus?

First, you need to create a config file, shards.yml, inside your config/ directory. to see the syntax and how this file should look, please checkout <a href=“wiki.github.com/tchandy/octopus/config-file”>this page on wiki</a>.

### Syntax

Octopus adds a method to each AR Class and object. the using method is used to select the shard, like this: <pre>User.where(:name => “Thiago”).limit(3).using(:slave_one) </pre>

Octopus also supports queries inside block. When you pass a block to the using method, all queries inside the block will be sent to the specified shard.

<pre> Octopus.using(:slave_two) do

User.create(:name => "Mike")

end </pre>

Each object knows where is your shard, so you could to thinks like this:

<pre> # This will find the user in the shard1 @user = User.using(:shard1).find_by_name(“Joao”)

# This will find the user in the master database @user2 = User.find_by_name(“Jose”)

#Sets the name @user.name = “Mike”

# Save the user in the correct shard, shard1. @user.save() </pre>

### Migrations

In migrations, you also have access to the using method. The syntax is basically the same. This migration will run in brazil and canada shards.

<pre>

class CreateUsersOnBothShards < ActiveRecord::Migration
  using(:brazil, :canada)

  def self.up
    User.create!(:name => "Both")
  end

  def self.down
    User.delete_all()
  end
end

</pre>

You also could send a migration to a group of shards.  This migration will be sent to all shards that belongs to history_shards group, specified in shards.yml:

<pre>

class CreateUsersOnMultiplesGroups < ActiveRecord::Migration
  using_group(:history_shards)

  def self.up
    User.create!(:name => "MultipleGroup")
  end

  def self.down
    User.delete_all()
  end
end

</pre>

### Rails Controllers

If you want to send a specified action, or all actions from a controller, to a specific shard, use this syntax: <pre>

class ApplicationController < ActionController::Base
  around_filter :select_shard      

  def select_shard
    Octopus.using(:brazil) do
      yield
    end
  end    
end

</pre>

To see the complete list of features and syntax, please check out our <a href="http://wiki.github.com/tchandy/octopus/"> Wiki</a>

Wanna see sample rails applications using octopus features? please check it out: <a href=“github.com/tchandy/octopus_sharding_example”>Sharding Example</a> and <a href=“github.com/tchandy/octopus_replication_example”>Replication Example</a>

## Thanks

This project is sponsored by the <a href=“www.rubysoc.org”>Ruby Summer of Code</a>, and my mentors <a href=“github.com/mperham”>Mike Perham</a> and <a href=“github.com/amitagarwal”>Amit Agarwal</a>.