psycopg2.pool -- Connections pooling

.. sectionauthor:: Daniele Varrazzo daniele.varrazzo@gmail.com

.. index:: pair: Connection; Pooling

.. module:: psycopg2.pool

Creating new PostgreSQL connections can be an expensive operation. This module offers a few pure Python classes implementing simple connection pooling directly in the client application.

.. class:: AbstractConnectionPool(minconn, maxconn, *args, **kwargs)

Base class implementing generic key-based pooling code.

New *minconn* connections are created automatically. The pool will support
a maximum of about *maxconn* connections.  *\*args* and *\*\*kwargs* are
passed to the `~psycopg2.connect()` function.

The following methods are expected to be implemented by subclasses:

.. method:: getconn(key=None)

    Get a free connection from the pool.

    The *key* parameter is optional: if used, the connection will be
    associated to the key and calling `!getconn()` with the same key again
    will return the same connection.

.. method:: putconn(conn, key=None, close=False)

    Put away a connection.

    If *close* is `!True`, discard the connection from the pool.
    *key* should be used consistently with `getconn()`.

.. method:: closeall

    Close all the connections handled by the pool.

    Note that all the connections are closed, including ones
    eventually in use by the application.

The following classes are AbstractConnectionPool subclasses ready to be used.

.. autoclass:: SimpleConnectionPool

.. note:: This pool class is useful only for single-threaded applications.

.. index:: Multithread; Connection pooling

.. autoclass:: ThreadedConnectionPool

.. note:: This pool class can be safely used in multi-threaded applications.