activerecord 4.2.0

data/lib/active_record/callbacks.rb

@@ -0,0 +1,313 @@
+module ActiveRecord
+  # = Active Record Callbacks
+  #
+  # Callbacks are hooks into the life cycle of an Active Record object that allow you to trigger logic
+  # before or after an alteration of the object state. This can be used to make sure that associated and
+  # dependent objects are deleted when +destroy+ is called (by overwriting +before_destroy+) or to massage attributes
+  # before they're validated (by overwriting +before_validation+). As an example of the callbacks initiated, consider
+  # the <tt>Base#save</tt> call for a new record:
+  #
+  # * (-) <tt>save</tt>
+  # * (-) <tt>valid</tt>
+  # * (1) <tt>before_validation</tt>
+  # * (-) <tt>validate</tt>
+  # * (2) <tt>after_validation</tt>
+  # * (3) <tt>before_save</tt>
+  # * (4) <tt>before_create</tt>
+  # * (-) <tt>create</tt>
+  # * (5) <tt>after_create</tt>
+  # * (6) <tt>after_save</tt>
+  # * (7) <tt>after_commit</tt>
+  #
+  # Also, an <tt>after_rollback</tt> callback can be configured to be triggered whenever a rollback is issued.
+  # Check out <tt>ActiveRecord::Transactions</tt> for more details about <tt>after_commit</tt> and
+  # <tt>after_rollback</tt>.
+  #
+  # Additionally, an <tt>after_touch</tt> callback is triggered whenever an
+  # object is touched.
+  #
+  # Lastly an <tt>after_find</tt> and <tt>after_initialize</tt> callback is triggered for each object that
+  # is found and instantiated by a finder, with <tt>after_initialize</tt> being triggered after new objects
+  # are instantiated as well.
+  #
+  # There are nineteen callbacks in total, which give you immense power to react and prepare for each state in the
+  # Active Record life cycle. The sequence for calling <tt>Base#save</tt> for an existing record is similar,
+  # except that each <tt>_create</tt> callback is replaced by the corresponding <tt>_update</tt> callback.
+  #
+  # Examples:
+  #   class CreditCard < ActiveRecord::Base
+  #     # Strip everything but digits, so the user can specify "555 234 34" or
+  #     # "5552-3434" and both will mean "55523434"
+  #     before_validation(on: :create) do
+  #       self.number = number.gsub(/[^0-9]/, "") if attribute_present?("number")
+  #     end
+  #   end
+  #
+  #   class Subscription < ActiveRecord::Base
+  #     before_create :record_signup
+  #
+  #     private
+  #       def record_signup
+  #         self.signed_up_on = Date.today
+  #       end
+  #   end
+  #
+  #   class Firm < ActiveRecord::Base
+  #     # Destroys the associated clients and people when the firm is destroyed
+  #     before_destroy { |record| Person.destroy_all "firm_id = #{record.id}"   }
+  #     before_destroy { |record| Client.destroy_all "client_of = #{record.id}" }
+  #   end
+  #
+  # == Inheritable callback queues
+  #
+  # Besides the overwritable callback methods, it's also possible to register callbacks through the
+  # use of the callback macros. Their main advantage is that the macros add behavior into a callback
+  # queue that is kept intact down through an inheritance hierarchy.
+  #
+  #   class Topic < ActiveRecord::Base
+  #     before_destroy :destroy_author
+  #   end
+  #
+  #   class Reply < Topic
+  #     before_destroy :destroy_readers
+  #   end
+  #
+  # Now, when <tt>Topic#destroy</tt> is run only +destroy_author+ is called. When <tt>Reply#destroy</tt> is
+  # run, both +destroy_author+ and +destroy_readers+ are called. Contrast this to the following situation
+  # where the +before_destroy+ method is overridden:
+  #
+  #   class Topic < ActiveRecord::Base
+  #     def before_destroy() destroy_author end
+  #   end
+  #
+  #   class Reply < Topic
+  #     def before_destroy() destroy_readers end
+  #   end
+  #
+  # In that case, <tt>Reply#destroy</tt> would only run +destroy_readers+ and _not_ +destroy_author+.
+  # So, use the callback macros when you want to ensure that a certain callback is called for the entire
+  # hierarchy, and use the regular overwritable methods when you want to leave it up to each descendant
+  # to decide whether they want to call +super+ and trigger the inherited callbacks.
+  #
+  # *IMPORTANT:* In order for inheritance to work for the callback queues, you must specify the
+  # callbacks before specifying the associations. Otherwise, you might trigger the loading of a
+  # child before the parent has registered the callbacks and they won't be inherited.
+  #
+  # == Types of callbacks
+  #
+  # There are four types of callbacks accepted by the callback macros: Method references (symbol), callback objects,
+  # inline methods (using a proc), and inline eval methods (using a string). Method references and callback objects
+  # are the recommended approaches, inline methods using a proc are sometimes appropriate (such as for
+  # creating mix-ins), and inline eval methods are deprecated.
+  #
+  # The method reference callbacks work by specifying a protected or private method available in the object, like this:
+  #
+  #   class Topic < ActiveRecord::Base
+  #     before_destroy :delete_parents
+  #
+  #     private
+  #       def delete_parents
+  #         self.class.delete_all "parent_id = #{id}"
+  #       end
+  #   end
+  #
+  # The callback objects have methods named after the callback called with the record as the only parameter, such as:
+  #
+  #   class BankAccount < ActiveRecord::Base
+  #     before_save      EncryptionWrapper.new
+  #     after_save       EncryptionWrapper.new
+  #     after_initialize EncryptionWrapper.new
+  #   end
+  #
+  #   class EncryptionWrapper
+  #     def before_save(record)
+  #       record.credit_card_number = encrypt(record.credit_card_number)
+  #     end
+  #
+  #     def after_save(record)
+  #       record.credit_card_number = decrypt(record.credit_card_number)
+  #     end
+  #
+  #     alias_method :after_initialize, :after_save
+  #
+  #     private
+  #       def encrypt(value)
+  #         # Secrecy is committed
+  #       end
+  #
+  #       def decrypt(value)
+  #         # Secrecy is unveiled
+  #       end
+  #   end
+  #
+  # So you specify the object you want messaged on a given callback. When that callback is triggered, the object has
+  # a method by the name of the callback messaged. You can make these callbacks more flexible by passing in other
+  # initialization data such as the name of the attribute to work with:
+  #
+  #   class BankAccount < ActiveRecord::Base
+  #     before_save      EncryptionWrapper.new("credit_card_number")
+  #     after_save       EncryptionWrapper.new("credit_card_number")
+  #     after_initialize EncryptionWrapper.new("credit_card_number")
+  #   end
+  #
+  #   class EncryptionWrapper
+  #     def initialize(attribute)
+  #       @attribute = attribute
+  #     end
+  #
+  #     def before_save(record)
+  #       record.send("#{@attribute}=", encrypt(record.send("#{@attribute}")))
+  #     end
+  #
+  #     def after_save(record)
+  #       record.send("#{@attribute}=", decrypt(record.send("#{@attribute}")))
+  #     end
+  #
+  #     alias_method :after_initialize, :after_save
+  #
+  #     private
+  #       def encrypt(value)
+  #         # Secrecy is committed
+  #       end
+  #
+  #       def decrypt(value)
+  #         # Secrecy is unveiled
+  #       end
+  #   end
+  #
+  # The callback macros usually accept a symbol for the method they're supposed to run, but you can also
+  # pass a "method string", which will then be evaluated within the binding of the callback. Example:
+  #
+  #   class Topic < ActiveRecord::Base
+  #     before_destroy 'self.class.delete_all "parent_id = #{id}"'
+  #   end
+  #
+  # Notice that single quotes (') are used so the <tt>#{id}</tt> part isn't evaluated until the callback
+  # is triggered. Also note that these inline callbacks can be stacked just like the regular ones:
+  #
+  #   class Topic < ActiveRecord::Base
+  #     before_destroy 'self.class.delete_all "parent_id = #{id}"',
+  #                    'puts "Evaluated after parents are destroyed"'
+  #   end
+  #
+  # == <tt>before_validation*</tt> returning statements
+  #
+  # If the returning value of a +before_validation+ callback can be evaluated to +false+, the process will be
+  # aborted and <tt>Base#save</tt> will return +false+. If Base#save! is called it will raise a
+  # ActiveRecord::RecordInvalid exception. Nothing will be appended to the errors object.
+  #
+  # == Canceling callbacks
+  #
+  # If a <tt>before_*</tt> callback returns +false+, all the later callbacks and the associated action are
+  # cancelled. If an <tt>after_*</tt> callback returns +false+, all the later callbacks are cancelled.
+  # Callbacks are generally run in the order they are defined, with the exception of callbacks defined as
+  # methods on the model, which are called last.
+  #
+  # == Ordering callbacks
+  #
+  # Sometimes the code needs that the callbacks execute in a specific order. For example, a +before_destroy+
+  # callback (+log_children+ in this case) should be executed before the children get destroyed by the +dependent: destroy+ option.
+  #
+  # Let's look at the code below:
+  #
+  #   class Topic < ActiveRecord::Base
+  #     has_many :children, dependent: destroy
+  #
+  #     before_destroy :log_children
+  #
+  #     private
+  #       def log_children
+  #         # Child processing
+  #       end
+  #   end
+  #
+  # In this case, the problem is that when the +before_destroy+ callback is executed, the children are not available
+  # because the +destroy+ callback gets executed first. You can use the +prepend+ option on the +before_destroy+ callback to avoid this.
+  #
+  #   class Topic < ActiveRecord::Base
+  #     has_many :children, dependent: destroy
+  #
+  #     before_destroy :log_children, prepend: true
+  #
+  #     private
+  #       def log_children
+  #         # Child processing
+  #       end
+  #   end
+  #
+  # This way, the +before_destroy+ gets executed before the <tt>dependent: destroy</tt> is called, and the data is still available.
+  #
+  # == Transactions
+  #
+  # The entire callback chain of a +save+, <tt>save!</tt>, or +destroy+ call runs
+  # within a transaction. That includes <tt>after_*</tt> hooks. If everything
+  # goes fine a COMMIT is executed once the chain has been completed.
+  #
+  # If a <tt>before_*</tt> callback cancels the action a ROLLBACK is issued. You
+  # can also trigger a ROLLBACK raising an exception in any of the callbacks,
+  # including <tt>after_*</tt> hooks. Note, however, that in that case the client
+  # needs to be aware of it because an ordinary +save+ will raise such exception
+  # instead of quietly returning +false+.
+  #
+  # == Debugging callbacks
+  #
+  # The callback chain is accessible via the <tt>_*_callbacks</tt> method on an object. ActiveModel Callbacks support
+  # <tt>:before</tt>, <tt>:after</tt> and <tt>:around</tt> as values for the <tt>kind</tt> property. The <tt>kind</tt> property
+  # defines what part of the chain the callback runs in.
+  #
+  # To find all callbacks in the before_save callback chain:
+  #
+  #   Topic._save_callbacks.select { |cb| cb.kind.eql?(:before) }
+  #
+  # Returns an array of callback objects that form the before_save chain.
+  #
+  # To further check if the before_save chain contains a proc defined as <tt>rest_when_dead</tt> use the <tt>filter</tt> property of the callback object:
+  #
+  #   Topic._save_callbacks.select { |cb| cb.kind.eql?(:before) }.collect(&:filter).include?(:rest_when_dead)
+  #
+  # Returns true or false depending on whether the proc is contained in the before_save callback chain on a Topic model.
+  #
+  module Callbacks
+    extend ActiveSupport::Concern
+
+    CALLBACKS = [
+      :after_initialize, :after_find, :after_touch, :before_validation, :after_validation,
+      :before_save, :around_save, :after_save, :before_create, :around_create,
+      :after_create, :before_update, :around_update, :after_update,
+      :before_destroy, :around_destroy, :after_destroy, :after_commit, :after_rollback
+    ]
+
+    module ClassMethods
+      include ActiveModel::Callbacks
+    end
+
+    included do
+      include ActiveModel::Validations::Callbacks
+
+      define_model_callbacks :initialize, :find, :touch, :only => :after
+      define_model_callbacks :save, :create, :update, :destroy
+    end
+
+    def destroy #:nodoc:
+      _run_destroy_callbacks { super }
+    end
+
+    def touch(*) #:nodoc:
+      _run_touch_callbacks { super }
+    end
+
+  private
+
+    def create_or_update #:nodoc:
+      _run_save_callbacks { super }
+    end
+
+    def _create_record #:nodoc:
+      _run_create_callbacks { super }
+    end
+
+    def _update_record(*) #:nodoc:
+      _run_update_callbacks { super }
+    end
+  end
+end

data/lib/active_record/coders/json.rb

@@ -0,0 +1,13 @@
+module ActiveRecord
+  module Coders # :nodoc:
+    class JSON # :nodoc:
+      def self.dump(obj)
+        ActiveSupport::JSON.encode(obj)
+      end
+
+      def self.load(json)
+        ActiveSupport::JSON.decode(json) unless json.nil?
+      end
+    end
+  end
+end

data/lib/active_record/coders/yaml_column.rb

@@ -0,0 +1,38 @@
+require 'yaml'
+
+module ActiveRecord
+  module Coders # :nodoc:
+    class YAMLColumn # :nodoc:
+
+      attr_accessor :object_class
+
+      def initialize(object_class = Object)
+        @object_class = object_class
+      end
+
+      def dump(obj)
+        return if obj.nil?
+
+        unless obj.is_a?(object_class)
+          raise SerializationTypeMismatch,
+            "Attribute was supposed to be a #{object_class}, but was a #{obj.class}. -- #{obj.inspect}"
+        end
+        YAML.dump obj
+      end
+
+      def load(yaml)
+        return object_class.new if object_class != Object && yaml.nil?
+        return yaml unless yaml.is_a?(String) && yaml =~ /^---/
+        obj = YAML.load(yaml)
+
+        unless obj.is_a?(object_class) || obj.nil?
+          raise SerializationTypeMismatch,
+            "Attribute was supposed to be a #{object_class}, but was a #{obj.class}"
+        end
+        obj ||= object_class.new if object_class != Object
+
+        obj
+      end
+    end
+  end
+end

data/lib/active_record/connection_adapters/abstract/connection_pool.rb

@@ -0,0 +1,659 @@
+require 'thread'
+require 'thread_safe'
+require 'monitor'
+require 'set'
+require 'active_support/core_ext/string/filters'
+
+module ActiveRecord
+  # Raised when a connection could not be obtained within the connection
+  # acquisition timeout period: because max connections in pool
+  # are in use.
+  class ConnectionTimeoutError < ConnectionNotEstablished
+  end
+
+  module ConnectionAdapters
+    # Connection pool base class for managing Active Record database
+    # connections.
+    #
+    # == Introduction
+    #
+    # A connection pool synchronizes thread access to a limited number of
+    # database connections. The basic idea is that each thread checks out a
+    # database connection from the pool, uses that connection, and checks the
+    # connection back in. ConnectionPool is completely thread-safe, and will
+    # ensure that a connection cannot be used by two threads at the same time,
+    # as long as ConnectionPool's contract is correctly followed. It will also
+    # handle cases in which there are more threads than connections: if all
+    # connections have been checked out, and a thread tries to checkout a
+    # connection anyway, then ConnectionPool will wait until some other thread
+    # has checked in a connection.
+    #
+    # == Obtaining (checking out) a connection
+    #
+    # Connections can be obtained and used from a connection pool in several
+    # ways:
+    #
+    # 1. Simply use ActiveRecord::Base.connection as with Active Record 2.1 and
+    #    earlier (pre-connection-pooling). Eventually, when you're done with
+    #    the connection(s) and wish it to be returned to the pool, you call
+    #    ActiveRecord::Base.clear_active_connections!. This will be the
+    #    default behavior for Active Record when used in conjunction with
+    #    Action Pack's request handling cycle.
+    # 2. Manually check out a connection from the pool with
+    #    ActiveRecord::Base.connection_pool.checkout. You are responsible for
+    #    returning this connection to the pool when finished by calling
+    #    ActiveRecord::Base.connection_pool.checkin(connection).
+    # 3. Use ActiveRecord::Base.connection_pool.with_connection(&block), which
+    #    obtains a connection, yields it as the sole argument to the block,
+    #    and returns it to the pool after the block completes.
+    #
+    # Connections in the pool are actually AbstractAdapter objects (or objects
+    # compatible with AbstractAdapter's interface).
+    #
+    # == Options
+    #
+    # There are several connection-pooling-related options that you can add to
+    # your database connection configuration:
+    #
+    # * +pool+: number indicating size of connection pool (default 5)
+    # * +checkout_timeout+: number of seconds to block and wait for a connection
+    #   before giving up and raising a timeout error (default 5 seconds).
+    # * +reaping_frequency+: frequency in seconds to periodically run the
+    #   Reaper, which attempts to find and recover connections from dead
+    #   threads, which can occur if a programmer forgets to close a
+    #   connection at the end of a thread or a thread dies unexpectedly.
+    #   Regardless of this setting, the Reaper will be invoked before every
+    #   blocking wait. (Default nil, which means don't schedule the Reaper).
+    class ConnectionPool
+      # Threadsafe, fair, FIFO queue.  Meant to be used by ConnectionPool
+      # with which it shares a Monitor.  But could be a generic Queue.
+      #
+      # The Queue in stdlib's 'thread' could replace this class except
+      # stdlib's doesn't support waiting with a timeout.
+      class Queue
+        def initialize(lock = Monitor.new)
+          @lock = lock
+          @cond = @lock.new_cond
+          @num_waiting = 0
+          @queue = []
+        end
+
+        # Test if any threads are currently waiting on the queue.
+        def any_waiting?
+          synchronize do
+            @num_waiting > 0
+          end
+        end
+
+        # Returns the number of threads currently waiting on this
+        # queue.
+        def num_waiting
+          synchronize do
+            @num_waiting
+          end
+        end
+
+        # Add +element+ to the queue.  Never blocks.
+        def add(element)
+          synchronize do
+            @queue.push element
+            @cond.signal
+          end
+        end
+
+        # If +element+ is in the queue, remove and return it, or nil.
+        def delete(element)
+          synchronize do
+            @queue.delete(element)
+          end
+        end
+
+        # Remove all elements from the queue.
+        def clear
+          synchronize do
+            @queue.clear
+          end
+        end
+
+        # Remove the head of the queue.
+        #
+        # If +timeout+ is not given, remove and return the head the
+        # queue if the number of available elements is strictly
+        # greater than the number of threads currently waiting (that
+        # is, don't jump ahead in line).  Otherwise, return nil.
+        #
+        # If +timeout+ is given, block if it there is no element
+        # available, waiting up to +timeout+ seconds for an element to
+        # become available.
+        #
+        # Raises:
+        # - ConnectionTimeoutError if +timeout+ is given and no element
+        # becomes available after +timeout+ seconds,
+        def poll(timeout = nil)
+          synchronize do
+            if timeout
+              no_wait_poll || wait_poll(timeout)
+            else
+              no_wait_poll
+            end
+          end
+        end
+
+        private
+
+        def synchronize(&block)
+          @lock.synchronize(&block)
+        end
+
+        # Test if the queue currently contains any elements.
+        def any?
+          !@queue.empty?
+        end
+
+        # A thread can remove an element from the queue without
+        # waiting if an only if the number of currently available
+        # connections is strictly greater than the number of waiting
+        # threads.
+        def can_remove_no_wait?
+          @queue.size > @num_waiting
+        end
+
+        # Removes and returns the head of the queue if possible, or nil.
+        def remove
+          @queue.shift
+        end
+
+        # Remove and return the head the queue if the number of
+        # available elements is strictly greater than the number of
+        # threads currently waiting.  Otherwise, return nil.
+        def no_wait_poll
+          remove if can_remove_no_wait?
+        end
+
+        # Waits on the queue up to +timeout+ seconds, then removes and
+        # returns the head of the queue.
+        def wait_poll(timeout)
+          @num_waiting += 1
+
+          t0 = Time.now
+          elapsed = 0
+          loop do
+            @cond.wait(timeout - elapsed)
+
+            return remove if any?
+
+            elapsed = Time.now - t0
+            if elapsed >= timeout
+              msg = 'could not obtain a database connection within %0.3f seconds (waited %0.3f seconds)' %
+                [timeout, elapsed]
+              raise ConnectionTimeoutError, msg
+            end
+          end
+        ensure
+          @num_waiting -= 1
+        end
+      end
+
+      # Every +frequency+ seconds, the reaper will call +reap+ on +pool+.
+      # A reaper instantiated with a nil frequency will never reap the
+      # connection pool.
+      #
+      # Configure the frequency by setting "reaping_frequency" in your
+      # database yaml file.
+      class Reaper
+        attr_reader :pool, :frequency
+
+        def initialize(pool, frequency)
+          @pool      = pool
+          @frequency = frequency
+        end
+
+        def run
+          return unless frequency
+          Thread.new(frequency, pool) { |t, p|
+            while true
+              sleep t
+              p.reap
+            end
+          }
+        end
+      end
+
+      include MonitorMixin
+
+      attr_accessor :automatic_reconnect, :checkout_timeout
+      attr_reader :spec, :connections, :size, :reaper
+
+      # Creates a new ConnectionPool object. +spec+ is a ConnectionSpecification
+      # object which describes database connection information (e.g. adapter,
+      # host name, username, password, etc), as well as the maximum size for
+      # this ConnectionPool.
+      #
+      # The default ConnectionPool maximum size is 5.
+      def initialize(spec)
+        super()
+
+        @spec = spec
+
+        @checkout_timeout = (spec.config[:checkout_timeout] && spec.config[:checkout_timeout].to_f) || 5
+        @reaper  = Reaper.new self, spec.config[:reaping_frequency]
+        @reaper.run
+
+        # default max pool size to 5
+        @size = (spec.config[:pool] && spec.config[:pool].to_i) || 5
+
+        # The cache of reserved connections mapped to threads
+        @reserved_connections = ThreadSafe::Cache.new(:initial_capacity => @size)
+
+        @connections         = []
+        @automatic_reconnect = true
+
+        @available = Queue.new self
+      end
+
+      # Retrieve the connection associated with the current thread, or call
+      # #checkout to obtain one if necessary.
+      #
+      # #connection can be called any number of times; the connection is
+      # held in a hash keyed by the thread id.
+      def connection
+        # this is correctly done double-checked locking
+        # (ThreadSafe::Cache's lookups have volatile semantics)
+        @reserved_connections[current_connection_id] || synchronize do
+          @reserved_connections[current_connection_id] ||= checkout
+        end
+      end
+
+      # Is there an open connection that is being used for the current thread?
+      def active_connection?
+        synchronize do
+          @reserved_connections.fetch(current_connection_id) {
+            return false
+          }.in_use?
+        end
+      end
+
+      # Signal that the thread is finished with the current connection.
+      # #release_connection releases the connection-thread association
+      # and returns the connection to the pool.
+      def release_connection(with_id = current_connection_id)
+        synchronize do
+          conn = @reserved_connections.delete(with_id)
+          checkin conn if conn
+        end
+      end
+
+      # If a connection already exists yield it to the block. If no connection
+      # exists checkout a connection, yield it to the block, and checkin the
+      # connection when finished.
+      def with_connection
+        connection_id = current_connection_id
+        fresh_connection = true unless active_connection?
+        yield connection
+      ensure
+        release_connection(connection_id) if fresh_connection
+      end
+
+      # Returns true if a connection has already been opened.
+      def connected?
+        synchronize { @connections.any? }
+      end
+
+      # Disconnects all connections in the pool, and clears the pool.
+      def disconnect!
+        synchronize do
+          @reserved_connections.clear
+          @connections.each do |conn|
+            checkin conn
+            conn.disconnect!
+          end
+          @connections = []
+          @available.clear
+        end
+      end
+
+      # Clears the cache which maps classes.
+      def clear_reloadable_connections!
+        synchronize do
+          @reserved_connections.clear
+          @connections.each do |conn|
+            checkin conn
+            conn.disconnect! if conn.requires_reloading?
+          end
+          @connections.delete_if do |conn|
+            conn.requires_reloading?
+          end
+          @available.clear
+          @connections.each do |conn|
+            @available.add conn
+          end
+        end
+      end
+
+      # Check-out a database connection from the pool, indicating that you want
+      # to use it. You should call #checkin when you no longer need this.
+      #
+      # This is done by either returning and leasing existing connection, or by
+      # creating a new connection and leasing it.
+      #
+      # If all connections are leased and the pool is at capacity (meaning the
+      # number of currently leased connections is greater than or equal to the
+      # size limit set), an ActiveRecord::ConnectionTimeoutError exception will be raised.
+      #
+      # Returns: an AbstractAdapter object.
+      #
+      # Raises:
+      # - ConnectionTimeoutError: no connection can be obtained from the pool.
+      def checkout
+        synchronize do
+          conn = acquire_connection
+          conn.lease
+          checkout_and_verify(conn)
+        end
+      end
+
+      # Check-in a database connection back into the pool, indicating that you
+      # no longer need this connection.
+      #
+      # +conn+: an AbstractAdapter object, which was obtained by earlier by
+      # calling +checkout+ on this pool.
+      def checkin(conn)
+        synchronize do
+          owner = conn.owner
+
+          conn._run_checkin_callbacks do
+            conn.expire
+          end
+
+          release owner
+
+          @available.add conn
+        end
+      end
+
+      # Remove a connection from the connection pool.  The connection will
+      # remain open and active but will no longer be managed by this pool.
+      def remove(conn)
+        synchronize do
+          @connections.delete conn
+          @available.delete conn
+
+          release conn.owner
+
+          @available.add checkout_new_connection if @available.any_waiting?
+        end
+      end
+
+      # Recover lost connections for the pool.  A lost connection can occur if
+      # a programmer forgets to checkin a connection at the end of a thread
+      # or a thread dies unexpectedly.
+      def reap
+        stale_connections = synchronize do
+          @connections.select do |conn|
+            conn.in_use? && !conn.owner.alive?
+          end
+        end
+
+        stale_connections.each do |conn|
+          synchronize do
+            if conn.active?
+              conn.reset!
+              checkin conn
+            else
+              remove conn
+            end
+          end
+        end
+      end
+
+      private
+
+      # Acquire a connection by one of 1) immediately removing one
+      # from the queue of available connections, 2) creating a new
+      # connection if the pool is not at capacity, 3) waiting on the
+      # queue for a connection to become available.
+      #
+      # Raises:
+      # - ConnectionTimeoutError if a connection could not be acquired
+      def acquire_connection
+        if conn = @available.poll
+          conn
+        elsif @connections.size < @size
+          checkout_new_connection
+        else
+          reap
+          @available.poll(@checkout_timeout)
+        end
+      end
+
+      def release(owner)
+        thread_id = owner.object_id
+
+        @reserved_connections.delete thread_id
+      end
+
+      def new_connection
+        Base.send(spec.adapter_method, spec.config)
+      end
+
+      def current_connection_id #:nodoc:
+        Base.connection_id ||= Thread.current.object_id
+      end
+
+      def checkout_new_connection
+        raise ConnectionNotEstablished unless @automatic_reconnect
+
+        c = new_connection
+        c.pool = self
+        @connections << c
+        c
+      end
+
+      def checkout_and_verify(c)
+        c._run_checkout_callbacks do
+          c.verify!
+        end
+        c
+      end
+    end
+
+    # ConnectionHandler is a collection of ConnectionPool objects. It is used
+    # for keeping separate connection pools for Active Record models that connect
+    # to different databases.
+    #
+    # For example, suppose that you have 5 models, with the following hierarchy:
+    #
+    #   class Author < ActiveRecord::Base
+    #   end
+    #
+    #   class BankAccount < ActiveRecord::Base
+    #   end
+    #
+    #   class Book < ActiveRecord::Base
+    #     establish_connection "library_db"
+    #   end
+    #
+    #   class ScaryBook < Book
+    #   end
+    #
+    #   class GoodBook < Book
+    #   end
+    #
+    # And a database.yml that looked like this:
+    #
+    #   development:
+    #     database: my_application
+    #     host: localhost
+    #
+    #   library_db:
+    #     database: library
+    #     host: some.library.org
+    #
+    # Your primary database in the development environment is "my_application"
+    # but the Book model connects to a separate database called "library_db"
+    # (this can even be a database on a different machine).
+    #
+    # Book, ScaryBook and GoodBook will all use the same connection pool to
+    # "library_db" while Author, BankAccount, and any other models you create
+    # will use the default connection pool to "my_application".
+    #
+    # The various connection pools are managed by a single instance of
+    # ConnectionHandler accessible via ActiveRecord::Base.connection_handler.
+    # All Active Record models use this handler to determine the connection pool that they
+    # should use.
+    class ConnectionHandler
+      def initialize
+        # These caches are keyed by klass.name, NOT klass. Keying them by klass
+        # alone would lead to memory leaks in development mode as all previous
+        # instances of the class would stay in memory.
+        @owner_to_pool = ThreadSafe::Cache.new(:initial_capacity => 2) do |h,k|
+          h[k] = ThreadSafe::Cache.new(:initial_capacity => 2)
+        end
+        @class_to_pool = ThreadSafe::Cache.new(:initial_capacity => 2) do |h,k|
+          h[k] = ThreadSafe::Cache.new
+        end
+      end
+
+      def connection_pool_list
+        owner_to_pool.values.compact
+      end
+
+      def connection_pools
+        ActiveSupport::Deprecation.warn(<<-MSG.squish)
+          In the next release, this will return the same as `#connection_pool_list`.
+          (An array of pools, rather than a hash mapping specs to pools.)
+        MSG
+
+        Hash[connection_pool_list.map { |pool| [pool.spec, pool] }]
+      end
+
+      def establish_connection(owner, spec)
+        @class_to_pool.clear
+        raise RuntimeError, "Anonymous class is not allowed." unless owner.name
+        owner_to_pool[owner.name] = ConnectionAdapters::ConnectionPool.new(spec)
+      end
+
+      # Returns true if there are any active connections among the connection
+      # pools that the ConnectionHandler is managing.
+      def active_connections?
+        connection_pool_list.any?(&:active_connection?)
+      end
+
+      # Returns any connections in use by the current thread back to the pool,
+      # and also returns connections to the pool cached by threads that are no
+      # longer alive.
+      def clear_active_connections!
+        connection_pool_list.each(&:release_connection)
+      end
+
+      # Clears the cache which maps classes.
+      def clear_reloadable_connections!
+        connection_pool_list.each(&:clear_reloadable_connections!)
+      end
+
+      def clear_all_connections!
+        connection_pool_list.each(&:disconnect!)
+      end
+
+      # Locate the connection of the nearest super class. This can be an
+      # active or defined connection: if it is the latter, it will be
+      # opened and set as the active connection for the class it was defined
+      # for (not necessarily the current class).
+      def retrieve_connection(klass) #:nodoc:
+        pool = retrieve_connection_pool(klass)
+        raise ConnectionNotEstablished, "No connection pool for #{klass}" unless pool
+        conn = pool.connection
+        raise ConnectionNotEstablished, "No connection for #{klass} in connection pool" unless conn
+        conn
+      end
+
+      # Returns true if a connection that's accessible to this class has
+      # already been opened.
+      def connected?(klass)
+        conn = retrieve_connection_pool(klass)
+        conn && conn.connected?
+      end
+
+      # Remove the connection for this class. This will close the active
+      # connection and the defined connection (if they exist). The result
+      # can be used as an argument for establish_connection, for easily
+      # re-establishing the connection.
+      def remove_connection(owner)
+        if pool = owner_to_pool.delete(owner.name)
+          @class_to_pool.clear
+          pool.automatic_reconnect = false
+          pool.disconnect!
+          pool.spec.config
+        end
+      end
+
+      # Retrieving the connection pool happens a lot so we cache it in @class_to_pool.
+      # This makes retrieving the connection pool O(1) once the process is warm.
+      # When a connection is established or removed, we invalidate the cache.
+      #
+      # Ideally we would use #fetch here, as class_to_pool[klass] may sometimes be nil.
+      # However, benchmarking (https://gist.github.com/jonleighton/3552829) showed that
+      # #fetch is significantly slower than #[]. So in the nil case, no caching will
+      # take place, but that's ok since the nil case is not the common one that we wish
+      # to optimise for.
+      def retrieve_connection_pool(klass)
+        class_to_pool[klass.name] ||= begin
+          until pool = pool_for(klass)
+            klass = klass.superclass
+            break unless klass <= Base
+          end
+
+          class_to_pool[klass.name] = pool
+        end
+      end
+
+      private
+
+      def owner_to_pool
+        @owner_to_pool[Process.pid]
+      end
+
+      def class_to_pool
+        @class_to_pool[Process.pid]
+      end
+
+      def pool_for(owner)
+        owner_to_pool.fetch(owner.name) {
+          if ancestor_pool = pool_from_any_process_for(owner)
+            # A connection was established in an ancestor process that must have
+            # subsequently forked. We can't reuse the connection, but we can copy
+            # the specification and establish a new connection with it.
+            establish_connection owner, ancestor_pool.spec
+          else
+            owner_to_pool[owner.name] = nil
+          end
+        }
+      end
+
+      def pool_from_any_process_for(owner)
+        owner_to_pool = @owner_to_pool.values.find { |v| v[owner.name] }
+        owner_to_pool && owner_to_pool[owner.name]
+      end
+    end
+
+    class ConnectionManagement
+      def initialize(app)
+        @app = app
+      end
+
+      def call(env)
+        testing = env['rack.test']
+
+        response = @app.call(env)
+        response[2] = ::Rack::BodyProxy.new(response[2]) do
+          ActiveRecord::Base.clear_active_connections! unless testing
+        end
+
+        response
+      rescue Exception
+        ActiveRecord::Base.clear_active_connections! unless testing
+        raise
+      end
+    end
+  end
+end