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.

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.