db-charmer 1.8.4 → 1.9.0

checksums.yaml

@@ -0,0 +1,15 @@
+---
+!binary "U0hBMQ==":
+  metadata.gz: !binary |-
+    MDA4YjJhNmIzN2FlMzUzZDM5MzMwOWNhMTI0NTk3MmJhNDY1YjA3OA==
+  data.tar.gz: !binary |-
+    MmFiMTJhMjE0MTk2ZTIyOTJmYzZmMDZjZTUwZWI5OWIwZTY3YzE4MQ==
+SHA512:
+  metadata.gz: !binary |-
+    NTBkMzNmZGY3Yjc5ZDFmYTU4Y2YwMGFiNzlkZGQ2YTk3YmMwODAyNTQxMzZl
+    NWVhNzg3NjI3NDU4ZWM5ZjU2MDI5NzM4MzM4NDg4OWZhM2MyODFlNGIwNDBj
+    ZTAwMDJkMDEyNDY1OWI2Y2FkYzQ5MjMyNjBkODYxOTBjMTVhMmY=
+  data.tar.gz: !binary |-
+    ZjIyOTNhZjIxYTc3YjM2ZTc2ZDY2NzJlMDAwODZlMzYxYTEyYzEyMjE2NzVj
+    NjMwMjQ0MDk0NzI2ZjM0OTE0Yjg0MzYzYTM4OGZlMGM2YmZlZjhiOTcwNGEy
+    ZTM3Y2EyOTIxZGQ5ZWJkZjhhYWU4NDQ4OGY2ZGE1YzczMmMwODI=

data/CHANGES

@@ -1,3 +1,22 @@
+1.9.0 (2013-10-09):
+
+Most of the major changes in this version are related to our initial push towards making
+DbCharmer thread-safe and making sure it works correctly in multi-threaded environments.
+
+Please note, that even though we now test DbCharmer in multi-threaded environments, we still
+consider multi-threaded support experimental.
+
+Bug fix: Improved Rails environment detection (sometimes DbCharmer would use
+Rails-specific code while running in non-rails projects).
+
+Bug fix: Make sure on_db() method could restore original connection after an exception is
+raised from a DB driver during connection switching (Thanks to Dmytro Shteflyuk for finding
+the issue and helping with debugging).
+
+This is the first release that does not have a really strict constraint for point-releases
+within the Rails 3.2.x branch.
+
+----------------------------------------------------------------------------------------
 1.8.4 (2013-03-18):
 
 Bumped up rails dependencies up to 3.2.13.

data/README.rdoc

@@ -32,539 +32,6 @@ before using any of its connection management methods. Correct value here is a v
 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, :force_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://dbcharmer.net.
@@ -589,14 +56,14 @@ Build status is: {<img src="https://secure.travis-ci.org/kovyrin/db-charmer.png?
 
 At the moment we have the following build matrix:
 * Rails versions:
-  - 2.x
+  - 2.3
   - 3.0
   - 3.1
   - 3.2
 * Ruby versions:
   - 1.8.7
-  - Ruby Enterprise Edition (1.8.7)
-  - 1.9.3 (Rails 3 only since older versions do not support new ruby releases)
+  - 1.9.3 (Rails 3.0+ only)
+  - 2.0.0 (Rails 3.2+ only)
 * Databases:
   - MySQL
 
@@ -604,11 +71,19 @@ In addition to CI testing, this gem is used in production on Scribd.com (one of
 sites in the world) with Ruby Enterprise Edition and Rails 2.2, Rails 2.3, Sinatra and plain
 Rack applications.
 
-Starting with version 1.8.0 we support Rails versions up to 3.2.8. Please note, that Rails 3.2.4
+Starting with version 1.8.0 we support Rails versions 3.2.8 and higher. Please note, that Rails 3.2.4
 is not officially supported. Your code may work on that version, but no bug reports will be
 accepted about this version.
 
 
+== Is it Thread-Safe?
+
+Starting with version 1.9.0 we have started working on making the code thread-safe and making sure
+DbCharmer works correctly in multi-threaded environments. At this moment we consider multi-threaded
+mode experimental. If you use it and it works for you - please let us know, if it does not - please
+make sure to file a ticket so that we could improve the code and make it work in your situation.
+
+
 == Who are the authors?
 
 This plugin has been created in Scribd.com for our internal use and then the sources were opened for