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:

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.

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).

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.

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).

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.

# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 318definitialize(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] &&spec.config[:reaping_frequency].to_f))
@reaper.run# default max pool size to 5@size = (spec.config[:pool] &&spec.config[:pool].to_i) ||5# The cache of threads mapped to reserved connections, the sole purpose# of the cache is to speed-up +connection+ method, it is not the authoritative# registry of which thread owns which connection, that is tracked by# +connection.owner+ attr on each +connection+ instance.# The invariant works like this: if there is mapping of +thread => conn+,# then that +thread+ does indeed own that +conn+, however an absence of a such# mapping does not mean that the +thread+ doesn't own the said connection, in# that case +conn.owner+ attr should be consulted.# Access and modification of +@thread_cached_conns+ does not require# synchronization.@thread_cached_conns = ThreadSafe::Cache.new(:initial_capacity =>@size)
@connections = []
@automatic_reconnect = true# Connection pool allows for concurrent (outside the main `synchronize` section)# establishment of new connections. This variable tracks the number of threads# currently in the process of independently establishing connections to the DB.@now_connecting = 0# A boolean toggle that allows/disallows new connections.@new_cons_enabled = true@available = ConnectionLeasingQueue.newselfend

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.

# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 442defclear_reloadable_connections(raise_on_acquisition_timeout = true)
num_new_conns_required = 0with_exclusively_acquired_all_connections(raise_on_acquisition_timeout) dosynchronizedo@connections.eachdo|conn|checkinconnconn.disconnect!ifconn.requires_reloading?end@connections.delete_if(&:requires_reloading?)
@available.clearif@connections.size<@size# because of the pruning done by this method, we might be running# low on connections, while threads stuck in queue are helpless# (not being able to establish new connections for themselves),# see also more detailed explanation in +remove+num_new_conns_required = num_waiting_in_queue-@connections.sizeend@connections.eachdo|conn|@available.addconnendendendbulk_make_new_connections(num_new_conns_required) ifnum_new_conns_required>0end

Clears the cache which maps classes and re-connects connections that
require reloading.

The pool first tries to gain ownership of all connections, if unable to do
so within a timeout interval (default duration is +spec.config * 2+ seconds), the pool forcefully
clears the cache and reloads connections without any regard for other
connection owning threads.

The pool first tries to gain ownership of all connections, if unable to do
so within a timeout interval (default duration is +spec.config * 2+ seconds), the pool is
forcefully disconneted wihout any regard for other connection owning
threads.

# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 521defremove(conn)
needs_new_connection = falsesynchronizedoremove_connection_from_thread_cacheconn@connections.deleteconn@available.deleteconn# @available.any_waiting? => true means that prior to removing this# conn, the pool was at its max size (@connections.size == @size)# this would mean that any threads stuck waiting in the queue wouldn't# know they could checkout_new_connection, so let's do it for them.# Because condition-wait loop is encapsulated in the Queue class# (that in turn is oblivious to ConnectionPool implementation), threads# that are "stuck" there are helpless, they have no way of creating# new connections and are completely reliant on us feeding available# connections into the Queue.needs_new_connection = @available.any_waiting?end# This is intentionally done outside of the synchronized section as we# would like not to hold the main mutex while checking out new connections,# thus there is some chance that needs_new_connection information is now# stale, we can live with that (bulk_make_new_connections will make# sure not to exceed the pool's @size limit).bulk_make_new_connections(1) ifneeds_new_connectionend

If a connection obtained through connection or with_connection
methods already exists yield it to the block. If no such connection exists
checkout a connection, yield it to the block, and checkin the connection
when finished.