README.rdoc in db-charmer-1.6.19 vs README.rdoc in db-charmer-1.7.0.pre1

@@ -26,11 +26,11 @@
 To install db-charmer as a Rails plugin use this:
 
   script/plugin install git://github.com/kovyrin/db-charmer.git
 
 _Notice_: If you use db-charmer 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> 
+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
 
@@ -50,10 +50,25 @@
   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.
@@ -241,10 +256,69 @@
 
 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 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
+
+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
@@ -490,14 +564,25 @@
 most of the parts of plugin's code.
 
 
 == What Ruby and Rails implementations does it work for?
 
-We have a continuous integration setups for this plugin on MRI 1.8.6 with Rails 2.2 and 2.3.
-We use the plugin in production on Scribd.com with MRI (rubyee) 1.8.6 and Rails 2.2.
+We have a continuous integration setups for this plugin on MRI 1.8.7 with Rails 2.2 and 2.3.
+We use the plugin in production on Scribd.com with MRI (rubyee) 1.8.7 and Rails 2.2, Rails 2.3,
+Sinatra and plain Rack applications.
 
 
 == 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. All the code in this package has been developed by Alexey Kovyrin for Scribd.com
+other people to use. Most of the code in this package has been developed by Alexey 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