⤌ Back

Module pool

Pool — a managed connection pool for high-throughput PostgreSQL access. The pool maintains a set of pre-opened Connection objects and lends them to callers on demand. When a query completes (or a cursor is closed), the connection is automatically returned to the pool rather than being closed.

Design

• Min connections — pool.min connections are created eagerly at startup and kept alive indefinitely.
• Max connections — the pool will never open more than pool.max connections simultaneously.
• Idle eviction — connections idle for longer than pool.idleTimeoutMillis are closed and removed from the pool.
• Acquire timeout — if no connection is available within pool.acquireTimeoutMillis, a PoolExhaustedError is raised.

Example

import postgres { Pool }
var db = Pool({
  host:     'localhost',
  database: 'mydb',
  user:     'alice',
  password: 'secret',
  pool: {
    min:                  2,
    max:                  10,
    idleTimeoutMillis:    30000,
    acquireTimeoutMillis: 5000,
  }
})
var result = db.query('select count(*) from events')
echo result.rows[0]
db.close()

Classes

class Pool

A connection pool that manages a set of Connection objects.

This module implements the following decorated functions: @to_string.

Properties

• min_size (number)

  Minimum number of connections kept open in the pool.

• max_size (number)

  Maximum number of connections the pool may open simultaneously.

• idle_timeout (number)

  Milliseconds a connection may sit idle before being closed. 0 = never evict.

• acquire_timeout (number)

  Milliseconds to wait for an available connection before raising PoolExhaustedError.

Methods

• Pool(options) (Constructor)

  Creates a connection pool.

  Parameters

  • dict options Connection options merged with pool-specific options.

    Pool-specific options (nested under pool key)

    Key	Type	Default	Description
    min	number	1	Minimum connections.
    max	number	10	Maximum connections.
    idleTimeoutMillis	number	30000	Idle eviction timeout (ms).
    acquireTimeoutMillis	number	5000	Max wait for a connection (ms).

• query(sql, options)

  Acquires a connection from the pool, executes the query, then returns the connection to the pool. Supports the same options dict as Connection.query(). When options.cursor is true, the returned cursor's close() method triggers the connection return.You must call cursor.close().*

  Parameters

  • string sql The SQL statement.

  • dict options Query options.

• execute(sql, options)

  Acquires a connection, executes a statement, and releases the connection.

  Parameters

  • string sql SQL statement.

  • dict options Query options.

• with_connection(fn)

  Runs fn(connection) with an acquired connection, automatically releasing it afterwards. Useful for multi-statement transactions.

  db.with_connection(@(conn) {
    conn.begin()
    conn.execute('update accounts set balance = balance - 100 where id = \$1',
                 { params: [42] })
    conn.execute('update accounts set balance = balance + 100 where id = \$1',
                 { params: [99] })
    conn.commit()
  })
  

  Parameters

  • function fn Callback receiving the Connection object.

• close()

  Closes all connections in the pool (both idle and active) and shuts the pool down. Any in-flight queries will complete normally; subsequent calls to query() will raise ClosedError.

• stats()

  Returns a snapshot of pool statistics.