psycopg2-pool’s documentation

This package provides a better connection pool implementation than the one contained in the psycopg2.pool module (see issue #563).

This project is released under the same license as psycopg2, the LGPLv3.

psycopg2_pool

This module implements connection pooling, which is needed because PostgreSQL requires separate TCP connections for concurrent sessions.

exception psycopg2_pool.PoolError

class psycopg2_pool.ConnectionPool(minconn=1, maxconn=inf, idle_timeout=600, **connect_kwargs)

A pool of psycopg2:connection objects.

minconn

The minimum number of connections to keep in the pool. By default one connection is opened when the pool is created.

maxconn

The maximum number of connections in the pool. By default the pool will attempt to open as many connections as requested.

idle_timeout

How many seconds to keep an idle connection before closing it. The default value causes idle connections to be closed after 10 minutes (approximately, it depends on putconn() being called).

connect_kwargs

The keyword arguments to pass to psycopg2.connect(). If the dsn argument isn’t specified, then it’s set to an empty string by default.

The following attributes are internal, they’re documented here to provide insight into how the pool works.

connections_in_use

The set of connections that have been checked out of the pool through getconn(). Type: weakref.WeakSet.

idle_connections

The pool of unused connections, last in first out. Type: collections.deque.

return_times

A timestamp is stored in this dict when a connection is added to idle_connections. That timestamp is used in getconn() to compute how long the connection stayed idle in the pool. Type: dict.

This class provides two main methods (getconn() and putconn()), plus another one that you probably don’t need (clear()).

getconn()

Get a connection from the pool.

If there is no idle connection available, then a new one is opened; unless there are already maxconn connections open, then a PoolError exception is raised.

Any connection that is broken, or has been idle for more than idle_timeout seconds, is closed and discarded.

putconn(conn)

Return a connection to the pool.

You should always return a connection to the pool, even if you’ve closed it. That being said, the pool only holds weak references to connections returned by getconn(), so they should be garbage collected even if you fail to return them.

clear()

Close and discard all idle connections in the pool (regardless of the values of minconn and idle_timeout).

This method could be useful if you have periods of high activity that result in many connections being opened, followed by prolonged periods with zero activity (no calls to getconn() or putconn()), and you care about closing those extraneous connections during the inactivity period. It’s up to you to call this method in that case.

Alternatively you may want to run a cron task to close idle connections from the server.

class psycopg2_pool.ThreadSafeConnectionPool(**kwargs)

This subclass of ConnectionPool uses a threading.RLock object to ensure that its methods are thread safe.

getconn()

See ConnectionPool.getconn().

putconn(conn)

See ConnectionPool.putconn().

clear()

See ConnectionPool.clear().