Class | Sequel::ConnectionPool
In: | lib/sequel/connection_pool.rb
Parent: | Object

A ConnectionPool manages access to database connections by keeping multiple connections and giving threads exclusive access to each connection.

### Methods

allocated available_connections created_count disconnect hold new size

### Attributes

connection_proc | [RW] | The proc used to create a new database connection.
disconnection_proc | [RW] | The proc used to disconnect a database connection.
max_size | [R] | The maximum number of connections.
mutex | [R] | The mutex that protects access to the other internal variables. You must use this if you want to manipulate the variables safely.

### Public Class methods

new(opts = {}, &block)

Constructs a new pool with a maximum size. If a block is supplied, it is used to create new connections as they are needed.

      pool = ConnectionPool.new(:max_connections=>10) {MyConnection.new(opts)}

The connection creation proc can be changed at any time by assigning a Proc to pool#connection_proc.

      pool = ConnectionPool.new(:max_connections=>10)
      pool.connection_proc = proc {MyConnection.new(opts)}

The connection pool takes the following options:

- :disconnection_proc - The proc called when removing connections from the pool.
- :max_connections - The maximum number of connections the connection pool will open (default 4)
- :pool_convert_exceptions - Whether to convert non-StandardError based exceptions to RuntimeError exceptions (default true)
- :pool_sleep_time - The amount of time to sleep before attempting to acquire a connection again (default 0.001)
- :pool_timeout - The amount of seconds to wait to acquire a connection before raising a PoolTimeoutError (default 5)
- :servers - A hash of servers to use. Keys should be symbols. If not present, will use a single :default server. The server name symbol will be passed to the connection_proc.

[Source]

        # File lib/sequel/connection_pool.rb, line 43
    43:   def initialize(opts = {}, &block)
    44:     @max_size = Integer(opts[:max_connections] || 4)
    45:     raise(Sequel::Error, ':max_connections must be positive') if @max_size < 1
    46:     @mutex = Mutex.new
    47:     @connection_proc = block
    48:     @disconnection_proc = opts[:disconnection_proc]
    49:     @servers = [:default]
    50:     @servers += opts[:servers].keys - @servers if opts[:servers]
    51:     @available_connections = Hash.new{|h,k| h[:default]}
    52:     @allocated = Hash.new{|h,k| h[:default]}
    53:     @servers.each do |s|
    54:       @available_connections[s] = []
    55:       @allocated[s] = {}
    56:     end
    57:     @timeout = Integer(opts[:pool_timeout] || 5)
    58:     @sleep_time = Float(opts[:pool_sleep_time] || 0.001)
    59:     @convert_exceptions = opts.include?(:pool_convert_exceptions) ? opts[:pool_convert_exceptions] : true
    60:   end

### Public Instance methods

allocated(server=:default)

A hash of connections currently being used for the given server, key is the Thread, value is the connection.

[Source]

        # File lib/sequel/connection_pool.rb, line 64
    64:   def allocated(server=:default)
    65:     @allocated[server]
    66:   end

available_connections(server=:default)

An array of connections opened but not currently used, for the given server.

[Source]

        # File lib/sequel/connection_pool.rb, line 70
    70:   def available_connections(server=:default)
    71:     @available_connections[server]
    72:   end

created_count(server=:default)

The total number of connections opened for the given server, should be equal to available_connections.length + allocated.length

[Source]

        # File lib/sequel/connection_pool.rb, line 76
    76:   def created_count(server=:default)
    77:     @allocated[server].length + @available_connections[server].length
    78:   end

disconnect(&block)

Removes all connection currently available on all servers, optionally yielding each connection to the given block. This method has the effect of disconnecting from the database, assuming that no connections are currently being used. Once a connection is requested using hold, the connection pool creates new connections to the database.

[Source]

         # File lib/sequel/connection_pool.rb, line 131
    131:   def disconnect(&block)
    132:     block ||= @disconnection_proc
    133:     @mutex.synchronize do
    134:       @available_connections.each do |server, conns|
    135:         conns.each{|c| block.call(c)} if block
    136:         conns.clear
    137:       end
    138:     end
    139:   end

hold(server=:default) {|conn| ...}

Chooses the first available connection to the given server, or if none are available, creates a new connection. Passes the connection to the supplied block:

      pool.hold {|conn| conn.execute('DROP TABLE posts')}

Pool#hold is re-entrant, meaning it can be called recursively in the same thread without blocking.

If no connection is immediately available and the pool is already using the maximum number of connections, Pool#hold will block until a connection is available or the timeout expires. If the timeout expires before a connection can be acquired, a Sequel::PoolTimeout is raised.

[Source]

         # File lib/sequel/connection_pool.rb, line 95
     95:   def hold(server=:default)
     96:     begin
     97:       t = Thread.current
     98:       if conn = owned_connection(t, server)
     99:         return yield(conn)
    100:       end
    101:       begin
    102:         unless conn = acquire(t, server)
    103:           time = Time.new
    104:           timeout = time + @timeout
    105:           sleep_time = @sleep_time
    106:           sleep sleep_time
    107:           until conn = acquire(t, server)
    108:             raise(::Sequel::PoolTimeout) if Time.new > timeout
    109:             sleep sleep_time
    110:           end
    111:         end
    112:         yield conn
    113:       rescue Sequel::DatabaseDisconnectError => dde
    114:         remove(t, conn, server) if conn
    115:         raise
    116:       ensure
    117:         @mutex.synchronize{release(t, server)} if conn && !dde
    118:       end
    119:     rescue StandardError
    120:       raise
    121:     rescue Exception => e
    122:       raise(@convert_exceptions ? RuntimeError.new(e.message) : e)
    123:     end
    124:   end

size(server=:default)

Alias for created_count

[Validate]