read_from_slave 0.3.0

data/README

@@ -0,0 +1,96 @@
+Read_from_slave
+
+Read_from_slave for Rails enables database reads from a slave database, while writes continue to go to the master
+
+Read_from_slave will work with Rails 2.2 and above.
+
+Installation
+
+sudo gem install sdsykes-read_from_slave
+
+Configuration
+
+In config/environments/production.rb (for instance)
+
+  config.gem "sdsykes-read_from_slave", :lib=>"read_from_slave"
+
+In config/database.yml
+
+  production:
+    adapter: mysql
+    database: mydatabase
+    username: myuser
+    password: mypassword
+    host: my.main.database.server.com
+    port: 3306
+
+  slave_for_mydatabase:
+    adapter: mysql
+    database: mydatabase
+    username: myuser
+    password: mypassword
+    socket: /var/lib/mysql/mysql.sock
+
+Just use the regular YAML format to specify your slave database, it could equally well be on
+another server as the local example given above.
+
+Phusion Passenger
+
+Note that if you are using Passenger, you need to make sure that the slave database is reconnected
+if there is any chance that it was accessed before the spawner forks.  This could be because
+database was accessed during the generation of routes, or perhaps if you are using the has_many_polymorphs
+gem.
+
+The safest thing to do is to have something like this in your production.rb or environment.rb:
+
+  PhusionPassenger.on_event(:starting_worker_process) do |forked|
+    if forked
+      # We're in smart spawning mode.                                                               
+      ActiveRecord::Base.establish_slave_connections
+    else
+      # We're in conservative spawning mode. We don't need to do anything.                          
+    end
+  end
+
+Documentation
+
+http://rdoc.info/projects/sdsykes/read_from_slave
+
+Tests
+
+Clone the git repository, and you can run the read_from_slave tests or entire ActiveRecord test suite to prove that read_from_slave works correctly.
+
+  $ rake test
+  ...snip..
+  Finished in 0.046365 seconds.
+  
+  7 tests, 7 assertions, 0 failures, 0 errors
+  
+  $ rake test_with_active_record
+  ...snip...
+  Finished in 51.904306 seconds.
+  
+  2057 tests, 6685 assertions, 0 failures, 0 errors
+
+Todo
+
+* Support a pool of multiple slaves
+
+References
+
+"Masochism":http://github.com/technoweenie/masochism/tree/master
+not thread safe
+won't work with apps that talk to multiple (master) databases
+
+"Acts as readonlyable":http://rubyforge.org/projects/acts-as-with-ro/
+old, not suitable for Rails 2.x
+
+"master_slave_adapter":http://github.com/mauricio/master_slave_adapter/tree/master
+similar to read_from_slave, but adapter based approach
+
+"multi_db":http://github.com/schoefmax/multi_db/tree/master
+another one, proxy connection approach
+looks like it won't work with apps that talk to multiple (master) databases
+more complex than read_from_slave
+
+(c) 2009 Stephen Sykes

data/README.textile

@@ -0,0 +1,114 @@
+h1. Read_from_slave
+
+h4. Read_from_slave for Rails enables database reads from a slave database, while writes continue to go to the master
+
+Read_from_slave will work with Rails 2.2 and above.
+
+h2. Installation
+
+<pre>
+<code>
+sudo gem install sdsykes-read_from_slave
+</code>
+</pre>
+
+h2. Configuration
+
+In config/environments/production.rb (for instance)
+
+<pre>
+<code>
+config.gem "sdsykes-read_from_slave", :lib=>"read_from_slave"
+</code>
+</pre>
+
+In config/database.yml
+
+<pre>
+<code>
+production:
+  adapter: mysql
+  database: mydatabase
+  username: myuser
+  password: mypassword
+  host: my.main.database.server.com
+  port: 3306
+
+slave_for_mydatabase:
+  adapter: mysql
+  database: mydatabase
+  username: myuser
+  password: mypassword
+  socket: /var/lib/mysql/mysql.sock
+</code>
+</pre>
+
+Just use the regular YAML format to specify your slave database, it could equally well be on
+another server as the local example given above.
+
+h2. Phusion Passenger
+
+Note that if you are using Passenger, you need to make sure that the slave database is reconnected
+if there is any chance that it was accessed before the spawner forks.  This could be because
+database was accessed during the generation of routes, or perhaps if you are using the has_many_polymorphs
+gem.
+
+The safest thing to do is to have something like this in your production.rb or environment.rb:
+
+<pre>
+<code>
+PhusionPassenger.on_event(:starting_worker_process) do |forked|
+  if forked
+    # We're in smart spawning mode.                                                               
+    ActiveRecord::Base.establish_slave_connections
+  else
+    # We're in conservative spawning mode. We don't need to do anything.                          
+  end
+end
+</code>
+</pre>
+
+h2. Documentation
+
+"http://rdoc.info/projects/sdsykes/read_from_slave":http://rdoc.info/projects/sdsykes/read_from_slave
+
+h2. Tests
+
+Clone the git repository, and you can run the read_from_slave tests or entire ActiveRecord test suite to prove that read_from_slave works correctly.
+
+<pre>
+<code>
+$ rake test
+...snip..
+Finished in 0.046365 seconds.
+
+7 tests, 7 assertions, 0 failures, 0 errors
+
+$ rake test_with_active_record
+...snip...
+Finished in 51.904306 seconds.
+
+2057 tests, 6685 assertions, 0 failures, 0 errors
+</code>
+</pre>
+
+h2. Todo
+
+* Support a pool of multiple slaves
+
+h2. References
+
+* "Masochism":http://github.com/technoweenie/masochism/tree/master
+** not thread safe
+** won't work with apps that talk to multiple (master) databases
+* "Acts as readonlyable":http://rubyforge.org/projects/acts-as-with-ro/
+** old, not suitable for Rails 2.x
+* "master_slave_adapter":http://github.com/mauricio/master_slave_adapter/tree/master
+** similar to read_from_slave, but adapter based approach
+* "multi_db":http://github.com/schoefmax/multi_db/tree/master
+** another one, proxy connection approach
+** looks like it won't work with apps that talk to multiple (master) databases
+** more complex than read_from_slave
+
+
+(c) 2009 Stephen Sykes

data/Rakefile

@@ -0,0 +1,38 @@
+require 'rake'
+require 'rake/testtask'
+require 'test/helper'
+
+task :default => [:test_read_from_slave]
+
+task :test => :default
+
+Rake::TestTask.new(:test_with_active_record) do |t|
+  t.libs << ReadFromSlave::ActiveRecordTest::AR_TEST_SUITE
+  t.libs << ReadFromSlave::ActiveRecordTest.connection
+  t.test_files = ReadFromSlave::ActiveRecordTest.test_files
+  t.ruby_opts = ["-r #{File.join(File.dirname(__FILE__), 'test', 'active_record_setup')}"]
+  t.verbose = true
+end
+
+Rake::TestTask.new(:test_read_from_slave) do |t|
+  t.libs << 'lib'
+  t.test_files = ReadFromSlave::Test.test_files
+  t.verbose = true
+end
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |s|
+    s.name = "read_from_slave"
+    s.summary = "Read_from_slave - Utilise your slave databases with rails"
+    s.email = "sdsykes@gmail.com"
+    s.homepage = "http://github.com/sdsykes/read_from_slave"
+    s.description = "Read_from_slave for Rails enables database reads from a slave database, while writes continue to go to the master"
+    s.authors = ["Stephen Sykes"]
+    s.files = FileList["[A-Z]*", "{lib,test}/**/*"]
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler not available. Install it with: sudo gem install technicalpickles-jeweler -s http://
+gems.github.com"
+end

data/VERSION.yml

@@ -0,0 +1,4 @@
+--- 
+:minor: 3
+:patch: 0
+:major: 0

data/lib/read_from_slave.rb

@@ -0,0 +1,151 @@
+# Read_from_slave for Rails enables database reads from a slave database, while writes continue 
+# to go to the master
+# To use read_from_slave you must install the gem, configure the gem in your environment file,
+# and setup your database.yml file with an entry for your slave database.
+#
+# === Configuration
+# In config/environments/production.rb (for instance)
+#
+#   config.gem "sdsykes-read_from_slave", :lib=>"read_from_slave"
+#
+# In config/database.yml  
+#
+#   production:
+#     adapter: mysql
+#     database: mydatabase
+#     username: myuser
+#     password: mypassword
+#     host: my.main.database.server.com
+#     port: 3306
+#
+#   slave_for_mydatabase:
+#     adapter: mysql
+#     database: mydatabase
+#     username: myuser
+#     password: mypassword
+#     socket: /var/lib/mysql/mysql.sock
+#
+# Note that if you have multiple databases you can also configure multiple slaves - use the
+# database name after slave_for_ in the configuration.
+#
+# === References
+# * "Masochism":http://github.com/technoweenie/masochism/tree/master
+# ** not thread safe
+# ** won't work with apps that talk to multiple (master) databases
+# * "Acts as readonlyable":http://rubyforge.org/projects/acts-as-with-ro/
+# ** old, not suitable for Rails 2.x
+# * "master_slave_adapter":http://github.com/mauricio/master_slave_adapter/tree/master
+# ** similar to read_from_slave, but adapter based approach
+# * "multi_db":http://github.com/schoefmax/multi_db/tree/master
+# ** another one, proxy connection approach
+# ** looks like it won't work with apps that talk to multiple (master) databases
+# ** more complex than read_from_slave
+#
+module ReadFromSlave
+  class << self
+    def install!
+      base = ActiveRecord::Base
+      base.send(:include, InstanceMethods)
+      base.alias_method_chain :reload, :read_from_slave
+      base.extend(SingletonMethods)
+      base.class_eval do
+        class << self
+          alias_method_chain :find_by_sql, :read_from_slave
+          alias_method_chain :connection, :read_from_slave
+        end
+      end
+    end
+  end
+
+  module InstanceMethods
+    def reload_with_read_from_slave(options = nil)
+      Thread.current[:read_from_slave] = :reload
+      reload_without_read_from_slave(options)
+    end
+  end
+
+  module SingletonMethods
+
+    @@slave_models = {}
+
+    def find_by_sql_with_read_from_slave(sql)
+      Thread.current[:read_from_slave] = (Thread.current[:read_from_slave] != :reload)
+      find_by_sql_without_read_from_slave(sql)
+    ensure
+      Thread.current[:read_from_slave] = false
+    end
+
+    def connection_with_read_from_slave
+      normal_connection = connection_without_read_from_slave
+      if Thread.current[:read_from_slave] && normal_connection.open_transactions == 0
+        Thread.current[:read_from_slave_uses] = :slave  # for testing use
+        slave_connection
+      else
+        Thread.current[:read_from_slave_uses] = :master
+        normal_connection
+      end
+    end
+
+    # Returns a connection to the slave database, or to the regular database if                     
+    # no slave is configured                                                                        
+    #                                                                                               
+    def slave_connection
+      (@slave_model || slave_model).connection_without_read_from_slave
+    end
+
+
+    # Returns an AR model class that has a connection to the appropriate slave db                   
+    #                                                                                               
+    def slave_model
+      db_name = master_database_name
+      if slave_config_for(db_name)
+        unless @@slave_models[db_name]
+          slave_model_name = "ReadFromSlaveFor_#{db_name}"
+          @@slave_models[db_name] = eval %{
+            class #{slave_model_name} < ActiveRecord::Base
+              self.abstract_class = true
+              establish_slave_connection_for('#{db_name}')
+            end
+            #{slave_model_name}
+          }
+        end
+        @slave_model = @@slave_models[db_name]
+      else
+        @slave_model = self
+      end
+    end
+
+    # Returns the name of the database in use, as given in the database.yml file                    
+    #                                                                                               
+    def master_database_name
+      connection_without_read_from_slave.instance_variable_get(:@config)[:database]
+    end
+
+    # Returns the config for the associated slave database for this master, 
+    # as given in the database.yml file                    
+    #                                                                                               
+    def slave_config_for(master)
+      configurations["slave_for_#{master}"]
+    end
+
+    # Establishes a connection to the slave database that is configured for                         
+    # the database name provided                                                                    
+    #                                       
+    def establish_slave_connection_for(master)
+      conn_spec = slave_config_for(master)
+      establish_connection(conn_spec) if conn_spec
+    end
+
+    # Re-establishes connections to all the slave databases that
+    # have been used so far.  Use this in your 
+    # PhusionPassenger.on_event(:starting_worker_process) block if required.
+    #
+    def establish_slave_connections
+      @@slave_models.each do |db_name, model|
+        model.establish_slave_connection_for(db_name)
+      end
+    end
+  end
+end
+
+ReadFromSlave.install!

data/test/active_record_setup.rb

@@ -0,0 +1,3 @@
+require File.join(File.dirname(__FILE__), 'helper')
+
+ReadFromSlave::ActiveRecordTest.setup

data/test/helper.rb

@@ -0,0 +1,96 @@
+require File.join(File.dirname(__FILE__), 'setup')
+require 'active_support/test_case'
+
+module ReadFromSlave
+  class Test
+    class << self
+
+      def setup
+        setup_constants
+        make_sqlite_config
+        make_sqlite_connection
+        load_models
+        load(SCHEMA_ROOT + "/schema.rb")
+        require 'test/unit'
+      end
+
+      def test_files
+        glob("#{File.dirname(__FILE__)}/**/*_test.rb")
+      end
+
+      def test_model_files
+        %w{course}
+      end
+
+      private
+
+      def setup_constants
+        set_constant('TEST_ROOT') {File.expand_path(File.dirname(__FILE__))}
+        set_constant('SCHEMA_ROOT') {TEST_ROOT + "/schema"}
+      end
+      
+      def make_sqlite_config
+        ActiveRecord::Base.configurations = {
+          'rfs' => {
+            :adapter => 'sqlite3',
+            :database => 'test_db',
+            :timeout => 5000
+          },
+          'slave_for_test_db' => {
+            :adapter => 'sqlite3',
+            :database => 'test_db',
+            :timeout => 5000
+          }
+        }
+      end
+      
+      def load_models
+        test_model_files.each {|f| require File.join(File.dirname(__FILE__), "models", f)}
+      end
+
+      def make_sqlite_connection
+        ActiveRecord::Base.establish_connection(ActiveRecord::Base.configurations['rfs'])
+      end
+      
+      def set_constant(constant)
+        Object.const_set(constant, yield) unless Object.const_defined?(constant)
+      end
+      
+      def glob(pattern)
+        Dir.glob(pattern)
+      end
+    end
+  end
+  
+  class ActiveRecordTest < Test
+    class << self
+      def setup
+        setup_constants
+      end
+      
+      def test_files
+        glob("#{AR_TEST_SUITE}/cases/**/*_test.rb").sort
+      end
+
+      def connection
+        File.join(AR_TEST_SUITE, 'connections', 'native_mysql')
+      end
+
+      private
+
+      def setup_constants
+        set_constant('MYSQL_DB_USER') {'rails'}
+        set_constant('AR_TEST_SUITE') {find_active_record_test_suite}
+      end
+ 
+      def find_active_record_test_suite
+        ts = ($:).grep(/activerecord/).last.split('/')
+        ts.pop
+        ts << 'test'
+        ts.join('/')
+      end
+    end
+
+    AR_TEST_SUITE = find_active_record_test_suite
+  end
+end

data/test/models/course.rb

@@ -0,0 +1,2 @@
+class Course < ActiveRecord::Base
+end

data/test/read_from_slave_test.rb

@@ -0,0 +1,45 @@
+require File.join(File.dirname(__FILE__), "helper")
+
+ReadFromSlave::Test.setup
+
+class ReadFromSlaveTest < ActiveSupport::TestCase
+  test "slave connection should be different from normal connection" do
+    assert_not_equal Course.connection_without_read_from_slave, Course.slave_connection
+  end
+
+  test "should be able to write and read from database" do
+    Course.create(:name=>"Saw playing")
+    x = Course.find(:first)
+    assert_equal "Saw playing", x.name
+  end
+
+  test "should write to master" do
+    Course.create(:name=>"Saw playing")
+    assert_equal :master, Thread.current[:read_from_slave_uses]
+  end
+
+  test "should read from slave" do
+    Course.create(:name=>"Saw playing")
+    x = Course.find(:first)
+    assert_equal :slave, Thread.current[:read_from_slave_uses]
+  end
+
+  test "should reload from master" do
+    Course.create(:name=>"Saw playing")
+    x = Course.find(:first)
+    x.reload
+    assert_equal :master, Thread.current[:read_from_slave_uses]
+  end
+
+  test "should get new slave connection when calling establish_slave_connections" do
+    conn = Course.slave_connection
+    ActiveRecord::Base.establish_slave_connections
+    assert_not_equal conn, Course.slave_connection
+  end
+
+  test "should not get new master connection when calling establish_slave_connections" do
+    conn = Course.connection_without_read_from_slave
+    ActiveRecord::Base.establish_slave_connections
+    assert_equal conn, Course.connection_without_read_from_slave
+  end
+end

data/test/schema/schema.rb

@@ -0,0 +1,5 @@
+ActiveRecord::Schema.define do
+  create_table :courses, :force => true do |t|
+    t.column :name, :string, :null => false
+  end
+end

data/test/setup.rb

@@ -0,0 +1,3 @@
+require 'rubygems'
+require 'activerecord'
+require File.join(File.dirname(__FILE__), '..', 'lib', 'read_from_slave')

data/test/test.rb

@@ -0,0 +1 @@
+# todo

metadata

@@ -0,0 +1,73 @@
+--- !ruby/object:Gem::Specification 
+name: read_from_slave
+version: !ruby/object:Gem::Version 
+  version: 0.3.0
+platform: ruby
+authors: 
+- Stephen Sykes
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-10-10 00:00:00 +03:00
+default_executable: 
+dependencies: []
+
+description: Read_from_slave for Rails enables database reads from a slave database, while writes continue to go to the master
+email: sdsykes@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+- README.textile
+files: 
+- README
+- README.textile
+- Rakefile
+- VERSION.yml
+- lib/read_from_slave.rb
+- test/active_record_setup.rb
+- test/helper.rb
+- test/models/course.rb
+- test/read_from_slave_test.rb
+- test/schema/schema.rb
+- test/setup.rb
+- test/test.rb
+has_rdoc: true
+homepage: http://github.com/sdsykes/read_from_slave
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+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: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Read_from_slave - Utilise your slave databases with rails
+test_files: 
+- test/active_record_setup.rb
+- test/helper.rb
+- test/models/course.rb
+- test/read_from_slave_test.rb
+- test/schema/schema.rb
+- test/setup.rb
+- test/test.rb