Active Record Connection Pool

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, or the checkout_timeout has expired.

Obtaining (checking out) a connection

Connections can be obtained and used from a connection pool in several ways:

  1. Simply use ActiveRecord::Base.lease_connection. When you’re done with the connection(s) and wish it to be returned to the pool, you call ActiveRecord::Base.connection_handler.clear_active_connections!. This is 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).

While a thread has a connection checked out from the pool using one of the above three methods, that connection will automatically be the one used by ActiveRecord queries executing on that thread. It is not required to explicitly pass the checked out connection to Rails models or queries, for example.

Options

There are several connection-pooling-related options that you can add to your database connection configuration:

  • checkout_timeout: number of seconds to wait for a connection to become available before giving up and raising a timeout error (default 5 seconds).

  • idle_timeout: number of seconds that a connection will be kept unused in the pool before it is automatically disconnected (default 300 seconds). Set this to zero to keep connections forever.

  • keepalive: number of seconds between keepalive checks if the connection has been idle (default 600 seconds).

  • max_age: number of seconds the pool will allow the connection to exist before retiring it at next checkin. (default Float::INFINITY).

  • max_connections: maximum number of connections the pool may manage (default 5).

  • min_connections: minimum number of connections the pool will open and maintain (default 0).

  • pool_jitter: maximum reduction factor to apply to max_age and keepalive intervals (default 0.2; range 0.0-1.0).

Namespace

Class

Methods

Included Modules

  • MonitorMixin

Constants

WeakThreadKeyMap = ObjectSpace::WeakKeyMap

Attributes

[R] async_executor
[RW] automatic_reconnect
[RW] checkout_timeout
[R] db_config
[R] keepalive
[R] max_age
[R] max_connections
[R] min_connections
[R] pool_config
[R] reaper
[R] role
[R] shard
[R] size

Class Public methods

install_executor_hooks(executor = ActiveSupport::Executor)

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 225
        def install_executor_hooks(executor = ActiveSupport::Executor)
          executor.register_hook(ExecutorHooks)
        end
🔎 See on GitHub

new(pool_config)

Creates a new ConnectionPool object. pool_config is a PoolConfig 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.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 246
      def initialize(pool_config)
        super()

        @pool_config = pool_config
        @db_config = pool_config.db_config
        @role = pool_config.role
        @shard = pool_config.shard

        @checkout_timeout = db_config.checkout_timeout
        @idle_timeout = db_config.idle_timeout
        @max_connections = db_config.max_connections
        @min_connections = db_config.min_connections
        @max_age = db_config.max_age
        @keepalive = db_config.keepalive

        # This variable tracks the cache of threads mapped to reserved connections, with the
        # sole purpose of speeding up the +connection+ method. It is not the authoritative
        # registry of which thread owns which connection. Connection ownership is tracked by
        # the +connection.owner+ attr on each +connection+ instance.
        # The invariant works like this: if there is mapping of <tt>thread => conn</tt>,
        # then that +thread+ does indeed own that +conn+. However, an absence of 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 <tt>@leases</tt> does not require
        # synchronization.
        @leases = LeaseRegistry.new

        @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

        # Sometimes otherwise-idle connections are temporarily held by the Reaper for
        # maintenance. This variable tracks the number of connections currently in that
        # state -- if a thread requests a connection and there are none available, it
        # will await any in-maintenance connections in preference to creating a new one.
        @maintaining = 0

        @threads_blocking_new_connections = 0

        @available = ConnectionLeasingQueue.new self
        @pinned_connection = nil
        @pinned_connections_depth = 0

        @async_executor = build_async_executor

        @schema_cache = nil

        @activated = false
        @original_context = ActiveSupport::IsolatedExecutionState.context

        @reaper_lock = Monitor.new
        @reaper = Reaper.new(self, db_config.reaping_frequency)
        @reaper.run
      end
🔎 See on GitHub

Instance Public methods

activate()

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 337
      def activate
        @activated = true
      end
🔎 See on GitHub

activated?()

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 341
      def activated?
        @activated
      end
🔎 See on GitHub

active_connection?()

Returns true if there is an open connection being used for the current thread.

This method only works for connections that have been obtained through lease_connection or with_connection methods. Connections obtained through checkout will not be detected by active_connection?

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 411
      def active_connection?
        connection_lease.connection
      end
🔎 See on GitHub

checkin(conn)

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.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 650
      def checkin(conn)
        return if @pinned_connection.equal?(conn)

        conn.lock.synchronize do
          synchronize do
            connection_lease.clear(conn)

            conn._run_checkin_callbacks do
              conn.expire
            end

            @available.add conn
          end
        end
      end
🔎 See on GitHub

checkout(checkout_timeout = @checkout_timeout)

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:

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 622
      def checkout(checkout_timeout = @checkout_timeout)
        return checkout_and_verify(acquire_connection(checkout_timeout)) unless @pinned_connection

        @pinned_connection.lock.synchronize do
          synchronize do
            # The pinned connection may have been cleaned up before we synchronized, so check if it is still present
            if @pinned_connection
              @pinned_connection.verify!

              # Any leased connection must be in @connections otherwise
              # some methods like #connected? won't behave correctly
              unless @connections.include?(@pinned_connection)
                @connections << @pinned_connection
              end

              @pinned_connection
            else
              checkout_and_verify(acquire_connection(checkout_timeout))
            end
          end
        end
      end
🔎 See on GitHub

clear_reloadable_connections(raise_on_acquisition_timeout = true)

Clears reloadable connections from the pool and re-connects connections that require reloading.

Raises:

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 580
      def clear_reloadable_connections(raise_on_acquisition_timeout = true)
        with_exclusively_acquired_all_connections(raise_on_acquisition_timeout) do
          synchronize do
            @connections.each do |conn|
              if conn.in_use?
                conn.steal!
                checkin conn
              end
              conn.disconnect! if conn.requires_reloading?
            end
            @connections.delete_if(&:requires_reloading?)
            @available.clear
          end
        end
      end
🔎 See on GitHub

clear_reloadable_connections!()

Clears reloadable connections from the pool 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.db_config.checkout_timeout * 2 seconds), then the pool forcefully clears the cache and reloads connections without any regard for other connection owning threads.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 604
      def clear_reloadable_connections!
        clear_reloadable_connections(false)
      end
🔎 See on GitHub

connected?()

Returns true if a connection has already been opened.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 482
      def connected?
        synchronize { @connections.any?(&:connected?) }
      end
🔎 See on GitHub

connections()

Returns an array containing the connections currently in the pool. Access to the array does not require synchronization on the pool because the array is newly created and not retained by the pool.

However; this method bypasses the ConnectionPool’s thread-safe connection access pattern. A returned connection may be owned by another thread, unowned, or by happen-stance owned by the calling thread.

Calling methods on a connection without ownership is subject to the thread-safety guarantees of the underlying method. Many of the methods on connection adapter classes are inherently multi-thread unsafe.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 497
      def connections
        synchronize { @connections.dup }
      end
🔎 See on GitHub

disconnect(raise_on_acquisition_timeout = true)

Disconnects all connections in the pool, and clears the pool.

Raises:

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 507
      def disconnect(raise_on_acquisition_timeout = true)
        @reaper_lock.synchronize do
          return if self.discarded?

          with_exclusively_acquired_all_connections(raise_on_acquisition_timeout) do
            synchronize do
              return if self.discarded?
              @connections.each do |conn|
                if conn.in_use?
                  conn.steal!
                  checkin conn
                end
                conn.disconnect!
              end
              @connections = []
              @leases.clear
              @available.clear

              # Stop maintaining the minimum size until reactivated
              @activated = false
            end
          end
        end
      end
🔎 See on GitHub

disconnect!()

Disconnects all connections in the pool, and clears the pool.

The pool first tries to gain ownership of all connections. If unable to do so within a timeout interval (default duration is spec.db_config.checkout_timeout * 2 seconds), then the pool is forcefully disconnected without any regard for other connection owning threads.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 538
      def disconnect!
        disconnect(false)
      end
🔎 See on GitHub

flush(minimum_idle = @idle_timeout)

Disconnect all connections that have been idle for at least minimum_idle seconds. Connections currently checked out, or that were checked in less than minimum_idle seconds ago, are unaffected.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 723
      def flush(minimum_idle = @idle_timeout)
        return if minimum_idle.nil?

        removed_connections = synchronize do
          return if self.discarded?

          idle_connections = @connections.select do |conn|
            !conn.in_use? && conn.seconds_idle >= minimum_idle
          end.sort_by { |conn| -conn.seconds_idle } # sort longest idle first

          # Don't go below our configured pool minimum unless we're flushing
          # everything
          idles_to_retain =
            if minimum_idle > 0
              @min_connections - (@connections.size - idle_connections.size)
            else
              0
            end

          if idles_to_retain > 0
            idle_connections.pop idles_to_retain
          end

          idle_connections.each do |conn|
            conn.lease

            @available.delete conn
            @connections.delete conn
          end
        end

        removed_connections.each do |conn|
          conn.disconnect!
        end
      end
🔎 See on GitHub

flush!()

Disconnect all currently idle connections. Connections currently checked out are unaffected. The pool will stop maintaining its minimum size until it is reactivated (such as by a subsequent checkout).

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 762
      def flush!
        reap
        flush(-1)

        # Stop maintaining the minimum size until reactivated
        @activated = false
      end
🔎 See on GitHub

keep_alive(threshold = @keepalive)

Prod any connections that have been idle for longer than the configured keepalive time. This will incidentally verify the connection is still alive, but the main purpose is to show the server (and any intermediate network hops) that we’re still here and using the connection.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 820
      def keep_alive(threshold = @keepalive)
        return if threshold.nil?

        sequential_maintenance -> c { (c.seconds_since_last_activity || 0) > c.pool_jitter(threshold) } do |conn|
          # conn.active? will cause some amount of network activity, which is all
          # we need to provide a keepalive signal.
          #
          # If it returns false, the connection is already broken; disconnect,
          # so it can be found and repaired.
          conn.disconnect! unless conn.active?
        end
      end
🔎 See on GitHub

lease_connection()

Retrieve the connection associated with the current thread, or call checkout to obtain one if necessary.

lease_connection can be called any number of times; the connection is held in a cache keyed by a thread.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 350
      def lease_connection
        lease = connection_lease
        lease.sticky = true
        lease.connection ||= checkout
      end
🔎 See on GitHub

pool_transaction_isolation_level()

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 886
      def pool_transaction_isolation_level
        isolation_level_key = "activerecord_pool_transaction_isolation_level_#{db_config.name}"
        ActiveSupport::IsolatedExecutionState[isolation_level_key]
      end
🔎 See on GitHub

pool_transaction_isolation_level=(isolation_level)

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 891
      def pool_transaction_isolation_level=(isolation_level)
        isolation_level_key = "activerecord_pool_transaction_isolation_level_#{db_config.name}"
        ActiveSupport::IsolatedExecutionState[isolation_level_key] = isolation_level
      end
🔎 See on GitHub

preconnect()

Preconnect all connections in the pool. This saves pool users from having to wait for a connection to be established when first using it after checkout.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 805
      def preconnect
        sequential_maintenance -> c { (!c.connected? || !c.verified?) && c.allow_preconnect } do |conn|
          conn.connect!
        rescue
          # Wholesale rescue: there's nothing we can do but move on. The
          # connection will go back to the pool, and the next consumer will
          # presumably try to connect again -- which will either work, or
          # fail and they'll be able to report the exception.
        end
      end
🔎 See on GitHub

prepopulate()

Ensure that the pool contains at least the configured minimum number of connections.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 772
      def prepopulate
        need_new_connections = nil

        synchronize do
          return if self.discarded?

          # We don't want to start prepopulating until we know the pool is wanted,
          # so we can avoid maintaining full pools in one-off scripts etc.
          return unless @activated

          need_new_connections = @connections.size < @min_connections
        end

        if need_new_connections
          while new_conn = try_to_checkout_new_connection { @connections.size < @min_connections }
            checkin(new_conn)
          end
        end
      end
🔎 See on GitHub

reap()

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.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 700
      def reap
        stale_connections = synchronize do
          return if self.discarded?
          @connections.select do |conn|
            conn.in_use? && !conn.owner.alive?
          end.each do |conn|
            conn.steal!
          end
        end

        stale_connections.each do |conn|
          if conn.active?
            conn.reset!
            checkin conn
          else
            remove conn
          end
        end
      end
🔎 See on GitHub

recycle!()

Immediately mark all current connections as due for replacement, equivalent to them having reached max_age – even if there is no max_age configured.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 836
      def recycle!
        synchronize do
          return if self.discarded?

          @connections.each do |conn|
            conn.force_retirement
          end
        end

        retire_old_connections
      end
🔎 See on GitHub

release_connection(existing_lease = nil)

Signal that the thread is finished with the current connection. release_connection releases the connection-thread association and returns the connection to the pool.

This method only works for connections that have been obtained through lease_connection or with_connection methods, connections obtained through checkout will not be automatically released.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 423
      def release_connection(existing_lease = nil)
        return if self.discarded?

        if conn = connection_lease.release
          checkin conn
          return true
        end
        false
      end
🔎 See on GitHub

remove(conn)

Remove a connection from the connection pool. The connection will remain open and active but will no longer be managed by this pool.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 668
      def remove(conn)
        needs_new_connection = false

        synchronize do
          remove_connection_from_thread_cache conn

          @connections.delete conn
          @available.delete conn

          # @available.any_waiting? => true means that prior to removing this
          # conn, the pool was at its max size (@connections.size == @max_connections).
          # 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.num_waiting > @maintaining
        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 @max_connections limit).
        bulk_make_new_connections(1) if needs_new_connection
      end
🔎 See on GitHub

retire_old_connections(max_age = @max_age)

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 792
      def retire_old_connections(max_age = @max_age)
        max_age ||= Float::INFINITY

        sequential_maintenance -> c { c.connection_age&.>= c.pool_jitter(max_age) } do |conn|
          # Disconnect, then return the adapter to the pool. Preconnect will
          # handle the rest.
          conn.disconnect!
        end
      end
🔎 See on GitHub

schema_cache()

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 312
      def schema_cache
        @schema_cache ||= BoundSchemaReflection.new(schema_reflection, self)
      end
🔎 See on GitHub

schema_reflection=(schema_reflection)

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 316
      def schema_reflection=(schema_reflection)
        pool_config.schema_reflection = schema_reflection
        @schema_cache = nil
      end
🔎 See on GitHub

stat()

Returns the connection pool’s usage statistic.

ActiveRecord::Base.connection_pool.stat # => { size: 15, connections: 1, busy: 1, dead: 0, idle: 0, waiting: 0, checkout_timeout: 5 }
📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 859
      def stat
        synchronize do
          {
            size: size,
            connections: @connections.size,
            busy: @connections.count { |c| c.in_use? && c.owner.alive? },
            dead: @connections.count { |c| c.in_use? && !c.owner.alive? },
            idle: @connections.count { |c| !c.in_use? },
            waiting: num_waiting_in_queue,
            checkout_timeout: checkout_timeout
          }
        end
      end
🔎 See on GitHub

with_connection(prevent_permanent_checkout: false)

Yields a connection from the connection pool to the block. If no connection is already checked out by the current thread, a connection will be checked out from the pool, yielded to the block, and then returned to the pool when the block is finished. If a connection has already been checked out on the current thread, such as via lease_connection or with_connection, that existing connection will be the one yielded and it will not be returned to the pool automatically at the end of the block; it is expected that such an existing connection will be properly returned to the pool by the code that checked it out.

📝 Source code 
# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 442
      def with_connection(prevent_permanent_checkout: false)
        lease = connection_lease
        sticky_was = lease.sticky
        lease.sticky = false if prevent_permanent_checkout

        if lease.connection
          begin
            yield lease.connection
          ensure
            lease.sticky = sticky_was if prevent_permanent_checkout && !sticky_was
          end
        else
          begin
            yield lease.connection = checkout
          ensure
            lease.sticky = sticky_was if prevent_permanent_checkout && !sticky_was
            release_connection(lease) unless lease.sticky
          end
        end
      end
🔎 See on GitHub