yam-db-charmer 1.7.01

data/.gitignore

@@ -0,0 +1,4 @@
+/doc
+/pkg
+.DS_Store
+/_site

data/CHANGES

@@ -0,0 +1,184 @@
+1.7.0 (2011-08-29):
+
+Beta feature: Rails 3 support
+
+Beta feature: Added force_slave_reads functionality. Now we could have models with slaves
+that are not used by default, but could be turned on globally (per-controller or per-action).
+
+Heavily reorganized the source code to match Rails code structure (class names, etc). This should
+make it much easier for other contributors to work with the code.
+Added smarter environment detection (using Rails.env, RAILS_ENV or RACK_ENV).
+
+Changed dependencies a bit: instead of depending on rails, we now require specific components
+(ActiveRecord, ActiveSupport, etc) + we do not require blankslate gem anymore.
+
+Bugfixes: Fix for N+1 queries when accessing shard_info for db_block_group_map sharding method.
+
+----------------------------------------------------------------------------------------
+1.6.17-19 (2011-04-25):
+
+Bugfixes: Do not touch database for sharded models until we really need to. Before 1.6.17
+if a database server was dead and there were any other connection issues, class loading
+in Ruby would be broken and sharded model class would not be initialized.
+
+----------------------------------------------------------------------------------------
+1.6.14 (2011-01-09):
+
+Bugfixes: We do not support Rails 3, and now we prohibit any versions but 2.2 and 2.3 from
+being used with db-charmer gem.
+
+----------------------------------------------------------------------------------------
+1.6.13 (2010-08-17):
+
+Starting with this version we use Rails.env instead of RAILS_ENV to auto-detect rails
+environment. If you use DbCharmer in non-rails project, please set DbCharmer.env manually.
+
+Bugfixes: Thanks to Eric Lindvall we now allow connection names that have symbols ruby
+wouldn't like for class names.
+
+----------------------------------------------------------------------------------------
+1.6.12 (2010-05-09):
+
+Starting with this version we use Rails.cache (memcache or whatever you use in your project)
+to cache sharding blocks information.
+
+Bugfixes: Thanks to Allen Madsen (github user blatyo) we've fixed a few minor issues in
+database connections handling.
+
+----------------------------------------------------------------------------------------
+1.6.11 (2010-04-16):
+
+Bugfix: Change the way we allocate sharding blocks in block map sharding method to
+prevent race-conditions from happening on block to shard assignments.
+Breaking change: We require connections to exist by default in all connection factory
+methods. If you need old behavior, pass should_exist=false explicitly.
+
+----------------------------------------------------------------------------------------
+1.6.10 (2010-04-09):
+
+Multi-Db migrations changed. Now it is possible to call ActiveRecord::Migration.db_magic
+and specify default migration connection that would be used by all migrations without
+excplicitly switched connections.
+
+----------------------------------------------------------------------------------------
+1.6.9 (2010-04-08):
+
+Bugfix release: now DbCharmer works without Rails.
+
+----------------------------------------------------------------------------------------
+1.6.7 (2010-04-07):
+
+Changed the way we handle associations in on_db(:foo).find(:include) calls. Now we
+switch association's connection only if its default connection is the same as the
+master model's connection (not more "table does not exist" problems I hope).
+
+----------------------------------------------------------------------------------------
+1.6.5 (2010-04-05):
+
+Bugfix release: Fixed :connection vs :slave in db_magic behaviour. Model.on_master should
+run queries on the master, not on AR's default connection.
+
+----------------------------------------------------------------------------------------
+1.6.4 (2010-04-05):
+
+Default behaviour changed: DbCharmer.connections_should_exist is true in all environments
+by default. Old default behaviour was too misleading for many developers.
+
+----------------------------------------------------------------------------------------
+1.6.3 (2010-04-03):
+
+Bugfix release: Modified stub connection initialization code to set default connections
+for sharded models using shards enumeration or default shard features of sharding methods.
+
+----------------------------------------------------------------------------------------
+1.6.2 (2010-04-03):
+
+Bugfix release: Modified our stub connection used on sharded models to fail on db-calling
+methods only. Proxy the rest to a real shard connection. Another bug fixed in db_block_map
+sharding method: we didn't increment block counters when assigning blocks to shards.
+
+----------------------------------------------------------------------------------------
+1.6.1 (2010-03-31):
+
+Breaking change from now on all connection-switching methods (both in migrations and in
+models) are controlled by a single option DbCharmer.connections_should_exist. This
+option is false by default in all non-production environments. Check out README for
+more details.
+
+----------------------------------------------------------------------------------------
+1.6.0 (2010-03-31):
+
+The major (and arguably the only noticeable) change in this version is our simple database
+sharding support. The feature is still in alpha stage and should not be used in production
+without complete understanding of the principles of its work.
+
+----------------------------------------------------------------------------------------
+1.5.5 (2010-03-15):
+
+Thanks to ngmoco.com (http://github.com/ngmoco) now DbCharmer supports one more use-case
+for multi-db migrations. Now you can run the same migration on many databases at once.
+For example, the following migration would create test_table on all three shard databases:
+
+    class MultiDbTest < ActiveRecord::Migration
+      db_magic :connections => [ :shard01, :shard02, :shard03 ]
+
+      def self.up
+        create_table :test_table do |t|
+          t.string :test_string
+          t.timestamps
+        end
+      end
+
+      def self.down
+        drop_table :test_table
+      end
+    end
+
+----------------------------------------------------------------------------------------
+1.5.4 (2010-03-12):
+
+Added DbCharmer.with_remapped_databases, so that you can change the connection for
+many models simultaneously, and implicitly. Very useful for work where you want to use
+a particular slave for a whole range of database access.
+
+----------------------------------------------------------------------------------------
+1.5.3 (2010-03-10):
+
+Few changes:
+ * Colorized connection names in the logs for development mode
+ * We do not log connection names when connection does not exist
+
+----------------------------------------------------------------------------------------
+1.5.1 (2010-03-06):
+
+In this version we've added support for connection names logging in Rails queries log.
+New log records have [connection_name] prefix for all queries that are executed on
+non-standard connections:
+
+[logs]   LogRecord Columns (1.1ms)   SHOW FIELDS FROM `log_records`
+[logs]   User Delete all (0.1ms)   DELETE FROM `users`
+[slave01]   User Load (0.2ms)   SELECT * FROM `users` WHERE (`users`.`login` = 'foo')
+
+----------------------------------------------------------------------------------------
+1.4.6 -> 1.5.0 (2010-03-05):
+
+Major change in this version of DbCharmer is association preload support. For example,
+let's say we have a schema:
+
+    class Post < ActiveRecord::Base
+      belongs_to :user
+    end
+
+    class User < ActiveRecord::Base
+      has_many :posts
+    end
+
+Now, if we have the following call in our code:
+
+    User.on_db(:foo).all(:include => :posts)
+
+In 1.4.6 it would load the users from connection :foo and posts from the
+default connection, which is not what we would expect from this line of code.
+So, starting 1.5.0 all finder calls on models having :include parameter would
+switch associated models' connections to the same connection as the main model
+in the call.

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2011, Oleksiy Kovyrin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/Makefile

@@ -0,0 +1,2 @@
+doc/files/README_rdoc.html:	README.rdoc
+	rdoc README.rdoc

data/README.rdoc

@@ -0,0 +1,612 @@
+= DB Charmer - ActiveRecord Connection Magic Plugin
+
++DbCharmer+ is a simple yet powerful plugin for ActiveRecord that significantly extends its ability to work with
+multiple databases and/or database servers. The major features we add to ActiveRecord are:
+
+1. Simple management for AR model connections (+switch_connection_to+ method)
+2. Switching of default AR model connections to separate servers/databases
+3. Ability to easily choose where your query should go (<tt>Model.on_*</tt> methods family)
+4. Automated master/slave queries routing (selects go to a slave, updates handled by the master).
+5. Multiple database migrations with very flexible query routing controls.
+6. Simple database sharding functionality with multiple sharding methods (value, range, mapping table).
+
+For more information on the project, you can check out our web site at http://kovyrin.github.com/db-charmer.
+
+
+== Installation
+
+There are two options when approaching +DbCharmer+ installation:
+* using the gem (recommended and the only way of using it with Rails 3.0+)
+* install as a Rails plugin (works in Rails 2.x only)
+
+To install as a gem, add this to your Gemfile:
+
+  gem 'db-charmer', :require => 'db_charmer'
+
+To install +DbCharmer+ as a Rails plugin use the following command:
+
+  ./script/plugin install git://github.com/kovyrin/db-charmer.git
+
+_Notice_: If you use +DbCharmer+ in a non-rails project, you may need to set <tt>DbCharmer.env</tt> to a correct value
+before using any of its connection management methods. Correct value here is a valid <tt>database.yml</tt>
+first-level section name.
+
+
+== Easy ActiveRecord Connection Management
+
+As a part of this plugin we've added +switch_connection_to+ method that accepts many different kinds
+of db connections specifications and uses them on a model. We support:
+
+1. Strings and symbols as the names of connection configuration blocks in database.yml.
+2. ActiveRecord models (we'd use connection currently set up on a model).
+3. Database connections (<tt>Model.connection</tt>)
+4. Nil values to reset model to default connection.
+
+Sample code:
+
+  class Foo < ActiveRecord::Model; end
+
+  Foo.switch_connection_to(:blah)
+  Foo.switch_connection_to('foo')
+  Foo.switch_connection_to(Bar)
+  Foo.switch_connection_to(Baz.connection)
+  Foo.switch_connection_to(nil)
+
+Sample <tt>database.yml</tt> configuration:
+
+  production:
+    blah:
+      adapter: mysql
+      username: blah
+      host: blah.local
+      database: blah
+
+    foo:
+      adapter: mysql
+      username: foo
+      host: foo.local
+      database: foo
+
+The +switch_connection_to+ method has an optional second parameter +should_exist+ which is true
+by default. This parameter is used when the method is called with a string or a symbol connection
+name and there is no such connection configuration in the database.yml file. If this parameter
+is +true+, an exception would be raised, otherwise, the error would be ignored and no connection
+change would happen.
+
+This is really useful when in development mode or in a tests you do not want to create many different
+databases on your local machine and just want to put all your tables in a single database.
+
+*Warning*: All the connection switching calls would switch connection *only* for those classes the
+method called on. You can't call the +switch_connection_to+ method and switch connection for a
+base class in some hierarchy (for example, you can't switch AR::Base connection and see all your
+models switched to the new connection, use the classic +establish_connection+ instead).
+
+
+== Multiple DB Migrations
+
+In every application that works with many databases, there is need in a convenient schema migrations mechanism.
+
+All Rails users already have this mechanism - rails migrations. So in +DbCharmer+, we've made it possible
+to seamlessly use multiple databases in Rails migrations.
+
+There are two methods available in migrations to operate on more than one database:
+
+1. Global connection change method - used to switch whole migration to a non-default database.
+2. Block-level connection change method - could be used to do only a part of a migration on a non-default db.
+
+Migration class example (global connection rewrite):
+
+  class MultiDbTest < ActiveRecord::Migration
+     db_magic :connection => :second_db
+
+     def self.up
+       create_table :test_table, :force => true do |t|
+         t.string :test_string
+         t.timestamps
+       end
+     end
+
+     def self.down
+       drop_table :test_table
+     end
+   end
+
+Migration class example (block-level connection rewrite):
+
+  class MultiDbTest < ActiveRecord::Migration
+    def self.up
+      on_db :second_db do
+        create_table :test_table, :force => true do |t|
+          t.string :test_string
+          t.timestamps
+        end
+      end
+    end
+
+    def self.down
+      on_db :second_db { drop_table :test_table }
+    end
+  end
+
+Migration class example (global connection rewrite, multiple connections with the same table):
+(NOTE: both :connection and :connections can take an array of connections)
+
+  class MultiDbTest < ActiveRecord::Migration
+    db_magic :connections => [:second_db, :default]
+
+    def self.up
+      create_table :test_table, :force => true do |t|
+        t.string :test_string
+        t.timestamps
+      end
+    end
+
+    def self.down
+      drop_table :test_table
+    end
+  end
+
+=== Default Migrations Connection
+
+Starting with DbCharmer version 1.6.10 it is possible to call <tt>ActiveRecord::Migration.db_magic</tt>
+and specify default migration connection that would be used by all migrations without
+excplicitly switched connections. If you want to switch your migration to the default ActiveRecord
+connection, just use <tt>db_magic :connection => :default</tt>.
+
+=== Invalid Connection Names Handling
+
+By default in all environments <tt>on_db</tt> and <tt>db_magic</tt> statments would fail if
+specified connection does not exist in database.yml. It is possible to make +DbCharmer+
+ignore such situations in non-production environments so that rails would create the tables
+in your single database (especially useful in test databases).
+
+This behaviour is controlled by the <tt>DbCharmer.connections_should_exist</tt>
+configuration attribute which could be set from a rails initializer.
+
+Warning: if in test environment you use separate connections and master-slave support
+in DbCharmer, make sure you disable transactional fixtures support in Rails. Without
+this change you're going to see all kinds of weird data visibility problems in your tests.
+
+
+== Using Models in Master-Slave Environments
+
+Master-slave replication is the most popular scale-out technique in a medium-sized and
+large database-centric applications today. There are some rails plugins out there that help
+developers to use slave servers in their models but none of them were flexible enough
+for us to start using them in a huge application we work on.
+
+So, we've been using ActsAsReadonlyable plugin for a long time and have made tons
+of changes in its code over the time. But since that plugin has been abandoned
+by its authors, we've decided to collect all of our master-slave code in one plugin
+and release it for rails 2.2+. +DbCharmer+ adds the following features to Rails models:
+
+
+=== Auto-Switching all Reads to the Slave(s)
+
+When you create a model, you could use <tt>db_magic :slave => :blah</tt> or
+<tt>db_magic :slaves => [ :foo, :bar ]</tt> commands in your model to set up reads
+redirection mode when all your find/count/exist/etc methods will be reading data
+from your slave (or a bunch of slaves in a round-robin manner). Here is an example:
+
+  class Foo < ActiveRecord::Base
+    db_magic :slave => :slave01
+  end
+
+  class Bar < ActiveRecord::Base
+    db_magic :slaves => [ :slave01, :slave02 ]
+  end
+
+
+=== Default Connection Switching
+
+If you have more than one master-slave cluster (or simply more than one database)
+in your database environment, then you might want to change the default database
+connection of some of your models. You could do that by using
+<tt>db_magic :connection => :foo</tt> call from your models. Example:
+
+  class Foo < ActiveRecord::Base
+    db_magic :connection => :foo
+  end
+
+Sample model on a separate master-slave cluster (so, separate main connection +
+a slave connection):
+
+  class Bar < ActiveRecord::Base
+    db_magic :connection => :bar, :slave => :bar_slave
+  end
+
+=== Per-Query Connection Management
+
+Sometimes you have select queries that you know you want to run on the master.
+This could happen for example when you have just added some data and need to read
+it back and not sure if it made it all the way to the slave yet or no. For this
+situation and a few others there is a set of methods we've added to ActiveRecord models:
+
+1) +on_master+ - this method could be used in two forms: block form and proxy form.
+In the block form you could force connection switch for a block of code:
+
+  User.on_master do
+    user = User.find_by_login('foo')
+    user.update_attributes!(:activated => true)
+  end
+
+In the proxy form this method could be used to force one query to be performed on
+the master database server:
+
+  Comment.on_master.last(:limit => 5)
+  User.on_master.find_by_activation_code(code)
+  User.on_master.exists?(:login => login, :password => password)
+
+2) +on_slave+ - this method is used to force a query to be run on a slave even in
+situations when it's been previously forced to use the master. If there is more
+than one slave, one would be selected randomly. Tis method has two forms as
+well: block and proxy.
+
+3) <tt>on_db(connection)</tt> - this method is what makes two previous methods
+possible. It is used to switch a model's connection to some db for a short block
+of code or even for one statement (two forms). It accepts the same range of values
+as the +switch_connection_to+ method does. Example:
+
+  Comment.on_db(:olap).count
+  Post.on_db(:foo).find(:first)
+
+By default in development and test environments you could use non-existing connections in your
+<tt>on_db</tt> calls and rails would send all your queries to a single default database. In
+production <tt>on_db</tt> won't accept non-existing names.
+
+This behaviour is controlled by the <tt>DbCharmer.connections_should_exist</tt>
+configuration attribute which could be set from a rails initializer.
+
+
+=== Forced Slave Reads
+
+In some cases we could have models that are too important to be used in default "send all
+reads to the slave" mode, but we still would like to be able to switch them to this mode
+sometimes. For example, you could have +User+ model, which you would like to keep from
+lagging with your slaves because users do not like to see outdated information about their
+accounts. But in some cases (like logged-out profile page views, etc) it would be perfectly
+reasonable to switch all reads to the slave.
+
+For this use-case starting with +DbCharmer+ release 1.7.0 we have a feature called forced
+slave reads. It consists of a few separate small features that together make it really
+powerful:
+
+1) <tt>:force_slave_reads => false</tt> option for +ActiveRecord+'s <tt>db_magic</tt> method.
+This option could be used to disable automated slave reads on your models so that you could
+call <tt>on_slave</tt> or use other methods to enable slave reads when you need it. Example:
+
+  class User < ActiveRecord::Base
+    db_magic :slave => slave01, :forced_slave_reads => false
+  end
+
+2) <tt>force_slave_reads</tt> +ActionController+ class method. This method could be used to
+enable per-controller (when called with no arguments), or per-action (<tt>:only</tt> and
+<tt>:except</tt> params) forced reads from slaves. This is really useful for actions in
+which you know you could tolerate some slave lag so all your models with slaves defined will
+send their reads to slaves. Example:
+
+  class ProfilesController < Application
+    force_slave_reads :except => [ :login, :logout ]
+    ...
+  end
+
+3) <tt>force_slave_reads!</tt> +ActionController+ instance method, that could be used within
+your actions or in controller filters to temporarily switch your models to forced slave reads
+mode. This method could be useful for cases when the same actions could be called by logged-in
+and anonymous users. Then you could authorize users in <tt>before_filter</tt> and call
+<tt>force_slave_reads!</tt> method for anonymous page views.
+
+  class ProfilesController < Application
+    before_filter do
+      force_slave_reads! unless current_user
+    end
+    ...
+  end
+
+Notice: Before using this method you need to enable +ActionController+ support in +DbCharmer+.
+You need to call <tt>DbCharmer.enable_controller_magic!</tt> method from your project
+initialization code.
+
+4) <tt>DbCharmer.force_slave_reads</tt> method that could be used with a block of ruby code
+and would enable forced slave reads mode until the end of the block execution. This is really
+powerful feature allowing high granularity in your control of forced slave reads mode. Example:
+
+  DbCharmer.force_slave_reads do
+    ...
+    total_users = User.count
+    ...
+  end
+
+Notice: At this point the feature considered beta and should be used with caution. It is fully covered
+with tests, but there still could be unexpected issues when used in real-world applications.
+
+
+=== Associations Connection Management
+
+ActiveRecord models can have an associations with each other and since every model has its
+own database connections, it becomes pretty hard to manage connections in a chained calls
+like <tt>User.posts.count</tt>. With a class-only connection switching methods this call
+would look like the following if we'd want to count posts on a separate database:
+
+  Post.on_db(:olap) { User.posts.count }
+
+Apparently this is not the best way to write the code and we've implemented an <tt>on_*</tt>
+methods on associations as well so you could do things like this:
+
+  @user.posts.on_db(:olap).count
+  @user.posts.on_slave.find(:title => 'Hello, world!')
+
+Notice: Since ActiveRecord associations implemented as proxies for resulting
+objects/collections, it is possible to use our connection switching methods even without
+chained methods:
+
+  @post.user.on_slave - would return post's author
+  @photo.owner.on_slave - would return photo's owner
+
+
+Starting with +DbCharmer+ release 1.4 it is possible to use prefix notation for has_many
+and HABTM associations connection switching:
+
+  @user.on_db(:foo).posts
+  @user.on_slave.posts
+
+
+=== Named Scopes Support
+
+To make it easier for +DbCharmer+ users to use connections switching methods with named scopes,
+we've added <tt>on_*</tt> methods support on the scopes as well. All the following scope chains
+would do exactly the same way (the query would be executed on the :foo database connection):
+
+  Post.on_db(:foo).published.with_comments.spam_marked.count
+  Post.published.on_db(:foo).with_comments.spam_marked.count
+  Post.published.with_comments.on_db(:foo).spam_marked.count
+  Post.published.with_comments.spam_marked.on_db(:foo).count
+
+And now, add this feature to our associations support and here is what we could do:
+
+  @user.on_db(:archive).posts.published.all
+  @user.posts.on_db(:olap).published.count
+  @user.posts.published.on_db(:foo).first
+
+
+=== Bulk Connection Management
+
+Sometimes you want to run code where a large number of tables may be used, and you'd like
+them all to use an alternate database. You can now do this:
+
+  DbCharmer.with_remapped_databases(:logs => :big_logs_slave) { ... }
+
+Any model whose default database is +:logs+ (e.g., <tt>db_charmer :connection => :logs</tt>)
+will now have its connection switched to +:big_logs_slave+ in that block. This is lower
+precedence than any other +DbCharmer+ method, so <tt>Model.on_db(:foo).find(...)</tt> and
+such things will still use the database they specify, not the one that model was remapped
+to.
+
+You can specify any number of remappings at once, and you can also use +:master+ as a database
+name that matches any model that has not had its connection set by +DbCharmer+ at all.
+
+*Note*: +DbCharmer+ works via +alias_method_chain+ in model classes. It is very careful
+to only patch the models it needs to. However, if you use +with_remapped_databases+ and
+remap the default database (+:master+), then it has no choice but to patch all subclasses
+of +ActiveRecord::Base+. This should not cause any serious problems or any big performance
+impact, but it is worth noting.
+
+
+== Simple Sharding Support
+
+Starting with the release 1.6.0 of +DbCharmer+ we have added support for simple database sharding
+to our ActiveRecord extensions. Even though this feature is tested in production, we do not recommend
+using it in your applications without complete understanding of the principles of its work.
+
+At this point we support four sharding methods:
+
+1) +range+ - really simple sharding method that allows you to take a table, slice is to a set of
+smaller tables with pre-defined ranges of primary keys and then put those smaller tables to
+different databases/servers. This could be useful for situations where you have a huge table that
+is slowly growing and you just want to keep it simple and split the table load into a few servers
+without building any complex sharding schemes.
+
+2) +hash_map+ - pretty simple sharding method that allows you to take a table and slice it to a set
+of smaller tables by some key that has a pre-defined key of values. For example, list of US mailing
+addresses could be sharded by states, where you'd be able to define which states are stored in which
+databases/servers.
+
+3) +db_block_map+ - this is a really complex sharding method that allows you to shard your table into a
+set of small fixed-size blocks that then would be assigned to a set of shards (databases/servers).
+Whenever you would need an additional blocks they would be allocated automatically and then balanced
+across the shards you have defined in your database. This method could be used to scale out huge
+tables with hundreds of millions to billions of rows and allows relatively easy re-sharding techniques
+to be implemented on top.
+
+4) +db_block_group_map+ - really similar to the +db_block_map+ method with a single difference: this method
+allows you to have a set of databases (table groups) on each server and every group would be handled as a
+separate shard of data. This approach is really useful for pre-sharding of your data before scaling your
+application out. You can easily start with one server, having 10-20-50 separate databases, and then
+move those databases to different servers as you see your database outgrow one machine.
+
+
+=== How to enable sharding?
+
+To enable sharding extensions you need to take a few things:
+
+1) Create a Rails initializer (on run this code when you initialize your script/application) with a
+set of sharded connections defined. Each connection would have a name, sharding method and an optional
+set of parameters to initialize the sharding method of your choice.
+
+2) Specify sharding connection you want to use in your models.
+
+3) Specify the shard you want to use before doing any operations on your models.
+
+For more details please check out the following documentation sections.
+
+
+=== Sharded Connections
+
+Sharded connection is a simple abstractions that allows you to specify all sharding parameters for a
+cluster in one place and then use this centralized configuration in your models. Here are a few examples
+of sharded connections initizlization calls:
+
+1) Sample range-based sharded connection:
+
+  TEXTS_SHARDING_RANGES = {
+    0...100   => :shard1,
+    100..200  => :shard2,
+    :default  => :shard3
+  }
+
+  DbCharmer::Sharding.register_connection(
+    :name => :texts,
+    :method => :range,
+    :ranges => TEXTS_SHARDING_RANGES
+  )
+
+2) Sample hash map sharded connection:
+
+  SHARDING_MAP = {
+    'US'  => :us_users,
+    'CA'  => :ca_users,
+    :default  => :other_users
+  }
+
+  DbCharmer::Sharding.register_connection(
+    :name => :users,
+    :method => :hash_map,
+    :map => SHARDING_MAP
+  )
+
+3) Sample database block map sharded connection:
+
+  DbCharmer::Sharding.register_connection(
+    :name => :social,
+    :method => :db_block_map,
+    :block_size => 10000,                   # Number of keys per block
+    :map_table => :event_shards_map,        # Table with blocks to shards mapping
+    :shards_table => :event_shards_info,    # Shards connection information table
+    :connection => :social_shard_info       # What connection to use to read the map
+  )
+
+After your sharded connection is defined, you could use it in your models:
+
+  class Text < ActiveRecord::Base
+    db_magic :sharded => {
+      :key => :id,
+      :sharded_connection => :texts
+    }
+  end
+
+  class Event < ActiveRecord::Base
+    set_table_name :timeline_events
+
+    db_magic :sharded => {
+      :key => :to_uid,
+      :sharded_connection => :social
+    }
+  end
+
+
+=== Switching connections in sharded models
+
+Every time you need to perform an operation on a sharded model, you need to specify on which shard
+you want to do it. We have a method for this which would look familiar for the people that use
++DbCharmer+ for non-sharded environments since it looks and works just like those per-query
+connection management methods:
+
+  Event.shard_for(10).find(:conditions => { :to_uid => 123 }, :limit => 5)
+  Text.shard_for(123).find_by_id(123)
+
+There is another method that could be used with range and hash_map sharding methods, this method
+allows you to switch to the default shard:
+
+  Text.on_default_shard.create(:body => 'hello', :user_id => 123)
+
+And finally, there is a method that allows you to run your code on each shard in the system (at this
+point the method is supported in db_block_map and db_block_group_map methods only):
+
+  Event.on_each_shard { |event| event.delete_all }
+
+
+=== Defining your own sharding methods
+
+It is possible with +DbCharmer+ for the users to define their own sharding methods. You need to do a
+few things to implement your very own sharding scheme:
+
+1) Create a class with a name <tt>DbCharmer::Sharding::Method::YourOwnName</tt>
+
+2) Implement at least a constructor <tt>initialize(config)</tt> and a lookup instance
+method <tt>shard_for_key(key)</tt> that would return either a connection name from <tt>database.yml</tt>
+file or just a hash of connection parameters for rails connection adapters.
+
+3) Register your sharded connection using the following call:
+
+  DbCharmer::Sharding.register_connection(
+    :name => :some_name,
+    :method => :your_own_name,    # your sharding method class name in lower case
+    ... some additional parameters if needed ...
+  )
+
+4) Use your sharded connection as any standard one.
+
+
+=== Adding support for default shards in your custom sharding methods
+
+If you want to be able to use +on_default_shard+ method on your custom-sharded models, you
+need to do two things:
+
+1) implement <tt>support_default_shard?</tt> instance method on your sharded class that
+would return +true+ if you do support default shard specification and +false+ otherwise.
+
+2) implement <tt>:default</tt> symbol support as a key in your +shard_for_key+ method.
+
+
+=== Adding support for shards enumeration in your custom sharding methods
+
+To add shards enumeration support to your custom-sharded models you need to implement
+an instance method +shard_connections+ on your class. This method should return an array of
+sharding connection names or connection configurations to be used to establish connections in a loop.
+
+
+== Documentation/Questions
+
+For more information about the library, please visit our site at http://kovyrin.github.com/db-charmer.
+If you need more defails on DbCharmer internals, please check out the source code. All the plugin's
+code is ~100% covered with tests (located in a separate staging rails project
+at http://github.com/kovyrin/db-charmer-sandbox). The project has unit tests for all or at
+least the most actively used code paths.
+
+If you have any questions regarding this project, you could contact the author using
+the DbCharmer Users Group mailing list:
+
+- Group Info: http://groups.google.com/group/db-charmer
+- Subscribe using the info page or by sending an email to mailto:db-charmer-subscribe@googlegroups.com
+
+
+== What Ruby and Rails implementations does it work for?
+
+We have a continuous integration setup for this gem on with Rails 2.2, 2.3 and 3.0 using a few
+different versions of Ruby. For more information about the build matrix please visit
+http://github.com/kovyrin/db-charmer-sandbox web site.
+
+In addition to CI testing, we use this gem in production on Scribd.com (one of the largest RoR
+sites in the world) with Ruby Enterprise Edition and Rails 2.2, Rails 2.3, Sinatra and plain
+Rack applications.
+
+Starting with version 1.7.0 we support Rails 3.0, but until further notice we consider it a
+beta-quality feature since we do not run any production software on this version of Rails. If you
+run your application on Rails 3.0, please contact the author.
+
+
+== Who are the authors?
+
+This plugin has been created in Scribd.com for our internal use and then the sources were opened for
+other people to use. Most of the code in this package has been developed by Oleksiy Kovyrin for
+Scribd.com and is released under the MIT license. For more details, see the LICENSE file.
+
+Other contributors who have helped with the development of this library are (alphabetically ordered):
+* Allen Madsen
+* Andrew Geweke
+* Ashley Martens
+* Dmytro Shteflyuk
+* Eric Lindvall
+* Gregory Man
+* Michael Birk
+* Tyler McMullen