Active Record Connection Pool

# 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

# 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

# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 337
def activate
  @activated = true
end

# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 341
def activated?
  @activated
end

# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 411
def active_connection?
  connection_lease.connection
end

# 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

# 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

# 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

# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 604
def clear_reloadable_connections!
  clear_reloadable_connections(false)
end

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

# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 497
def connections
  synchronize { @connections.dup }
end

# 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

# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 538
def disconnect!
  disconnect(false)
end

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# File activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 312
def schema_cache
  @schema_cache ||= BoundSchemaReflection.new(schema_reflection, self)
end

# 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

# 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

# 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