How Octopus Works

Octopus works using the Proxy Pattern . Basically, Octopus builds a proxy between ActiveRecord and Database Connection. The proxy object handles the way of executing queries, when send to multiple shards, or send to master when the database is replicated. Default behaviours are:

• Replication: Writes queries are sent to master, and reads queries are sent to slaves.
• Sharding: Writes/Reads queries are sent to master, unless you specified a shard to send the query.

Each ActiveRecord objects know their current shard, that is setted after the object is created using callbacks. Example:

 
ree-1.8.7-2010.02 > user = User.using(:slave1).create!(:name => "Thiago")
 => #<User id: 1, name: "Thiago", birthday: nil, created_at: "2010-07-15 17:35:10", updated_at: "2010-07-15 17:35:10"> 
ree-1.8.7-2010.02 > user.current_shard
 => :slave1 

Octopus also handles associations. When you try to get a object that is associated to another object, you could use normal ActiveRecord syntax to get the objects. Examples:

# This code will pick a client from the shard named brazil, and try to get all items associated with this client in that shard.
@brazil_client = Client.using(:brazil).find_by_name("Brazil Client")
@brazil_client.items