schoefmax-multi_db 0.1.1 → 0.1.2

data/README.rdoc

@@ -10,13 +10,14 @@ master database.
 
 === Caveats
 
-* works with activerecord 2.1 - 2.2
+* works with activerecord 2.1 and 2.2, but is not threadsafe (yet)
+* when using Passenger or lightspeed you will probably need to introduce a before_filter which checks if the proxy is setup (see the discussion in the masochism readme: http://github.com/technoweenie/masochism/tree/master)
 
 === Install
 
   gem install schoefmax-multi_db --source http://gems.github.com
 
-In Rails 2.1, add this to your environment.rb:
+When using Rails, add this to your environment.rb:
 
   config.gem 'schoefmax-multi_db', :lib => 'multi_db', :source => 'http://gems.github.com'
 
@@ -38,13 +39,18 @@ In your database.yml, add sections for the slaves, e.g.:
     password: 
     host: 10.0.0.2
 
-  production_slave_database2: # another slave
+  production_slave_database_2: # another slave
     ...
-  production_slave_database_some_server: # yet another one
+  production_slave_database_in_india: # yet another one
     ...
 
-*NOTE*: multi_db identifies slave databases by looking for "slave_database" 
-somewhere in the database name!
+*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:
@@ -58,38 +64,88 @@ the corresponding file in config/environments:
     MultiDb::ConnectionProxy.setup!
   end
 
-In the development and test environments, you can use the same configuration
-for your master and slave databases.
+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.
+
+=== Forcing the master for certain actions
+
+Just add this to your controller:
+
+  around_filter(:only => :foo_action) { |c,a| MyModel.connection.with_master { a.call } }
+
+=== Forcing the master for certain models
+
+In your environment.rb or an initializer, add:
+
+  MultiDb::ConnectionProxy.master_models = ['PaymentTransaction', ...]
+
+=== 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":
 
-* Support for multiple slave connections (round robin)
-* It sends anything except "select ..." queries to the master, instead of 
-  sending only specific things to the master and anything "else" to the slave, 
-  which is a lot more dangerous (e.g. "execute" wasn't sent to the master in 
-  earlier versions of masochism)
-* It sends everything coming from AR-Observers to the master, to avoid race 
-  conditions (idea from one of the commenters on a blog entry about masochism)
-* It uses its own query cache (with masochism, the slave's cache isn't emptied 
-  when there are changes on the master)
+* 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 nested "with_master"-blocks (in masochism, nesting such blocks 
-  would unexpectedly switch you to the slave again)
-* It schedules a reconnect on the master connection to avoid problems
-  with virtual, migrating IPs for the master (e.g. multi-master HA setups)
-* It's possible to specify slave_database instead of master_database which
-  makes migration between with and without multi_db less dangerous
-* It allows environment specific settings for different slave setups
-* It doesn't come with set_to_master! and set_to_slave!, as these are 
-  considered dangerous (and make no sense) in a multi-slave setup. Instead of 
-  set_to_master!, use with_master { code }
-
+* 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.
+* 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
 
 === Contributors
 
- * Matt Conway http://github.com/wr0ngway
- * Matthias Marshall http://github.com/webops
+* Matt Conway http://github.com/wr0ngway
+* Matthias Marshall http://github.com/webops
 
 === Running specs
 

data/lib/multi_db/active_record_extensions.rb

@@ -10,7 +10,11 @@ module MultiDb
         
         # hijack the original method
         def connection
-          @@connection_proxy
+          if ConnectionProxy.master_models.include?(self.to_s)
+            self.retrieve_connection
+          else
+            @@connection_proxy
+          end
         end
       end
       

data/lib/multi_db/connection_proxy.rb

@@ -13,33 +13,28 @@ module MultiDb
     attr_accessor :current
     
     class << self
-      
-      # Example:
-      #  MultiDb::ConnectionProxy.configuration = {
-      #    :production_master_database => {
-      #      :adapter => 
-      #    }
-      #  }
-      # defaults to the content of Rails.root/config/database.yml if not set and used with Rails
-      attr_accessor :configuration
+
       # 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 = %w[PaymentTransactions]
+      attr_accessor :master_models
+
+      # Replaces the connection of ActiveRecord::Base with a proxy and
+      # establishes the connections to the slaves.
       def setup!
-        # if no configuration was set, we assume that rails is used and load the database.yml
-        unless self.configuration
-          raise "RAILS_ROOT not set. Set MultiDb::ConnectionProxy.configuration manually if you use multi_db outside rails" unless defined?(RAILS_ROOT)
-          self.configuration = YAML.load(ERB.new(File.read(File.join(RAILS_ROOT, 'config', 'database.yml'))).result)
-        end
-        unless self.environment
-          raise "RAILS_ENV not set. Set MultiDb::ConnectionProxy.environment manually if you use multi_db outside rails" unless defined?(RAILS_ENV)
-          self.environment = RAILS_ENV
-        end
+        self.master_models ||= []
+        self.environment   ||= (defined?(RAILS_ENV) ? RAILS_ENV : 'development')
+        
         master = ActiveRecord::Base
-        master.send :include, MultiDb::ActiveRecordExtensions
         slaves = init_slaves
-        raise "No slaves defined in database configuration" if slaves.empty?
-        slaves.each {|slave| slave.send :include, MultiDb::ActiveRecordExtensions}
+        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.")
@@ -54,7 +49,7 @@ module MultiDb
       # These would be available later as MultiDb::SlaveDatabaseSomeserver
       def init_slaves
         returning([]) do |slaves|
-          self.configuration.keys.each do |name|
+          ActiveRecord::Base.configurations.keys.each do |name|
             if name.to_s =~ /#{self.environment}_(slave_database.*)/
               MultiDb.module_eval %Q{
                 class #{$1.camelize} < ActiveRecord::Base

data/multi_db.gemspec

@@ -2,14 +2,14 @@
 
 Gem::Specification.new do |s|
   s.name = %q{multi_db}
-  s.version = "0.1.1"
+  s.version = "0.1.2"
 
   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-01-29}
   s.description = "Connection proxy for ActiveRecord for single master / multiple slave database deployments"
   s.email = "max@pragmatic-it.de"
-  s.extra_rdoc_files = ["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"]
+  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"

data/spec/connection_proxy_spec.rb

@@ -8,12 +8,21 @@ 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.establish_connection(MULTI_DB_SPEC_CONFIG['test'])
+    ActiveRecord::Base.configurations = MULTI_DB_SPEC_CONFIG
+    ActiveRecord::Base.establish_connection :test
+    class MasterModel < ActiveRecord::Base; end
+    @sql = 'SELECT 1 + 1 FROM DUAL'
+  end
+  
+  before(:each) do
     MultiDb::ConnectionProxy.setup!
     @proxy = ActiveRecord::Base.connection
-    @sql = 'SELECT 1 + 1 FROM DUAL'
+  end
+
+  it 'AR::B#connection should return an instance of MultiDb::ConnectionProxy' do
+    ActiveRecord::Base.connection.should be_a(MultiDb::ConnectionProxy)
   end
 
   it "should generate classes for each entry in the database.yml" do
@@ -114,6 +123,18 @@ describe MultiDb::ConnectionProxy do
     @proxy.master.retrieve_connection.should_receive(:insert).and_return(1)
     @proxy.insert(@sql)
   end
+
+  it 'should always use the master database for models configured as master models' do
+    MultiDb::SlaveDatabase2.retrieve_connection.should_receive(:select_all).once.and_return([])
+    MasterModel.connection.should == @proxy
+    MasterModel.first
+    
+    MultiDb::ConnectionProxy.master_models = ['MasterModel']
+    MasterModel.connection.should == @proxy.master.retrieve_connection
+    MultiDb::SlaveDatabase1.retrieve_connection.should_not_receive(:select_all)
+    MasterModel.retrieve_connection.should_receive(:select_all).once.and_return([])
+    MasterModel.first
+  end
   
 end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: schoefmax-multi_db
 version: !ruby/object:Gem::Version 
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors: 
 - "Maximilian Sch\xC3\xB6fmann"
@@ -28,11 +28,6 @@ executables: []
 extensions: []
 
 extra_rdoc_files: 
-- 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
 files: