Class: ActiveRecord::ConnectionAdapters::ConnectionPool

Connection pool base class for managing ActiveRecord 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.

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 ActiveRecord 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 ActiveRecord when used in conjunction with ActionPack‘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.

Connections in the pool are actually AbstractAdapter objects (or objects compatible with AbstractAdapter‘s interface).

Options

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

pool: number indicating size of connection pool (default 5)
wait_timeout: number of seconds to block and wait for a connection before giving up and raising a timeout error (default 5 seconds).

Methods

checkin checkout clear_reloadable_connections! clear_stale_cached_connections! connected? connection disconnect! new release_connection with_connection

Attributes

spec [R]

Public Class methods

new(spec)

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.

The default ConnectionPool maximum size is 5.

[Source]

    # File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 66
66:       def initialize(spec)
67:         @spec = spec
68:         # The cache of reserved connections mapped to threads
69:         @reserved_connections = {}
70:         # The mutex used to synchronize pool access
71:         @connection_mutex = Monitor.new
72:         @queue = @connection_mutex.new_cond
73:         # default 5 second timeout
74:         @timeout = spec.config[:wait_timeout] || 5
75:         # default max pool size to 5
76:         @size = (spec.config[:pool] && spec.config[:pool].to_i) || 5
77:         @connections = []
78:         @checked_out = []
79:       end

Public Instance methods

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]

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 199
199:       def checkin(conn)
200:         @connection_mutex.synchronize do
201:           conn.run_callbacks :checkin
202:           @checked_out.delete conn
203:           @queue.signal
204:         end
205:       end

checkout()

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 an existing connection, or by creating a new connection. If the maximum number of connections for this pool has already been reached, but the pool is empty (i.e. they‘re all being used), then this method will wait until a thread has checked in a connection. The wait time is bounded however: if no connection can be checked out within the timeout specified for this pool, then a ConnectionTimeoutError exception will be raised.

Returns: an AbstractAdapter object.

Raises:

ConnectionTimeoutError: no connection can be obtained from the pool within the timeout period.

[Source]

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 173
173:       def checkout
174:         # Checkout an available connection
175:         conn = @connection_mutex.synchronize do
176:           if @checked_out.size < @connections.size
177:             checkout_existing_connection
178:           elsif @connections.size < @size
179:             checkout_new_connection
180:           end
181:         end
182:         return conn if conn
183: 
184:         # No connections available; wait for one
185:         @connection_mutex.synchronize do
186:           if @queue.wait(@timeout)
187:             checkout_existing_connection
188:           else
189:             raise ConnectionTimeoutError, "could not obtain a database connection within #{@timeout} seconds.  The pool size is currently #{@size}, perhaps you need to increase it?"
190:           end
191:         end
192:       end

clear_reloadable_connections!()

Clears the cache which maps classes

[Source]

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 129
129:       def clear_reloadable_connections!
130:         @reserved_connections.each do |name, conn|
131:           checkin conn
132:         end
133:         @reserved_connections = {}
134:         @connections.each do |conn|
135:           conn.disconnect! if conn.requires_reloading?
136:         end
137:         @connections = []
138:       end

clear_stale_cached_connections!()

Return any checked-out connections back to the pool by threads that are no longer alive.

[Source]

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 151
151:       def clear_stale_cached_connections!
152:         remove_stale_cached_threads!(@reserved_connections) do |name, conn|
153:           checkin conn
154:         end
155:       end

connected?()

Returns true if a connection has already been opened.

[Source]

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 112
112:       def connected?
113:         !@connections.empty?
114:       end

connection()

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

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

[Source]

    # File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 86
86:       def connection
87:         if conn = @reserved_connections[current_connection_id]
88:           conn
89:         else
90:           @reserved_connections[current_connection_id] = checkout
91:         end
92:       end

disconnect!()

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

[Source]

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 117
117:       def disconnect!
118:         @reserved_connections.each do |name,conn|
119:           checkin conn
120:         end
121:         @reserved_connections = {}
122:         @connections.each do |conn|
123:           conn.disconnect!
124:         end
125:         @connections = []
126:       end

release_connection()

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

[Source]

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 97
 97:       def release_connection
 98:         conn = @reserved_connections.delete(current_connection_id)
 99:         checkin conn if conn
100:       end

with_connection() {|conn| ...}

Reserve a connection, and yield it to a block. Ensure the connection is checked back in when finished.

[Source]

     # File vendor/rails/activerecord/lib/active_record/connection_adapters/abstract/connection_pool.rb, line 104
104:       def with_connection
105:         conn = checkout
106:         yield conn
107:       ensure
108:         checkin conn
109:       end