multi_db 0.2.1

data/LICENSE

@@ -0,0 +1,20 @@
+The MIT license:
+Copyright (c) 2008 Maximilian Schöfmann
+ 
+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/README.rdoc

@@ -0,0 +1,236 @@
+= multi_db
+
+=====-- This GEM was inspired by Rick Olson's "masochism"-Plugin
+
+multi_db uses a connection proxy, which sends read queries to slave databases,
+and all write queries to the master database (Read/Write Split).
+Within transactions, while executing ActiveRecord Observers and
+within "with_master" blocks (see below), even read queries are sent to the 
+master database.
+
+=== Important changes in 0.2.0
+
+* As of this version, <tt>ActiveRecord::Base.connection</tt> does not return the
+  connection proxy by default anymore (therefore the jump to 0.2.0). Only models
+  inheriting from AR::B return the proxy, unless they are defined as master_models
+  (see below). If you want to access the connection proxy from AR::B directly,
+  use <tt>ActiveRecord::Base.connection_proxy</tt>.
+
+* This version is the first attempt for thread-safety of this gem. <em>There might
+  still be some threading issues left!</em>. So please test your apps thoroughly
+  and report any issues you might encounter.
+
+* <tt>CGI::Session::ActiveRecordStore::Session</tt> is now automatically registered
+  as a master model.
+
+=== Caveats
+
+* works only with activerecord 2.1, 2.2 and 2.3
+
+=== Install
+
+  gem sources --add http://gems.github.com # only if you haven't already added github
+  gem install schoefmax-multi_db
+
+When using Rails, add this to your environment.rb:
+
+  config.gem 'schoefmax-multi_db', :lib => 'multi_db', :source => 'http://gems.github.com'
+
+=== Setup
+
+In your database.yml, add sections for the slaves, e.g.:
+
+  production: # that would be the master
+    adapter: mysql
+    database: myapp_production
+    username: root
+    password: 
+    host: localhost
+
+  production_slave_database: # that would be a slave 
+    adapter: mysql
+    database: myapp_production
+    username: root
+    password: 
+    host: 10.0.0.2
+
+  production_slave_database_2: # another slave
+    ...
+  production_slave_database_in_india: # yet another one
+    ...
+
+*NOTE*: multi_db identifies slave databases by looking for entries of the form
+"<tt><environment>_slave_database<_optional_name></tt>". As a (useless) side effect you
+get abstract classes named <tt>MultiDb::SlaveDatabaseInIndia</tt> etc.
+The advantage of specifying the slaves explicitly, instead of the master, is that
+you can use the same configuration file for scripts that don't use multi_db.
+Also, when you decide to disable multi_db for some reason, you don't have to 
+swap hosts in your <tt>database.yml</tt> from master to slave (which is easy to forget...).
+
+To enable the proxy globally, add this to your environment.rb, or some file in
+config/initializers:
+
+  MultiDb::ConnectionProxy.setup!
+
+If you only want to enable it for specific environments, add this to 
+the corresponding file in config/environments:
+
+  config.after_initialize do
+    MultiDb::ConnectionProxy.setup!
+  end
+
+In the development and test environments, you can use identical configurations
+for master and slave connections. This can help you finding (some of the) issues
+your application might have with a replicated database setup without actually having
+one on your development machine.
+
+=== Using with Phusion Passenger
+
+With Passengers smart spawning method, child processes forked by the ApplicationSpawner
+won't have the connection proxy set up properly.
+
+To make it work, add this to your <tt>environment.rb</tt> or an initializer script
+(e.g. <tt>config/initializers/connection_proxy.rb</tt>):
+
+  if defined?(PhusionPassenger)
+    PhusionPassenger.on_event(:starting_worker_process) do |forked|
+      if forked
+        # ... set MultiDb configuration options, if any ...
+        MultiDb::ConnectionProxy.setup!
+      end
+    end
+  else # not using passenger (e.g. development/testing)
+    # ... set MultiDb configuration options, if any ...
+    MultiDb::ConnectionProxy.setup!
+  end
+
+Thanks to Nathan Esquenazi for testing this.
+
+=== Forcing the master for certain actions
+
+Just add this to your controller:
+
+  around_filter(:only => :foo_action) { |c,a| ActiveRecord::Base.connection_proxy.with_master { a.call } }
+
+=== Forcing the master for certain models
+
+In your environment.rb or an initializer, add this *before* the call to <tt>setup!</tt>:
+
+  MultiDb::ConnectionProxy.master_models = ['CGI::Session::ActiveRecordStore::Session', 'PaymentTransaction', ...]
+  MultiDb::ConnectionProxy.setup!
+
+*NOTE*: You cannot safely add more master_models after calling <tt>setup!</tt>.
+
+=== Making one slave database sticky during a request
+
+This can be useful to leverage database level query caching as all queries will
+be sent to the same slave database during one web request.
+
+To enable, add this to your environment.rb just before <tt>MultiDb::ConnectionProxy.setup!</tt>:
+
+   MultiDb::ConnectionProxy.sticky_slave = true
+
+And add this to your ApplicationController:
+
+   after_filter { ActiveRecord::Base.connection_proxy.next_reader! }
+
+*NOTE*: It's not possible to toggle this mode in a running process, as the dynamically
+generated methods will have the initially defined "stickyness" built in.
+
+=== Usage outside of Rails
+
+You can use multi_db together with other framworks or in standalone scripts.
+Example:
+
+ require 'rubygems'
+ require 'active_record'
+ require 'multi_db'
+
+ ActiveRecord::Base.logger = Logger.new(STDOUT)
+ ActiveRecord::Base.configurations = {
+   'development' => {
+     'adapter'  => 'mysql',
+     'host'     => 'localhost',
+     'username' => 'root',
+     'database' => 'multi_db_test'
+   },
+   'development_slave_database' => {
+     'adapter'  => 'mysql',
+     'host'     => 'localhost',
+     'username' => 'root',
+     'database' => 'multi_db_test'
+   }
+ }
+ ActiveRecord::Base.establish_connection :development
+ MultiDb::ConnectionProxy.setup!
+
+ class MyModel < ActiveRecord::Base
+   # ...
+ end
+
+ # ...
+
+Note that the configurations hash should contain strings as keys instead of symbols.
+
+=== Differences to "masochism":
+
+* Supports multiple slave databases (round robin)
+* It sends everything except "select ..." queries to the master, instead of
+  sending only specific things to the master and anything "else" to the slave.
+  This avoids accidential writes to the master when there are API changes in
+  ActiveRecord which haven't been picked up by multi_db yet.
+  Note that this behaviour will also always send helper methods like "+quote+" or
+  "<tt>add_limit!</tt>" to the master connection object, which doesn't add any
+  more load on the master, as these methods don't communicate with the db server
+  itself.
+* It uses its own query cache as the slave's cache isn't emptied when there are
+  changes on the master
+* It supports immediate failover for slave connections
+* It will wait some time before trying to query a failed slave database again
+* It supports nesting "with_master"-blocks, without unexpectedly switching you
+  back to the slave again
+* It schedules a reconnect of the master connection if statements fail there.
+  This might help with HA setups using virtual IPs (a test setup would be nice
+  to verify this)
+* You specify slave databases in the configuration instead of specifying an extra
+  master database. This makes disabling or removing multi_db less dangerous
+  (Update: Recent versions of masochism support this, too).
+* There are no <tt>set_to_master!</tt> and <tt>set_to_slave!</tt> methods, just
+  <tt>with_master(&block)</tt>
+* All proxied methods are dynamically generated for better performance
+
+=== See also
+
+==== Masochism
+
+The original plugin:
+
+* http://github.com/technoweenie/masochism
+
+==== DataFabric
+
+A solution by FiveRuns, also based on masochism but without the "nested with_master"-issue,
+threadsafe and allows sharding of data.
+
+* http://github.com/fiveruns/data_fabric
+
+=== Contributors
+
+* Matt Conway http://github.com/wr0ngway
+* Matthias Marshall http://github.com/webops
+
+=== Ideas
+
+See: http://github.com/schoefmax/multi_db/wikis/home
+
+=== Running specs
+
+If you haven't already, install the rspec gem, then create an empty database
+called "multi_db_test" (you might want to tweak the spec/config/database.yml).
+From the plugin directory, run:
+
+  spec spec
+
+
+Copyright (c) 2008, Max Schoefmann <max (a) pragmatic-it de>
+Released under the MIT license

data/lib/multi_db.rb

@@ -0,0 +1,6 @@
+require 'tlattr_accessors'
+require 'multi_db/scheduler'
+require 'multi_db/active_record_extensions'
+require 'multi_db/observer_extensions'
+require 'multi_db/query_cache_compat'
+require 'multi_db/connection_proxy'

data/lib/multi_db/active_record_extensions.rb

@@ -0,0 +1,55 @@
+module MultiDb
+  module ActiveRecordExtensions
+    def self.included(base)
+      base.send :include, InstanceMethods
+      base.send :extend, ClassMethods
+      base.alias_method_chain :reload, :master
+      base.cattr_accessor :connection_proxy
+      # handle subclasses which were defined by the framework or plugins
+      base.send(:subclasses).each do |child|
+        child.hijack_connection
+      end
+    end
+
+    module InstanceMethods
+      def reload_with_master(*args, &block)
+        self.connection_proxy.with_master { reload_without_master }
+      end
+    end
+
+    module ClassMethods
+      # Make sure transactions always switch to the master
+      def transaction(&block)
+        if self.connection.kind_of?(ConnectionProxy)
+          super
+        else
+          self.connection_proxy.with_master { super }
+        end
+      end
+
+      # make caching always use the ConnectionProxy
+      def cache(&block)
+        if ActiveRecord::Base.configurations.blank?
+          yield
+        else
+          self.connection_proxy.cache(&block)
+        end
+      end
+
+      def inherited(child)
+        super
+        child.hijack_connection
+      end
+
+      def hijack_connection
+        return if ConnectionProxy.master_models.include?(self.to_s)
+        logger.info "[MULTIDB] hijacking connection for #{self.to_s}"
+        class << self
+          def connection
+            self.connection_proxy
+          end
+        end
+      end
+    end
+  end
+end

data/lib/multi_db/connection_proxy.rb

@@ -0,0 +1,189 @@
+module MultiDb
+  class ConnectionProxy
+    include QueryCacheCompat
+    include ActiveRecord::ConnectionAdapters::QueryCache
+    extend ThreadLocalAccessors
+    
+    # Safe methods are those that should either go to the slave ONLY or go
+    # to the current active connection.
+    SAFE_METHODS = [ :select_all, :select_one, :select_value, :select_values, 
+      :select_rows, :select, :verify!, :raw_connection, :active?, :reconnect!,
+      :disconnect!, :reset_runtime, :log, :log_info ]
+
+    if ActiveRecord.const_defined?(:SessionStore) # >= Rails 2.3
+      DEFAULT_MASTER_MODELS = ['ActiveRecord::SessionStore::Session']
+    else # =< Rails 2.3
+      DEFAULT_MASTER_MODELS = ['CGI::Session::ActiveRecordStore::Session']
+    end
+
+    attr_accessor :master
+    tlattr_accessor :master_depth, :current, true
+    
+    class << self
+
+      # defaults to RAILS_ENV if multi_db is used with Rails
+      # defaults to 'development' when used outside Rails
+      attr_accessor :environment
+      
+      # a list of models that should always go directly to the master
+      #
+      # Example:
+      #
+      #  MultiDb::ConnectionProxy.master_models = ['MySessionStore', 'PaymentTransaction']
+      attr_accessor :master_models
+
+      # decides if we should switch to the next reader automatically.
+      # If set to false, an after|before_filter in the ApplicationController
+      # has to do this.
+      # This will not affect failover if a master is unavailable.
+      attr_accessor :sticky_slave
+
+      # Replaces the connection of ActiveRecord::Base with a proxy and
+      # establishes the connections to the slaves.
+      def setup!
+        self.master_models ||= DEFAULT_MASTER_MODELS
+        self.environment   ||= (defined?(RAILS_ENV) ? RAILS_ENV : 'development')
+        self.sticky_slave  ||= false
+        
+        master = ActiveRecord::Base
+        slaves = init_slaves
+        raise "No slaves databases defined for environment: #{self.environment}" if slaves.empty?
+        master.send :include, MultiDb::ActiveRecordExtensions
+        ActiveRecord::Observer.send :include, MultiDb::ObserverExtensions
+        master.connection_proxy = new(master, slaves)
+        master.logger.info("** multi_db with master and #{slaves.length} slave#{"s" if slaves.length > 1} loaded.")
+      end
+
+      protected
+
+      # Slave entries in the database.yml must be named like this
+      #   development_slave_database:
+      # or
+      #   development_slave_database1:
+      # or
+      #   production_slave_database_someserver:
+      # These would be available later as MultiDb::SlaveDatabaseSomeserver
+      def init_slaves
+        returning([]) do |slaves|
+          ActiveRecord::Base.configurations.keys.each do |name|
+            if name.to_s =~ /#{self.environment}_(slave_database.*)/
+              MultiDb.module_eval %Q{
+                class #{$1.camelize} < ActiveRecord::Base
+                  self.abstract_class = true
+                  establish_connection :#{name}
+                end
+              }, __FILE__, __LINE__
+              slaves << "MultiDb::#{$1.camelize}".constantize
+            end
+          end
+        end
+      end
+
+      private :new
+      
+    end
+
+    def initialize(master, slaves)
+      @slaves    = Scheduler.new(slaves)
+      @master    = master
+      @reconnect = false
+      self.current      = @slaves.current
+      self.master_depth = 0
+    end
+
+    def slave
+      @slaves.current
+    end
+
+    def with_master
+      self.current = @master
+      self.master_depth += 1
+      yield
+    ensure
+      self.master_depth -= 1
+      self.current = slave if master_depth.zero?
+    end
+    
+    def transaction(start_db_transaction = true, &block)
+      with_master { @master.retrieve_connection.transaction(start_db_transaction, &block) }
+    end
+
+    # Calls the method on master/slave and dynamically creates a new
+    # method on success to speed up subsequent calls
+    def method_missing(method, *args, &block)
+      returning(send(target_method(method), method, *args, &block)) do 
+        create_delegation_method!(method)
+      end
+    end
+
+    # Switches to the next slave database for read operations.
+    # Fails over to the master database if all slaves are unavailable.
+    def next_reader!
+      return unless master_depth.zero? # don't if in with_master block
+      self.current = @slaves.next
+    rescue Scheduler::NoMoreItems
+      logger.warn "[MULTIDB] All slaves are blacklisted. Reading from master"
+      self.current = @master
+    end
+
+    protected
+
+    def create_delegation_method!(method)
+      self.instance_eval %Q{
+        def #{method}(*args, &block)
+          #{'next_reader!' unless self.class.sticky_slave || unsafe?(method)}
+          #{target_method(method)}(:#{method}, *args, &block)
+        end
+      }, __FILE__, __LINE__
+    end
+    
+    def target_method(method)
+      unsafe?(method) ? :send_to_master : :send_to_current
+    end
+    
+    def send_to_master(method, *args, &block)
+      reconnect_master! if @reconnect
+      @master.retrieve_connection.send(method, *args, &block)
+    rescue => e
+      raise_master_error(e)
+    end
+    
+    def send_to_current(method, *args, &block)
+      reconnect_master! if @reconnect && master?
+      current.retrieve_connection.send(method, *args, &block)
+    rescue NotImplementedError, NoMethodError
+      raise
+    rescue => e # TODO don't rescue everything
+      raise_master_error(e) if master?
+      logger.warn "[MULTIDB] Error reading from slave database"
+      logger.error %(#{e.message}\n#{e.backtrace.join("\n")})
+      @slaves.blacklist!(current)
+      next_reader!
+      retry
+    end
+    
+    def reconnect_master!
+      @master.retrieve_connection.reconnect!
+      @reconnect = false
+    end
+    
+    def raise_master_error(error)
+      logger.fatal "[MULTIDB] Error accessing master database. Scheduling reconnect"
+      @reconnect = true
+      raise error
+    end
+    
+    def unsafe?(method)
+      !SAFE_METHODS.include?(method)
+    end
+    
+    def master?
+      current == @master
+    end
+        
+    def logger
+      ActiveRecord::Base.logger
+    end
+
+  end
+end

data/lib/multi_db/observer_extensions.rb

@@ -0,0 +1,18 @@
+module MultiDb
+  module ObserverExtensions
+    def self.included(base)
+      base.alias_method_chain :update, :masterdb
+    end
+    
+    # Send observed_method(object) if the method exists.
+    def update_with_masterdb(observed_method, object) #:nodoc:
+      if object.class.connection.respond_to?(:with_master)
+        object.class.connection.with_master do
+          update_without_masterdb(observed_method, object)
+        end
+      else
+        update_without_masterdb(observed_method, object)
+      end
+    end
+  end
+end

data/lib/multi_db/query_cache_compat.rb

@@ -0,0 +1,21 @@
+module MultiDb
+  # Implements the methods expected by the QueryCache module
+  module QueryCacheCompat
+    def select_all(*a, &b)
+      next_reader! unless ConnectionProxy.sticky_slave
+      send_to_current(:select_all, *a, &b)
+    end
+    def columns(*a, &b)
+      send_to_current(:columns, *a, &b)
+    end
+    def insert(*a, &b)
+      send_to_master(:insert, *a, &b)
+    end
+    def update(*a, &b)
+      send_to_master(:update, *a, &b)
+    end
+    def delete(*a, &b)
+      send_to_master(:delete, *a, &b)
+    end
+  end
+end

data/lib/multi_db/scheduler.rb

@@ -0,0 +1,41 @@
+module MultiDb
+  class Scheduler
+    class NoMoreItems < Exception; end
+    extend ThreadLocalAccessors
+
+    attr :items
+    delegate :[], :[]=, :to => :items
+    tlattr_accessor :current_index, true
+    
+    def initialize(items, blacklist_timeout = 1.minute)
+      @n = items.length
+      @items     = items
+      @blacklist = Array.new(@n, Time.at(0))
+      @blacklist_timeout = blacklist_timeout
+      self.current_index = 0
+    end
+    
+    def blacklist!(item)
+      @blacklist[@items.index(item)] = Time.now
+    end
+    
+    def current
+      @items[current_index]
+    end
+    
+    def next
+      previous = current_index
+      until(@blacklist[next_index!] < Time.now - @blacklist_timeout) do
+        raise NoMoreItems, 'All items are blacklisted' if current_index == previous
+      end
+      current
+    end
+    
+    protected
+    
+    def next_index!
+      self.current_index = (current_index + 1) % @n
+    end
+
+  end
+end

data/multi_db.gemspec

@@ -0,0 +1,36 @@
+# -*- encoding: utf-8 -*-
+
+Gem::Specification.new do |s|
+  s.name = %q{multi_db}
+  s.version = "0.2.1"
+
+  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
+  s.authors = ["Maximilian Sch\303\266fmann"]
+  s.date = %q{2009-03-11}
+  s.description = "Connection proxy for ActiveRecord for single master / multiple slave database deployments"
+  s.email = "max@pragmatic-it.de"
+  s.extra_rdoc_files = ["LICENSE", "README.rdoc"]
+  s.files = ["lib/multi_db.rb", "lib/multi_db/active_record_extensions.rb", "lib/multi_db/connection_proxy.rb", "lib/multi_db/observer_extensions.rb", "lib/multi_db/query_cache_compat.rb", "lib/multi_db/scheduler.rb", "LICENSE", "README.rdoc", "spec/config/database.yml", "spec/connection_proxy_spec.rb", "spec/scheduler_spec.rb", "spec/spec_helper.rb", "multi_db.gemspec"]
+  s.has_rdoc = true
+  s.homepage = "http://github.com/schoefmax/multi_db"
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "multi_db", "--main", "README.rdoc"]
+  s.require_paths = ["lib"]
+  s.rubyforge_project = "multi_db"
+  s.rubygems_version = %q{1.3.1}
+  s.summary = "Connection proxy for ActiveRecord for single master / multiple slave database deployments"
+
+  if s.respond_to? :specification_version then
+    s.specification_version = 2
+
+    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency('activerecord', [">= 2.1.0"])
+      s.add_runtime_dependency('tlattr_accessors', [">= 0.0.3"])
+    else
+      s.add_dependency('activerecord', [">= 2.1.0"])
+      s.add_dependency('tlattr_accessors', [">= 0.0.3"])
+    end
+  else
+    s.add_dependency('activerecord', [">= 2.1.0"])
+    s.add_dependency('tlattr_accessors', [">= 0.0.3"])
+  end
+end

data/spec/config/database.yml

@@ -0,0 +1,23 @@
+test:
+  adapter: mysql
+  database: multi_db_test
+  username: root
+  password:
+  host: 127.0.0.1
+  pool: 5
+
+test_slave_database_1:
+  adapter: mysql
+  database: multi_db_test
+  username: root
+  password:
+  host: 127.0.0.1
+  pool: 5
+
+test_slave_database_2:
+  adapter: mysql
+  database: multi_db_test
+  username: root
+  password:
+  host: 127.0.0.1
+  pool: 5

data/spec/connection_proxy_spec.rb

@@ -0,0 +1,229 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require MULTI_DB_SPEC_DIR + '/../lib/multi_db/query_cache_compat'
+require MULTI_DB_SPEC_DIR + '/../lib/multi_db/active_record_extensions'
+require MULTI_DB_SPEC_DIR + '/../lib/multi_db/observer_extensions'
+require MULTI_DB_SPEC_DIR + '/../lib/multi_db/scheduler'
+require MULTI_DB_SPEC_DIR + '/../lib/multi_db/connection_proxy'
+
+RAILS_ROOT = MULTI_DB_SPEC_DIR
+
+describe MultiDb::ConnectionProxy do
+
+  before(:all) do
+    ActiveRecord::Base.configurations = MULTI_DB_SPEC_CONFIG
+    ActiveRecord::Base.establish_connection :test
+    ActiveRecord::Migration.verbose = false
+    ActiveRecord::Migration.create_table(:master_models, :force => true) {}
+    class MasterModel < ActiveRecord::Base; end
+    ActiveRecord::Migration.create_table(:foo_models, :force => true) {|t| t.string :bar}
+    class FooModel < ActiveRecord::Base; end
+    @sql = 'SELECT 1 + 1 FROM DUAL'
+  end
+  
+  before(:each) do
+    MultiDb::ConnectionProxy.master_models = ['MasterModel']
+    MultiDb::ConnectionProxy.setup!
+    @proxy = ActiveRecord::Base.connection_proxy
+    @master = @proxy.master.retrieve_connection
+    @slave1 = MultiDb::SlaveDatabase1.retrieve_connection
+    @slave2 = MultiDb::SlaveDatabase2.retrieve_connection
+  end
+
+  after(:each) do
+    ActiveRecord::Base.send :alias_method, :reload, :reload_without_master
+  end
+
+  it 'AR::B should respond to #connection_proxy' do
+    ActiveRecord::Base.connection_proxy.should be_kind_of(MultiDb::ConnectionProxy)
+  end
+
+  it 'FooModel#connection should return an instance of MultiDb::ConnectionProxy' do
+    FooModel.connection.should be_kind_of(MultiDb::ConnectionProxy)
+  end
+
+  it 'MasterModel#connection should not return an instance of MultiDb::ConnectionProxy' do
+    MasterModel.connection.should_not be_kind_of(MultiDb::ConnectionProxy)
+  end
+
+  it "should generate classes for each entry in the database.yml" do
+    defined?(MultiDb::SlaveDatabase1).should_not be_nil
+    defined?(MultiDb::SlaveDatabase2).should_not be_nil
+  end
+  
+  it 'should handle nested with_master-blocks correctly' do
+    @proxy.current.should_not == @proxy.master
+    @proxy.with_master do
+      @proxy.current.should == @proxy.master
+      @proxy.with_master do
+        @proxy.current.should == @proxy.master
+        @proxy.with_master do
+          @proxy.current.should == @proxy.master
+        end
+        @proxy.current.should == @proxy.master
+      end
+      @proxy.current.should == @proxy.master
+    end
+    @proxy.current.should_not == @proxy.master
+  end
+  
+  it 'should perform transactions on the master' do
+    @master.should_receive(:select_all).exactly(1) # makes sure the first one goes to a slave
+    @proxy.select_all(@sql)
+    ActiveRecord::Base.transaction do
+      @proxy.select_all(@sql)
+    end
+  end
+  
+  it 'should switch to the next reader on selects' do
+    @slave1.should_receive(:select_one).exactly(2)
+    @slave2.should_receive(:select_one).exactly(2)
+    4.times { @proxy.select_one(@sql) }
+  end
+  
+  it 'should not switch to the next reader when whithin a with_master-block' do
+    @master.should_receive(:select_one).twice
+    @slave1.should_not_receive(:select_one)
+    @slave2.should_not_receive(:select_one)
+    @proxy.with_master do
+      2.times { @proxy.select_one(@sql) }
+    end
+  end
+
+  it 'should send dangerous methods to the master' do
+    meths = [:insert, :update, :delete, :execute]
+    meths.each do |meth|
+      @slave1.stub!(meth).and_raise(RuntimeError)
+      @master.should_receive(meth).and_return(true)
+      @proxy.send(meth, @sql)
+    end
+  end
+  
+  it 'should dynamically generate safe methods' do
+    @proxy.should_not respond_to(:select_value)
+    @proxy.select_value(@sql)
+    @proxy.should respond_to(:select_value)
+  end
+  
+  it 'should cache queries using select_all' do
+    ActiveRecord::Base.cache do
+      # next_reader will be called and switch to the SlaveDatabase2
+      @slave2.should_receive(:select_all).exactly(1)
+      @slave1.should_not_receive(:select_all)
+      @master.should_not_receive(:select_all)
+      3.times { @proxy.select_all(@sql) }
+    end
+  end
+  
+  it 'should invalidate the cache on insert, delete and update' do
+    ActiveRecord::Base.cache do
+      meths = [:insert, :update, :delete]
+      meths.each do |meth|
+        @master.should_receive(meth).and_return(true)
+      end
+      @slave2.should_receive(:select_all).twice
+      @slave1.should_receive(:select_all).once
+      3.times do |i|
+        @proxy.select_all(@sql)
+        @proxy.send(meths[i])
+      end
+    end
+  end
+  
+  it 'should retry the next slave when one fails and finally fall back to the master' do
+    @slave1.should_receive(:select_all).once.and_raise(RuntimeError)
+    @slave2.should_receive(:select_all).once.and_raise(RuntimeError)
+    @master.should_receive(:select_all).and_return(true)
+    @proxy.select_all(@sql)
+  end
+  
+  it 'should try to reconnect the master connection after the master has failed' do
+    @master.should_receive(:update).and_raise(RuntimeError)
+    lambda { @proxy.update(@sql) }.should raise_error
+    @master.should_receive(:reconnect!).and_return(true)
+    @master.should_receive(:insert).and_return(1)
+    @proxy.insert(@sql)
+  end
+
+  it 'should reload models from the master' do
+    foo = FooModel.create!(:bar => 'baz')
+    foo.bar = "not_saved"
+    @slave1.should_not_receive(:select_all)
+    @slave2.should_not_receive(:select_all)
+    foo.reload
+    # we didn't stub @master#select_all here, check that we actually hit the db
+    foo.bar.should == 'baz'
+  end
+  
+  describe 'with sticky_slave ' do
+
+    before { MultiDb::ConnectionProxy.sticky_slave = true  }
+    after  { MultiDb::ConnectionProxy.sticky_slave = false }
+
+    it 'should not switch to the next reader automatically' do
+      @slave1.should_receive(:select_all).exactly(3)
+      @slave2.should_receive(:select_all).exactly(0)
+      3.times { @proxy.select_all(@sql) }
+    end
+
+    it '#next_reader! should switch to the next slave' do
+      @slave1.should_receive(:select_one).exactly(3)
+      @slave2.should_receive(:select_one).exactly(7)
+      3.times { @proxy.select_one(@sql) }
+      @proxy.next_reader!
+      7.times { @proxy.select_one(@sql) }
+    end
+
+  end
+
+  describe '(accessed from multiple threads)' do
+    # NOTE: We cannot put expectations on the connection objects itself
+    #       for the threading specs, as connection pooling will cause
+    #       different connections being returned for different threads.
+
+    it '#current and #next_reader! should be local to the thread' do
+      @proxy.current.should == MultiDb::SlaveDatabase1
+      @proxy.next_reader!.should == MultiDb::SlaveDatabase2
+      Thread.new do
+        @proxy.current.should == MultiDb::SlaveDatabase1
+        @proxy.next_reader!.should == MultiDb::SlaveDatabase2
+        @proxy.current.should == MultiDb::SlaveDatabase2
+        @proxy.next_reader!.should == MultiDb::SlaveDatabase1
+        @proxy.current.should == MultiDb::SlaveDatabase1
+      end
+      @proxy.current.should == MultiDb::SlaveDatabase2
+    end
+
+    it '#with_master should be local to the thread' do
+      @proxy.current.should_not == @proxy.master
+      @proxy.with_master do
+        @proxy.current.should == @proxy.master
+        Thread.new do
+          @proxy.current.should_not == @proxy.master
+          @proxy.with_master do
+            @proxy.current.should == @proxy.master
+          end
+          @proxy.current.should_not == @proxy.master
+        end
+        @proxy.current.should == @proxy.master
+      end
+      @proxy.current.should_not == @proxy.master
+    end
+
+    it 'should switch to the next reader even whithin with_master-block in different threads' do
+      # Because of connection pooling in AR 2.2, the second thread will cause
+      # a new connection being created behind the scenes. We therefore just test
+      # that these connections are beting retrieved for the right databases here.
+      @proxy.master.should_not_receive(:retrieve_connection).and_return(@master)
+      MultiDb::SlaveDatabase1.should_receive(:retrieve_connection).twice.and_return(@slave1)
+      MultiDb::SlaveDatabase2.should_receive(:retrieve_connection).once.and_return(@slave2)
+      @proxy.with_master do
+        Thread.new do
+          3.times { @proxy.select_one(@sql) }
+        end.join
+      end
+    end
+
+  end
+
+end
+

data/spec/scheduler_spec.rb

@@ -0,0 +1,58 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require MULTI_DB_SPEC_DIR + '/../lib/multi_db/scheduler'
+
+describe MultiDb::Scheduler do
+  
+  before do
+    @items = [5, 7, 4, 8]
+    @scheduler = MultiDb::Scheduler.new(@items.clone)
+  end
+  
+  it "should return items in a round robin fashion" do
+    first = @items.shift
+    @scheduler.current.should == first
+    @items.each do |item|
+      @scheduler.next.should == item
+    end
+    @scheduler.next.should == first
+  end
+  
+  it 'should not return blacklisted items' do
+    @scheduler.blacklist!(4)
+    @items.size.times do
+      @scheduler.next.should_not == 4
+    end
+  end
+  
+  it 'should raise NoMoreItems if all are blacklisted' do
+    @items.each do |item|
+      @scheduler.blacklist!(item)
+    end
+    lambda {
+      @scheduler.next
+    }.should raise_error(MultiDb::Scheduler::NoMoreItems)
+  end
+  
+  it 'should unblacklist items automatically' do
+    @scheduler = MultiDb::Scheduler.new(@items.clone, 1.second)
+    @scheduler.blacklist!(7)
+    sleep(1)
+    @scheduler.next.should == 7
+  end
+
+  describe '(accessed from multiple threads)' do
+
+    it '#current and #next should return the same item for the same thread' do
+      @scheduler.current.should == 5
+      @scheduler.next.should == 7
+      Thread.new do
+        @scheduler.current.should == 5
+        @scheduler.next.should == 7
+      end.join
+      @scheduler.next.should == 4
+    end
+
+  end
+  
+end
+

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+require 'rubygems'
+gem 'activerecord', '2.2.2'
+%w[tlattr_accessors active_record yaml erb spec].each {|lib| require lib}
+
+RAILS_ENV = ENV['RAILS_ENV'] = 'test'
+
+MULTI_DB_SPEC_DIR = File.dirname(__FILE__)
+MULTI_DB_SPEC_CONFIG = YAML::load(File.open(MULTI_DB_SPEC_DIR + '/config/database.yml'))
+
+ActiveRecord::Base.logger = Logger.new(MULTI_DB_SPEC_DIR + "/debug.log")
+ActiveRecord::Base.configurations = MULTI_DB_SPEC_CONFIG

metadata

@@ -0,0 +1,92 @@
+--- !ruby/object:Gem::Specification 
+name: multi_db
+version: !ruby/object:Gem::Version 
+  version: 0.2.1
+platform: ruby
+authors: 
+- "Maximilian Sch\xC3\xB6fmann"
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-03-11 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: activerecord
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 2.1.0
+    version: 
+- !ruby/object:Gem::Dependency 
+  name: tlattr_accessors
+  type: :runtime
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.0.3
+    version: 
+description: Connection proxy for ActiveRecord for single master / multiple slave database deployments
+email: max@pragmatic-it.de
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- LICENSE
+- README.rdoc
+files: 
+- lib/multi_db.rb
+- lib/multi_db/active_record_extensions.rb
+- lib/multi_db/connection_proxy.rb
+- lib/multi_db/observer_extensions.rb
+- lib/multi_db/query_cache_compat.rb
+- lib/multi_db/scheduler.rb
+- LICENSE
+- README.rdoc
+- spec/config/database.yml
+- spec/connection_proxy_spec.rb
+- spec/scheduler_spec.rb
+- spec/spec_helper.rb
+- multi_db.gemspec
+has_rdoc: true
+homepage: http://github.com/schoefmax/multi_db
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --line-numbers
+- --inline-source
+- --title
+- multi_db
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "1.2"
+  version: 
+requirements: []
+
+rubyforge_project: multi_db
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 2
+summary: Connection proxy for ActiveRecord for single master / multiple slave database deployments
+test_files: []
+