seamless_database_pool 1.0.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2008 Brian Durand
+
+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

@@ -0,0 +1,79 @@
+Seamless Database Pool provides a simple way in which to add support for a master/slave database cluster to ActiveRecord to allow massive scalability and automatic failover. The guiding design principle behind this code is to make it absolutely trivial to add to an existing, complex application. That way when you have a big, nasty application which needs to scale the database you won't have to stop all feature development just to refactor your database connection code. Let's face it, when the database is having scaling problems, you are in for a world of hurt and the faster you can fix the problem the better.
+
+This code is available as both a Rails plugin and a gem so it will work with any ActiveRecord application.
+
+= Database Clusters
+
+In a master/slave cluster you have one master database server which uses replication to feed all changes to one or more slave databases which are set up to only handle reads. Since most applications put most of the load on the server with reads, this setup can scale out an application quite well. You'll need to work with your database of choice to get replication set up. This plugin has an connection adapter which will handle proxying database requests to the right server.
+
+= Simple Integration
+
+You can convert a standard Rails application (i.e. one that follows the scaffold conventions) to use a database cluster with three simple steps:
+
+1. Set up the database cluster (OK maybe this one isn't simple)
+2. Update database.yml settings to point to the servers in the cluster
+3. Add this code to ApplicationController:
+
+  include SeamlessDatabasePool::ControllerFilter
+  use_database_pool :all => :persistent, [:create, :update, :destroy] => :master
+
+If needed you can control how the connection pool is utilized by wrapping your code in some simple blocks.
+ 
+= Failover
+
+One of the other main advantages of using any sort of cluster is that one node can fail without bringing down your application. This plugin automatically handles failing over dead database connections in the read pool. That is if it tries to use a read connection and it is found to be inactive, the connector will try to reconnect. If that fails, it will try another connection in the read pool. After thirty seconds it will try to reconnect the dead connection again. One limitation on failover is that a server with an unreachable IP can't failover on startup. If you have a server completely die and it can't be restarted, you should update the pool configuration immediately to remove that entry.
+
+= Configuration
+
+== The pool configuration
+
+The cluster connections are configured in database.yml using the seamless_database_pool adapter. Any properties you configure for the connection will be inherited by all connections in the pool. In this way, you can configure ports, usernames, etc. once instead of for each connection. One exception is that you can set the pool_adapter property which each connection will inherit as the adapter property. Each connection in the pool uses all the same configuration properties as normal for the adapters.
+
+== The read pool
+
+The read pool is specified with a read_pool property in the pool connection definition in database.yml. This should be specified as an array of hashes where each hash is the configuration for each read connection you'd like to use (see below for an example). As noted above, the configuration for the entire pool will be merged in with the options for each connection.
+
+Each connection can be assigned an additional option of pool_weight. This value should be number which indicates the relative weight that the connection should be given in the pool. If no value is specified, it will default to one. Setting the value to zero will keep the connection out of the pool.
+
+If possible, you should set the permissions on the database user for the read connections to one that only has select permission. This can be especially useful in development and testing to ensure that the read connection never have writes sent to them.
+
+== The master connection
+
+The master connection is specified with a master_connection property in the pool connection definition in database.yml (see below for an example). The master connection will be used for all non-select statements against the database (i.e. insert, update, delete, etc.). It will also be used for all statements inside a transaction or any reload commands.
+
+By default, the master connection will be included in the read pool. If you would like to dedicate this connection only for write operations, you should set the pool weight to zero. Do not duplicate the master connection in the read pool as this will result in the additional overhead of two connections to the database.
+
+== Example configuration
+
+  development:
+    adapter: seamless_database_pool
+    database: mydb_development
+    username: read_user
+    password: abc123
+    pool_adapter: mysql
+    port: 3306
+    master:
+      host: master-db.example.com
+      port: 6000
+      username: master_user
+      password: 567pass
+    read_pool:
+      - host: read-db-1.example.com
+        pool_weight: 2
+      - host: read-db-2.example.com
+
+In this configuration, the master connection will be a mysql connection to master-db.example.com:6000 using the username master_user and the password 567pass.
+
+The read pool will use three mysql connections to master-db, read-db-1, and read-db-2. The master connection will use a different port, username, password for the connection. The read connections will use the same values. Further, the connection read-db-1 will get half the traffic as the other two connections, so presumably it's on a more powerful box.
+
+= Using the read pool
+
+By default, the master connection will be used for everything. This is not terribly useful, so you should really specify a method of using the read pool for the actions that need it. Read connections will only be used for select statements against the database.
+
+This is done with static methods on SeamlessDatabasePool.
+
+= Controller Filters
+
+To ease integration into a Ruby on Rails application, several controller filters are provided to invoke the above connection methods in a block. These are not implemented as standard controller filters so that the connection methods can be in effect for other filters.
+
+See SeamlessDatabasePool::ControllerFilter for more details.

data/Rakefile

@@ -0,0 +1,43 @@
+require 'rubygems'
+require 'rake'
+require 'rake/rdoctask'
+require 'rake/gempackagetask'
+require 'spec/rake/spectask'
+
+desc 'Default: run unit tests.'
+task :default => :test
+
+desc 'Test seamless_database_pool.'
+Spec::Rake::SpecTask.new(:test) do |t|
+  t.spec_files = 'spec/**/*_spec.rb'
+end
+
+desc 'Generate documentation for seamless_database_pool.'
+Rake::RDocTask.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.options << '--title' << 'Seamless Database Pool' << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  rdoc.rdoc_files.include('README')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+spec = Gem::Specification.new do |s| 
+  s.name = "seamless_database_pool"
+  s.version = "1.0.0"
+  s.author = "Brian Durand"
+  s.platform = Gem::Platform::RUBY
+  s.summary = "Support for master/slave database clusters in ActiveRecord"
+  s.files = FileList["lib/**/*", "init.rb", "MIT-LICENSE", 'Rakefile'].to_a
+  s.require_path = "lib"
+  s.test_files = FileList["{spec}/**/*_spec.rb"].to_a
+  s.has_rdoc = true
+  s.rdoc_options << '--title' << 'Seamless Database Pool' << '--line-numbers' << '--inline-source' << '--main' << 'README'
+  s.extra_rdoc_files = ["README"]
+  s.homepage = "http://seamlessdbpool.rubyforge.org"
+  s.rubyforge_project = "seamlessdbpool"
+  s.email = 'brian@embellishedvisions.com'
+  s.requirements = 'rspec 1.0.8 or higher is needed to run the tests'
+end
+ 
+Rake::GemPackageTask.new(spec) do |pkg| 
+  pkg.need_tar = true 
+end

data/init.rb

@@ -0,0 +1,2 @@
+require 'seamless_database_pool'
+

data/lib/active_record/connection_adapters/seamless_database_pool_adapter.rb

@@ -0,0 +1,302 @@
+require 'seamless_database_pool/connect_timeout'
+
+module ActiveRecord
+  class Base
+    def self.seamless_database_pool_connection (config)
+      pool_weights = {}
+      
+      default_config = {:pool_weight => 1}.merge(config.merge(:adapter => config[:pool_adapter]))
+      default_config.delete(:master)
+      default_config.delete(:read_pool)
+      default_config.delete(:pool_adapter)
+      
+      master_config = default_config.merge(config[:master].symbolize_keys)
+      establish_adapter(master_config[:adapter])
+      master_connection = send("#{master_config[:adapter]}_connection".to_sym, master_config)
+      master_connection.class.send(:include, SeamlessDatabasePool::ConnectTimeout) unless master_connection.class.include?(SeamlessDatabasePool::ConnectTimeout)
+      master_connection.connect_timeout = master_config[:connect_timeout]
+      pool_weights[master_connection] = master_config[:pool_weight].to_i if master_config[:pool_weight].to_i > 0
+      
+      read_connections = []
+      config[:read_pool].each do |read_config|
+        read_config = default_config.merge(read_config.symbolize_keys)
+        read_config[:pool_weight] = read_config[:pool_weight].to_i
+        if read_config[:pool_weight] > 0
+          establish_adapter(read_config[:adapter])
+          conn = send("#{read_config[:adapter]}_connection".to_sym, read_config)
+          conn.class.send(:include, SeamlessDatabasePool::ConnectTimeout) unless conn.class.include?(SeamlessDatabasePool::ConnectTimeout)
+          conn.connect_timeout = read_config[:connect_timeout]
+          read_connections << conn
+          pool_weights[conn] = read_config[:pool_weight]
+        end
+      end if config[:read_pool]
+      
+      ActiveRecord::ConnectionAdapters::SeamlessDatabasePoolAdapter.new(nil, logger, master_connection, read_connections, pool_weights)
+    end
+    
+    def self.establish_adapter (adapter)
+      unless adapter then raise AdapterNotSpecified, "database configuration does not specify adapter" end
+      raise AdapterNotFound, "database pool must specify adapters" if adapter == 'seamless_database_pool'
+      
+      begin
+        require 'rubygems'
+        gem "activerecord-#{adapter}-adapter"
+        require "active_record/connection_adapters/#{adapter}_adapter"
+      rescue LoadError
+        begin
+          require "active_record/connection_adapters/#{adapter}_adapter"
+        rescue LoadError
+          raise "Please install the #{adapter} adapter: `gem install activerecord-#{adapter}-adapter` (#{$!})"
+        end
+      end
+
+      adapter_method = "#{adapter}_connection"
+      if !respond_to?(adapter_method)
+        raise AdapterNotFound, "database configuration specifies nonexistent #{adapter} adapter"
+      end
+    end
+
+    # Force reload to use the master connection since it's probably being called for a reason.
+    def reload_with_seamless_database_pool (options = nil)
+      SeamlessDatabasePool.use_master_connection do
+        reload_without_seamless_database_pool(options)
+      end
+    end
+    alias_method_chain(:reload, :seamless_database_pool)
+  end
+  
+  module Associations
+    class AssociationProxy
+      # Force reload to use the master connection since it's probably being called for a reason.
+      def reload_with_seamless_database_pool
+        SeamlessDatabasePool.use_master_connection do
+          reload_without_seamless_database_pool
+        end
+      end
+      alias_method_chain(:reload, :seamless_database_pool)
+    end
+  end
+
+  module ConnectionAdapters
+    class SeamlessDatabasePoolAdapter < AbstractAdapter
+
+      READ_ONLY_METHODS = [:select_one, :select_all, :select_value, :select_values, :select_rows, :select]
+      CONNECTION_METHODS = [:adapter_name, :active?, :reconnect!, :disconnect!, :verify!, :reset_runtime]
+      
+      attr_reader :read_connections, :master_connection
+      
+      def initialize (connection, logger, master_connection, read_connections, pool_weights)
+        super(connection, logger)
+        
+        @master_connection = master_connection
+        @read_connections = read_connections.dup.freeze
+        
+        @weighted_read_connections = []
+        pool_weights.each_pair do |conn, weight|
+          weight.times{@weighted_read_connections << conn}
+        end
+        @available_read_connections = [AvailableConnections.new(@weighted_read_connections)]
+        
+        define_proxy_methods
+      end
+      
+      def adapter_name #:nodoc:
+        'Seamless Database Pool'
+      end
+      
+      # Returns an array of the master connection and the read pool connections
+      def all_connections
+        [@master_connection] + @read_connections
+      end
+      
+      # Get the pool weight of a connection
+      def pool_weight (connection)
+        return @weighted_read_connections.select{|conn| conn == connection}.size
+      end
+      
+      def active?
+        active = true
+        all_connections.each{|conn| active &= conn.active?}
+        return active
+      end
+      
+      def reconnect!
+        all_connections.each{|conn| conn.reconnect!}
+      end
+      
+      def disconnect!
+        all_connections.each{|conn| conn.disconnect!}
+      end
+      
+      def verify!(timeout)
+        all_connections.each{|conn| conn.verify!(timeout)}
+      end
+      
+      def reset_runtime
+        all_connections.inject(0.0){|total, conn| total += conn.reset_runtime}
+      end
+      
+      # Get a random read connection from the pool. If the connection is not active, it will attempt to reconnect
+      # to the database. If that fails, it will be removed from the pool for one minute.
+      def random_read_connection
+        weighted_read_connections = available_read_connections
+        if @use_master or weighted_read_connections.empty?
+          return master_connection
+        else
+          weighted_read_connections[rand(weighted_read_connections.length)]
+        end
+      end
+      
+      # Get the current read connection
+      def current_read_connection
+        return SeamlessDatabasePool.read_only_connection(self)
+      end
+      
+      def transaction(start_db_transaction = true)
+        use_master_connection do
+          master_connection.transaction(start_db_transaction) do
+            yield if block_given?
+          end
+        end
+      end
+
+      def using_master_connection?
+        !!@use_master
+      end
+      
+      # Force using the master connection in a block.
+      def use_master_connection
+        save_val = @use_master
+        begin
+          @use_master = true
+          yield if block_given?
+        ensure
+          @use_master = save_val
+        end
+      end
+      
+      class DatabaseConnectionError < StandardError
+        attr_accessor :wrapped_exception
+      end
+      
+      # This simple class puts an expire time on an array of connections. It is used so the a connection
+      # to a down database won't try to reconnect over and over.
+      class AvailableConnections
+        attr_reader :connections, :failed_connection
+        attr_writer :expires
+        
+        def initialize (connections, failed_connection = nil, expires = nil)
+          @connections = connections
+          @failed_connection = failed_connection
+          @expires = expires
+        end
+        
+        def expired?
+          @expires < Time.now if @expires
+        end
+        
+        def reconnect!
+          failed_connection.reconnect!
+          raise DatabaseConnectionError.new unless failed_connection.active?
+        end
+      end
+      
+      # Get the available weighted connections. When a connection is dead and cannot be reconnected, it will
+      # be temporarily removed from the read pool so we don't keep trying to reconnect to a database that isn't
+      # listening.
+      def available_read_connections
+        available = @available_read_connections.last
+        if available.expired?
+          begin
+            available.reconnect!
+          rescue
+            # Couldn't reconnect so try again in a little bit
+            available.expires = 30.seconds.from_now
+            return available.connections
+          end
+          @available_read_connections.pop
+          return available_read_connections
+        else
+          return available.connections
+        end
+      end
+      
+      # Temporarily remove a connection from the read pool.
+      def suppress_read_connection (conn, expire)
+        available = available_read_connections
+        connections = available.reject{|c| c == conn}
+        
+        # This wasn't a read connection so don't suppress it
+        return if connections.length == available.length
+        
+        if connections.empty?
+          # No connections available so we might as well try them all again
+          @available_read_connections.slice!(1, @available_read_connections.length)
+        else
+          # Available connections will now not include the suppressed connection for a while
+          @available_read_connections.push(AvailableConnections.new(connections, conn, expire.seconds.from_now))
+        end
+      end
+      
+      private
+      
+      def proxy_connection_method (connection, method, proxy_type, *args, &block)
+        begin
+          connection.send(method, *args, &block)
+        rescue => e
+          unless proxy_type == :retry or connection.active?
+            connection.reconnect! rescue nil
+            connection_error = DatabaseConnectionError.new
+            connection_error.wrapped_exception = e
+            raise connection_error
+          end
+          raise e
+        end
+      end
+      
+      # Define proxy methods to handle actual database work.
+      def define_proxy_methods
+        master_methods = master_connection.public_methods(false) + master_connection.protected_methods(false) + master_connection.private_methods(false)
+        master_methods -= READ_ONLY_METHODS
+        master_methods -= CONNECTION_METHODS
+        master_methods.delete(:transaction)
+        
+        master_methods.each do |method_name|
+          instance_eval(%Q(
+            def #{method_name}(*args, &block)
+              begin
+                proxy_connection_method(master_connection, :#{method_name}, :master, *args, &block)
+              rescue DatabaseConnectionError => e
+                raise e.wrapped_exception
+              end
+            end
+          ))
+        end
+        
+        READ_ONLY_METHODS.each do |method_name|
+          instance_eval(%Q(
+            def #{method_name}(*args, &block)
+              connection = current_read_connection
+              begin
+                proxy_connection_method(connection, :#{method_name}, :read, *args, &block)
+              rescue DatabaseConnectionError => e
+                unless block or using_master_connection?
+                  # Try again with a different connection if needed unless it could have a side effect
+                  unless connection.active?
+                    suppress_read_connection(connection, 30)
+                    connection = current_read_connection
+                    SeamlessDatabasePool.set_persistent_read_connection(self, connection)
+                  end
+                  proxy_connection_method(connection, :#{method_name}, :retry, *args, &block)
+                else
+                  raise e.wrapped_exception
+                end
+              end
+            end
+          ))
+        end
+      end
+      
+    end
+  end
+end