== Introduction

ActsAsPartitionable provides support for using multiple databases to support 
data partitioning schemes for existing models. 
This plugin allows models marked as acts_as_partitionable to specify database 
partitions to and explicit names to reference those partitions using existing 
models.  As part of this plugin connection pooling is provided so that many 
different models may share the same database for partitions without forcing each 
partition model object to inherit from a common base class.

== Disclaimer

As part of our strategy to address data partitioning as stated in our blog 
entry: 
http://revolutiononrails.blogspot.com/2007/04/ActsAsReadonlyable-to-support-
read-only.html

We wrote this plugin in preparation to using slave DBs but we are not going to 
have those until May 2007.  
So even though the code is covered with tests (see 
svn://rubyforge.org/var/svn/actsaspartition/trunk/test/unit/partitionable_test.r
b), it has not yet been used in a production environment.

We will have a discovery period in May when the code is likely to be improved so 
for now you can use is at your own risk. 
Meanwhile, we would be happy to fix any issue revealed. Drop us a line at rails-
trunk [ at ] revolution DOT com.

Using this plugin should not be your first step in application 
optimization/scaling or even the second one. 
Before installing it make sure you understand the implication of leveraging 
multiple DBs (for example, the potential for cross DB joins).

== Example

=== Sample Model

class SomeModel < ActiveRecord::Base
# use the read_only database from the database.yml
    acts_as_partitionable :name => "partition_1", :access => :readonly, 
:db_config => :read_only

# use the default database for partition_2
    acts_as_partitionable :name => "partition_2"

# use the a specific w/r database for partition_3
    acts_as_partitionable :name => "partition_3", :db_config => 
:some_model_partition

# Specify the database configuration from a hash
    acts_as_partitionable :access => :readonly, :db_config => {:adapter => 
"mysql", :database => "partionable_db_test", :username => "root", :password => 
"", :host => "localhost"} 
end

=== Sample DB Config

dbs:

  database: master_db
  host: master-host

read_only:
  database: slave_db
  host: slave-host


some_model_partition:
  database: slave_db_2
  host: slave-host

=== Usage

r = SomeModel.readonly.find(:first)  # executes against the read_only db - 
slave_db
r.field = 'value'
r.save!  # raises ActiveRecord::ReadOnlyRecord 
r.readonly? # true

t = SomeModel.partition_3.find(:first) # executes against slave_db_2
t.field = 'some value'
t.save! # success to partition_3


== Installation

As plugin: 
script/plugin install 
svn://rubyforge.org/var/svn/actsaspartition/trunk/vendor/plugins/acts_as_partiti
onable


== License

ActsAsPartitionable is released under the MIT license.


== Support

The plugin RubyForge page is http://rubyforge.org/projects/actsaspartition


