seamless_database_pool 1.0.0

data/lib/seamless_database_pool.rb

@@ -0,0 +1,108 @@
+# This module allows setting the read pool connection type. Generally you will use one of
+#
+#   - use_random_read_connection
+#   - use_persistent_read_connection
+#   - use_master_connection
+#
+# Each of these methods can take an optional block. If they are called with a block, they
+# will set the read connection type only within the block. Otherwise they will set the default
+# read connection type. If none is ever called, the read connection type will be :master.
+
+module SeamlessDatabasePool
+
+  READ_CONNECTION_METHODS = [:master, :persistent, :random]
+
+  # Call this method to use a random connection from the read pool for every select statement.
+  # This method is good if your replication is very fast. Otherwise there is a chance you could
+  # get inconsistent results from one request to the next. This can result in mysterious failures
+  # if your code selects a value in one statement and then uses in another statement. You can wind
+  # up trying to use a value from one server that hasn't been replicated to another one yet.
+  # This method is best if you have few processes which generate a lot of queries and you have
+  # fast replication.
+  def self.use_random_read_connection
+    if block_given?
+      set_read_only_connection_type(:random){yield}
+    else
+      Thread.current[:read_only_connection] = :random
+    end
+  end
+  
+  # Call this method to pick a random connection from the read pool and use it for all subsequent
+  # select statements. This provides consistency from one select statement to the next. This
+  # method should always be called with a block otherwise you can end up with an imbalanced read
+  # pool. This method is best if you have lots of processes which have a relatively few select
+  # statements or a slow replication mechanism. Generally this is the best method to use for web
+  # applications.
+  def self.use_persistent_read_connection
+    if block_given?
+      set_read_only_connection_type(:persistent){yield}
+    else
+      Thread.current[:read_only_connection] = {}
+    end
+  end
+  
+  # Call this method to use the master connection for all subsequent select statements. This
+  # method is most useful when you are doing lots of updates since it guarantees consistency
+  # if you do a select immediately after an update or insert.
+  #
+  # The master connection will also be used for selects inside any transaction blocks. It will
+  # also be used if you pass :readonly => false to any ActiveRecord.find method.
+  def self.use_master_connection
+    if block_given?
+      set_read_only_connection_type(:master){yield}
+    else
+      Thread.current[:read_only_connection] = :master
+    end
+  end
+  
+  # Set the read only connection type to either :master, :random, or :persistent.
+  def self.set_read_only_connection_type (connection_type)
+    saved_connection = Thread.current[:read_only_connection]
+    retval = nil
+    begin
+      connection_type = {} if connection_type == :persistent
+      Thread.current[:read_only_connection] = connection_type
+      retval = yield if block_given?
+    ensure
+      Thread.current[:read_only_connection] = saved_connection
+    end
+    return retval
+  end
+  
+  # Get the read only connection type currently in use. Will be one of :master, :random, or :persistent.
+  def self.read_only_connection_type (default = :master)
+    connection_type = Thread.current[:read_only_connection] || default
+    connection_type = :persistent if connection_type.kind_of?(Hash)
+    return connection_type
+  end
+  
+  # Get a read only connection from a connection pool.
+  def self.read_only_connection (pool_connection)
+    return pool_connection.master_connection if pool_connection.using_master_connection?
+    connection_type = Thread.current[:read_only_connection]
+    
+    if connection_type.kind_of?(Hash)
+      connection = connection_type[pool_connection]
+      unless connection
+        connection = pool_connection.random_read_connection
+        connection_type[pool_connection] = connection
+      end
+      return connection
+    elsif connection_type == :random
+      return pool_connection.random_read_connection
+    else
+      return pool_connection.master_connection
+    end
+  end
+  
+  # This method is provided as a way to change the persistent connection when it fails and a new one is substituted.
+  def self.set_persistent_read_connection (pool_connection, read_connection)
+    connection_type = Thread.current[:read_only_connection]
+    connection_type[pool_connection] = read_connection if connection_type.kind_of?(Hash)
+  end
+  
+  def self.clear_read_only_connection
+    Thread.current[:read_only_connection] = nil
+  end
+  
+end

data/lib/seamless_database_pool/connect_timeout.rb

@@ -0,0 +1,22 @@
+module SeamlessDatabasePool
+  # This module is mixed into connection adapters to allow the reconnect! method to timeout if the
+  # IP address becomes unreachable. The default timeout is 1 second, but you can change it by setting
+  # the connect_timeout parameter in the adapter configuration.
+  module ConnectTimeout
+    attr_accessor :connect_timeout
+    
+    def self.included (base)
+      base.alias_method_chain :reconnect!, :connect_timeout
+    end
+    
+    def reconnect_with_connect_timeout!
+      begin
+        timeout(connect_timeout || 1) do
+          reconnect_without_connect_timeout!
+        end
+      rescue TimeoutError
+        raise "reconnect timed out"
+      end
+    end
+  end
+end

data/lib/seamless_database_pool/connection_statistics.rb

@@ -0,0 +1,63 @@
+module SeamlessDatabasePool
+  # This module is included for testing. Mix it into each of your database pool connections
+  # and it will keep track of how often each connection calls update, insert, execute,
+  # or select.
+  module ConnectionStatistics
+    def self.included (base)
+      base.alias_method_chain(:update, :connection_statistics)
+      base.alias_method_chain(:insert, :connection_statistics)
+      base.alias_method_chain(:execute, :connection_statistics)
+      base.alias_method_chain(:select, :connection_statistics)
+    end
+  
+    # Get the connection statistics
+    def connection_statistics
+      @connection_statistics ||= {}
+    end
+    
+    def reset_connection_statistics
+      @connection_statistics = {}
+    end
+  
+    def update_with_connection_statistics (sql, name = nil)
+      increment_connection_statistic(:update) do
+        update_without_connection_statistics(sql, name)
+      end
+    end
+  
+    def insert_with_connection_statistics (sql, name = nil)
+      increment_connection_statistic(:insert) do
+        insert_without_connection_statistics(sql, name)
+      end
+    end
+  
+    def execute_with_connection_statistics (sql, name = nil)
+      increment_connection_statistic(:execute) do
+        execute_without_connection_statistics(sql, name)
+      end
+    end
+  
+    protected
+  
+    def select_with_connection_statistics (sql, name = nil)
+      increment_connection_statistic(:select) do
+        select_without_connection_statistics(sql, name)
+      end
+    end
+  
+    def increment_connection_statistic (method)
+      if @counting_pool_statistics
+        yield
+      else
+        begin
+          @counting_pool_statistics = true
+          stat = connection_statistics[method] || 0
+          @connection_statistics[method] = stat + 1
+          yield
+        ensure
+          @counting_pool_statistics = false
+        end
+      end
+    end
+  end
+end

data/lib/seamless_database_pool/controller_filter.rb

@@ -0,0 +1,91 @@
+module SeamlessDatabasePool
+  # This module provides a simple method of declaring which read pool connection type should
+  # be used for various ActionController actions. To use it, you must first mix it into
+  # you controller and then call use_database_pool to configure the connection types. Generally
+  # you should just do this in ApplicationController and call use_database_pool in your controllers
+  # when you need different connection types.
+  #
+  # Example:
+  # 
+  #   ApplicationController < ActionController::Base
+  #     include SeamlessDatabasePool
+  #     use_database_pool :all => :persistent, [:save, :delete] => :master
+  #     ...
+  
+  module ControllerFilter    
+    def self.included (base)
+      unless base.respond_to?(:use_database_pool)
+        base.extend(ClassMethods)
+        base.class_eval do
+          alias_method_chain :perform_action, :seamless_database_pool
+          alias_method_chain :redirect_to, :seamless_database_pool
+        end
+      end
+    end
+    
+    module ClassMethods
+      
+      def seamless_database_pool_options
+        return @seamless_database_pool_options if @seamless_database_pool_options
+        @seamless_database_pool_options = superclass.seamless_database_pool_options.dup if superclass.respond_to?(:seamless_database_pool_options)
+        @seamless_database_pool_options ||= {}
+      end
+      
+      # Call this method to set up the connection types that will be used for your actions.
+      # The configuration is given as a hash where the key is the action name and the value is
+      # the connection type (:master, :persistent, or :random). You can specify :all as the action
+      # to define a default connection type. You can also specify the action names in an array
+      # to easily map multiple actions to one connection type.
+      #
+      # The configuration is inherited from parent controller classes, so if you have default
+      # behavior, you should simply specify it in ApplicationController to have it available
+      # globally.
+      def use_database_pool (options)
+        remapped_options = seamless_database_pool_options
+        options.each_pair do |actions, connection_method|
+          unless SeamlessDatabasePool::READ_CONNECTION_METHODS.include?(connection_method)
+            raise "Invalid read pool method: #{connection_method}; should be one of #{SeamlessDatabasePool::READ_CONNECTION_METHODS.inspect}"
+          end
+          actions = [actions] unless actions.kind_of?(Array)
+          actions.each do |action|
+            remapped_options[action.to_sym] = connection_method
+          end
+        end
+        @seamless_database_pool_options = remapped_options
+      end
+    end
+    
+    # Force the master connection to be used on the next request. This is very useful for the Post-Redirect pattern
+    # where you post a request to your save action and then redirect the user back to the edit action. By calling
+    # this method, you won't have to worry if the replication engine is slower than the redirect. Normally you
+    # won't need to call this method yourself as it is automatically called when you perform a redirect from within
+    # a master connection block. It is made available just in case you have special needs that don't quite fit
+    # into this module's default logic.
+    def use_master_db_connection_on_next_request
+      session[:next_request_db_connection] = :master if session
+    end
+    
+    def seamless_database_pool_options
+      self.class.seamless_database_pool_options
+    end
+    
+    def perform_action_with_seamless_database_pool
+      read_pool_method = session.delete(:next_request_db_connection) if session
+      read_pool_method ||= seamless_database_pool_options[action_name.to_sym] || seamless_database_pool_options[:all]
+      if read_pool_method
+        SeamlessDatabasePool.set_read_only_connection_type(read_pool_method) do
+          perform_action_without_seamless_database_pool
+        end
+      else
+        perform_action_without_seamless_database_pool
+      end
+    end
+    
+    def redirect_to_with_seamless_database_pool (options = {}, response_status = {})
+      if SeamlessDatabasePool.read_only_connection_type(nil) == :master
+        use_master_db_connection_on_next_request
+      end
+      redirect_to_without_seamless_database_pool(options, response_status)
+    end
+  end
+end

data/spec/connection_statistics_spec.rb

@@ -0,0 +1,77 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'spec_helper'))
+
+describe "SeamlessDatabasePool::ConnectionStatistics" do
+  
+  module SeamlessDatabasePool
+    class ConnectionStatisticsTester
+      def insert (sql, name = nil)
+        "INSERT #{sql}/#{name}"
+      end
+      
+      def update (sql, name = nil)
+        execute(sql)
+        "UPDATE #{sql}/#{name}"
+      end
+      
+      def execute (sql, name = nil)
+        "EXECUTE #{sql}/#{name}"
+      end
+      
+      protected
+      
+      def select (sql, name = nil)
+        "SELECT #{sql}/#{name}"
+      end
+      
+      include ConnectionStatistics
+    end
+  end
+  
+  it "should increment statistics on update" do
+    connection = SeamlessDatabasePool::ConnectionStatisticsTester.new
+    connection.update('SQL', 'name').should == "UPDATE SQL/name"
+    connection.connection_statistics.should == {:update => 1}
+    connection.update('SQL 2').should == "UPDATE SQL 2/"
+    connection.connection_statistics.should == {:update => 2}
+  end
+  
+  it "should increment statistics on insert" do
+    connection = SeamlessDatabasePool::ConnectionStatisticsTester.new
+    connection.insert('SQL', 'name').should == "INSERT SQL/name"
+    connection.connection_statistics.should == {:insert => 1}
+    connection.insert('SQL 2').should == "INSERT SQL 2/"
+    connection.connection_statistics.should == {:insert => 2}
+  end
+  
+  it "should increment statistics on execute" do
+    connection = SeamlessDatabasePool::ConnectionStatisticsTester.new
+    connection.execute('SQL', 'name').should == "EXECUTE SQL/name"
+    connection.connection_statistics.should == {:execute => 1}
+    connection.execute('SQL 2').should == "EXECUTE SQL 2/"
+    connection.connection_statistics.should == {:execute => 2}
+  end
+  
+  it "should increment statistics on select" do
+    connection = SeamlessDatabasePool::ConnectionStatisticsTester.new
+    connection.send(:select, 'SQL', 'name').should == "SELECT SQL/name"
+    connection.connection_statistics.should == {:select => 1}
+    connection.send(:select, 'SQL 2').should == "SELECT SQL 2/"
+    connection.connection_statistics.should == {:select => 2}
+  end
+  
+  it "should increment counts only once within a block" do
+    connection = SeamlessDatabasePool::ConnectionStatisticsTester.new
+    connection.should_receive(:execute).with('SQL')
+    connection.update('SQL')
+    connection.connection_statistics.should == {:update => 1}
+  end
+  
+  it "should be able to clear the statistics" do
+    connection = SeamlessDatabasePool::ConnectionStatisticsTester.new
+    connection.update('SQL')
+    connection.connection_statistics.should == {:update => 1}
+    connection.reset_connection_statistics
+    connection.connection_statistics.should == {}
+  end
+  
+end

data/spec/filter_spec.rb

@@ -0,0 +1,134 @@
+require File.expand_path(File.join(File.dirname(__FILE__), 'spec_helper'))
+
+describe "SeamlessDatabasePool::ControllerFilter" do
+  
+  module SeamlessDatabasePool
+    class TestApplicationController
+      attr_reader :action_name, :session
+      
+      def initialize(action, session = {})
+        @action_name = action
+        @session = session
+      end
+      
+      def perform_action
+        send action_name
+      end
+      
+      def redirect_to (options = {}, response_status = {})
+        options
+      end
+      
+      def base_action
+        SeamlessDatabasePool.read_only_connection_type
+      end
+    end
+    
+    class TestBaseController < TestApplicationController
+      include SeamlessDatabasePool::ControllerFilter
+
+      use_database_pool :read => :persistent
+      
+      def read
+        SeamlessDatabasePool.read_only_connection_type
+      end
+      
+      def other
+        SeamlessDatabasePool.read_only_connection_type
+      end
+    end
+    
+    class TestOtherController < TestBaseController
+      use_database_pool :all => :random, [:edit, :save, :redirect_master_action] => :master
+      
+      def edit
+        SeamlessDatabasePool.read_only_connection_type
+      end
+
+      def save
+        SeamlessDatabasePool.read_only_connection_type
+      end
+      
+      def redirect_master_action
+        redirect_to(:action => :read)
+      end
+      
+      def redirect_read_action
+        redirect_to(:action => :read)
+      end
+    end
+  end
+  
+  it "should work with nothing set" do
+    controller = SeamlessDatabasePool::TestApplicationController.new('base_action')
+    controller.perform_action.should == :master
+  end
+  
+  it "should allow setting a connection type for a single action" do
+    controller = SeamlessDatabasePool::TestBaseController.new('read')
+    controller.perform_action.should == :persistent
+  end
+  
+  it "should allow setting a connection type for actions" do
+    controller = SeamlessDatabasePool::TestOtherController.new('edit')
+    controller.perform_action.should == :master
+    controller = SeamlessDatabasePool::TestOtherController.new('save')
+    controller.perform_action.should == :master
+  end
+  
+  it "should allow setting a connection type for all actions" do
+    controller = SeamlessDatabasePool::TestOtherController.new('other')
+    controller.perform_action.should == :random
+  end
+  
+  it "should inherit the superclass' options" do
+    controller = SeamlessDatabasePool::TestOtherController.new('read')
+    controller.perform_action.should == :persistent
+  end
+  
+  it "should be able to force using the master connection on the next request" do
+    session = {}
+    
+    # First request
+    controller = SeamlessDatabasePool::TestOtherController.new('read', session)
+    controller.perform_action.should == :persistent
+    controller.use_master_db_connection_on_next_request
+    
+    # Second request
+    controller = SeamlessDatabasePool::TestOtherController.new('read', session)
+    controller.perform_action.should == :master
+    
+    # Third request
+    controller = SeamlessDatabasePool::TestOtherController.new('read', session)
+    controller.perform_action.should == :persistent
+  end
+  
+  it "should not break trying to force the master connection if sessions are not enabled" do
+    controller = SeamlessDatabasePool::TestOtherController.new('read', nil)
+    controller.perform_action.should == :persistent
+    controller.use_master_db_connection_on_next_request
+    
+    # Second request
+    controller = SeamlessDatabasePool::TestOtherController.new('read', nil)
+    controller.perform_action.should == :persistent
+  end
+  
+  it "should force the master connection on the next request for a redirect in master connection block" do
+    session = {}
+    controller = SeamlessDatabasePool::TestOtherController.new('redirect_master_action', session)
+    controller.perform_action.should == {:action => :read}
+    
+    controller = SeamlessDatabasePool::TestOtherController.new('read', session)
+    controller.perform_action.should == :master
+  end
+
+  it "should not force the master connection on the next request for a redirect not in master connection block" do
+    session = {}
+    controller = SeamlessDatabasePool::TestOtherController.new('redirect_read_action', session)
+    controller.perform_action.should == {:action => :read}
+    
+    controller = SeamlessDatabasePool::TestOtherController.new('read', session)
+    controller.perform_action.should == :persistent
+  end
+  
+end