Class: ActiveRecord::ConnectionAdapters::ConnectionPool

Inherits:
Object
  • Object
show all
Includes:
QueryCache::ConnectionPoolConfiguration, MonitorMixin
Defined in:
lib/active_record/connection_adapters/abstract/connection_pool.rb,
lib/active_record/connection_adapters/abstract/connection_pool/queue.rb,
lib/active_record/connection_adapters/abstract/connection_pool/reaper.rb

Overview

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). Set to nil or -1 for unlimited connections.

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

– Synchronization policy:

  • all public methods can be called outside synchronize

  • access to these instance variables needs to be in synchronize:

    • @connections

    • @now_connecting

    • @maintaining

  • private methods that require being called in a synchronize blocks are now explicitly documented

Defined Under Namespace

Modules: BiasableQueue, ExecutorHooks Classes: ConnectionLeasingQueue, Lease, LeaseRegistry, Queue, Reaper, WeakThreadKeyMap

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from QueryCache::ConnectionPoolConfiguration

#clear_query_cache, #dirties_query_cache, #disable_query_cache, #disable_query_cache!, #enable_query_cache, #enable_query_cache!, #query_cache, #query_cache_enabled

Constructor Details

#initialize(pool_config) ⇒ ConnectionPool

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.



251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 251

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

Instance Attribute Details

#async_executor ⇒ Object (readonly)

Returns the value of attribute async_executor.



240
241
242
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 240

def async_executor
  @async_executor
end

#automatic_reconnect ⇒ Object

Returns the value of attribute automatic_reconnect.



239
240
241
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 239

def automatic_reconnect
  @automatic_reconnect
end

#checkout_timeout ⇒ Object

Returns the value of attribute checkout_timeout.



239
240
241
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 239

def checkout_timeout
  @checkout_timeout
end

#db_config ⇒ Object (readonly)

Returns the value of attribute db_config.



240
241
242
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 240

def db_config
  @db_config
end

#keepalive ⇒ Object (readonly)

Returns the value of attribute keepalive.



240
241
242
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 240

def keepalive
  @keepalive
end

#max_age ⇒ Object (readonly)

Returns the value of attribute max_age.



240
241
242
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 240

def max_age
  @max_age
end

#max_connections ⇒ Object (readonly) Also known as: size

Returns the value of attribute max_connections.



240
241
242
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 240

def max_connections
  @max_connections
end

#min_connections ⇒ Object (readonly)

Returns the value of attribute min_connections.



240
241
242
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 240

def min_connections
  @min_connections
end

#pool_config ⇒ Object (readonly)

Returns the value of attribute pool_config.



240
241
242
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 240

def pool_config
  @pool_config
end

#reaper ⇒ Object (readonly)

Returns the value of attribute reaper.



240
241
242
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 240

def reaper
  @reaper
end

#role ⇒ Object (readonly)

Returns the value of attribute role.



240
241
242
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 240

def role
  @role
end

#shard ⇒ Object (readonly)

Returns the value of attribute shard.



240
241
242
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 240

def shard
  @shard
end

Class Method Details

.install_executor_hooks(executor = ActiveSupport::Executor) ⇒ Object 



231
232
233
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 231

def install_executor_hooks(executor = ActiveSupport::Executor)
  executor.register_hook(ExecutorHooks)
end

Instance Method Details

#activate ⇒ Object 



342
343
344
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 342

def activate
  @activated = true
end

#activated? ⇒ Boolean

Returns:

  • (Boolean) 


346
347
348
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 346

def activated?
  @activated
end

#active_connection? ⇒ Boolean Also known as: 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?

Returns:

  • (Boolean) 


419
420
421
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 419

def active_connection?
  connection_lease.connection
end

#checkin(conn) ⇒ Object

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.



658
659
660
661
662
663
664
665
666
667
668
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 658

def checkin(conn)
  return if @pinned_connection.equal?(conn)

  conn.lock.synchronize do
    synchronize do
      connection_lease.clear(conn)
      conn.expire
      @available.add conn
    end
  end
end

#checkout(checkout_timeout = @checkout_timeout) ⇒ Object

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:

  • ActiveRecord::ConnectionTimeoutError no connection can be obtained from the pool.



630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 630

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

#clear_reloadable_connections(raise_on_acquisition_timeout = true) ⇒ Object

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

Raises:

  • ActiveRecord::ExclusiveConnectionTimeoutError if unable to gain ownership of all connections in the pool within a timeout interval (default duration is spec.db_config.checkout_timeout * 2 seconds).



588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 588

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

#clear_reloadable_connections! ⇒ Object

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.



612
613
614
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 612

def clear_reloadable_connections!
  clear_reloadable_connections(false)
end

#connected? ⇒ Boolean

Returns true if a connection has already been opened.

Returns:

  • (Boolean) 


490
491
492
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 490

def connected?
  synchronize { @connections.any?(&:connected?) }
end

#connection_descriptor ⇒ Object

:nodoc:



410
411
412
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 410

def connection_descriptor # :nodoc:
  pool_config.connection_descriptor
end

#connections ⇒ Object

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.



505
506
507
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 505

def connections
  synchronize { @connections.dup }
end

#discard! ⇒ Object

Discards all connections in the pool (even if they’re currently leased!), along with the pool itself. Any further interaction with the pool (except #spec and #schema_cache) is undefined.

See AbstractAdapter#discard!



555
556
557
558
559
560
561
562
563
564
565
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 555

def discard! # :nodoc:
  @reaper_lock.synchronize do
    synchronize do
      return if self.discarded?
      @connections.each do |conn|
        conn.discard!
      end
      @connections = @available = @leases = nil
    end
  end
end

#discarded? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


567
568
569
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 567

def discarded? # :nodoc:
  @connections.nil?
end

#disconnect(raise_on_acquisition_timeout = true) ⇒ Object

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

Raises:

  • ActiveRecord::ExclusiveConnectionTimeoutError if unable to gain ownership of all connections in the pool within a timeout interval (default duration is spec.db_config.checkout_timeout * 2 seconds).



515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 515

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

#disconnect! ⇒ Object

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.



546
547
548
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 546

def disconnect!
  disconnect(false)
end

#flush(minimum_idle = @idle_timeout) ⇒ Object

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.



727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 727

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

#flush! ⇒ Object

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



766
767
768
769
770
771
772
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 766

def flush!
  reap
  flush(-1)

  # Stop maintaining the minimum size until reactivated
  @activated = false
end

#inspect ⇒ Object

:nodoc:



310
311
312
313
314
315
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 310

def inspect # :nodoc:
  name_field = " name=#{name_inspect}" if name_inspect
  shard_field = " shard=#{shard_inspect}" if shard_inspect

  "#<#{self.class.name} env_name=#{db_config.env_name.inspect}#{name_field} role=#{role.inspect}#{shard_field}>"
end

#internal_metadata ⇒ Object

:nodoc:



338
339
340
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 338

def internal_metadata # :nodoc:
  InternalMetadata.new(self)
end

#keep_alive(threshold = @keepalive) ⇒ Object

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.



825
826
827
828
829
830
831
832
833
834
835
836
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 825

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

#lease_connection ⇒ Object

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.



355
356
357
358
359
360
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 355

def lease_connection
  lease = connection_lease
  lease.connection ||= checkout
  lease.sticky = true
  lease.connection
end

#maintainable? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


571
572
573
574
575
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 571

def maintainable? # :nodoc:
  synchronize do
    @connections&.size&.> 0 || (activated? && @min_connections > 0)
  end
end

#migration_context ⇒ Object

:nodoc:



326
327
328
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 326

def migration_context # :nodoc:
  MigrationContext.new(migrations_paths, schema_migration, internal_metadata)
end

#migrations_paths ⇒ Object

:nodoc:



330
331
332
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 330

def migrations_paths # :nodoc:
  db_config.migrations_paths || Migrator.migrations_paths
end

#new_connection ⇒ Object

:nodoc:



883
884
885
886
887
888
889
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 883

def new_connection # :nodoc:
  connection = db_config.new_connection
  connection.pool = self
  connection
rescue ConnectionNotEstablished => ex
  raise ex.set_pool(self)
end

#num_available_in_queue ⇒ Object

:nodoc:



857
858
859
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 857

def num_available_in_queue # :nodoc:
  @available.size
end

#num_waiting_in_queue ⇒ Object

:nodoc:



853
854
855
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 853

def num_waiting_in_queue # :nodoc:
  @available.num_waiting
end

#permanent_lease? ⇒ Boolean

:nodoc:

Returns:

  • (Boolean) 


362
363
364
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 362

def permanent_lease? # :nodoc:
  connection_lease.sticky.nil?
end

#pin_connection!(lock_thread) ⇒ Object

:nodoc:



366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 366

def pin_connection!(lock_thread) # :nodoc:
  @pinned_connection ||= (connection_lease&.connection || checkout)
  @pinned_connections_depth += 1

  # 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.lock_thread = ActiveSupport::IsolatedExecutionState.context if lock_thread
  @pinned_connection.pinned = true
  @pinned_connection.verify! # eagerly validate the connection
  @pinned_connection.begin_transaction joinable: false, _lazy: false
end

#pool_transaction_isolation_level ⇒ Object 



891
892
893
894
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 891

def pool_transaction_isolation_level
  isolation_level_key = "activerecord_pool_transaction_isolation_level_#{db_config.name}"
  ActiveSupport::IsolatedExecutionState[isolation_level_key]
end

#pool_transaction_isolation_level=(isolation_level) ⇒ Object 



896
897
898
899
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 896

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

#preconnect ⇒ Object

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.



810
811
812
813
814
815
816
817
818
819
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 810

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

#prepopulate ⇒ Object

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



776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 776

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 }
      new_conn.allow_preconnect = true
      checkin(new_conn)
    end
  end
end

#reap ⇒ Object

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.



704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 704

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

#reaper_lock(&block) ⇒ Object

:nodoc:



577
578
579
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 577

def reaper_lock(&block) # :nodoc:
  @reaper_lock.synchronize(&block)
end

#recycle! ⇒ Object

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



841
842
843
844
845
846
847
848
849
850
851
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 841

def recycle!
  synchronize do
    return if self.discarded?

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

  retire_old_connections
end

#release_connection(existing_lease = nil) ⇒ Object

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.



431
432
433
434
435
436
437
438
439
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 431

def release_connection(existing_lease = nil)
  return if self.discarded?

  if conn = connection_lease.release
    checkin conn
    return true
  end
  false
end

#remove(conn) ⇒ Object

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



672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 672

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

#retire_old_connections(max_age = @max_age) ⇒ Object 



797
798
799
800
801
802
803
804
805
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 797

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

#schedule_query(future_result) ⇒ Object

:nodoc:



878
879
880
881
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 878

def schedule_query(future_result) # :nodoc:
  @async_executor.post { future_result.execute_or_skip }
  Thread.pass
end

#schema_cache ⇒ Object 



317
318
319
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 317

def schema_cache
  @schema_cache ||= BoundSchemaReflection.new(schema_reflection, self)
end

#schema_migration ⇒ Object

:nodoc:



334
335
336
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 334

def schema_migration # :nodoc:
  SchemaMigration.new(self)
end

#schema_reflection=(schema_reflection) ⇒ Object 



321
322
323
324
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 321

def schema_reflection=(schema_reflection)
  pool_config.schema_reflection = schema_reflection
  @schema_cache = nil
end

#stat ⇒ Object

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 }



864
865
866
867
868
869
870
871
872
873
874
875
876
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 864

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

#unpin_connection! ⇒ Object

:nodoc:



382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 382

def unpin_connection! # :nodoc:
  raise "There isn't a pinned connection #{object_id}" unless @pinned_connection

  clean = true
  @pinned_connection.lock.synchronize do
    @pinned_connections_depth -= 1
    connection = @pinned_connection
    @pinned_connection = nil if @pinned_connections_depth.zero?

    if connection.transaction_open?
      connection.rollback_transaction
    else
      # Something committed or rolled back the transaction
      clean = false
      connection.reset!
    end

    if @pinned_connection.nil?
      connection.pinned = false
      connection.steal!
      connection.lock_thread = nil
      checkin(connection)
    end
  end

  clean
end

#with_connection(prevent_permanent_checkout: false) ⇒ Object

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.



450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 450

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

#with_pool_transaction_isolation_level(isolation_level, transaction_open, &block) ⇒ Object

:nodoc:



471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
 
# File 'lib/active_record/connection_adapters/abstract/connection_pool.rb', line 471

def with_pool_transaction_isolation_level(isolation_level, transaction_open, &block) # :nodoc:
  if !ActiveRecord.default_transaction_isolation_level.nil?
    begin
      if transaction_open && self.pool_transaction_isolation_level != ActiveRecord.default_transaction_isolation_level
        raise ActiveRecord::TransactionIsolationError, "cannot set default isolation level while transaction is open"
      end

      old_level = self.pool_transaction_isolation_level
      self.pool_transaction_isolation_level = isolation_level
      yield
    ensure
      self.pool_transaction_isolation_level = old_level
    end
  else
    yield
  end
end