mirror of
https://github.com/psycopg/psycopg2.git
synced 2024-11-10 19:16:34 +03:00
Added documentation for the 'pool' module.
This commit is contained in:
parent
3636bc4201
commit
4412826556
|
@ -85,14 +85,15 @@ When should I save and re-use a cursor as opposed to creating a new one as neede
|
|||
suggestion is to almost always create a new cursor and dispose old ones as
|
||||
soon as the data is not required anymore (call :meth:`~cursor.close` on
|
||||
them.) The only exception are tight loops where one usually use the same
|
||||
cursor for a whole bunch of INSERTs or UPDATEs.
|
||||
cursor for a whole bunch of :sql:`INSERT`\s or :sql:`UPDATE`\s.
|
||||
|
||||
When should I save and re-use a connection as opposed to creating a new one as needed?
|
||||
Creating a connection can be slow (think of SSL over TCP) so the best
|
||||
practice is to create a single connection and keep it open as long as
|
||||
required. It is also good practice to rollback or commit frequently (even
|
||||
after a single SELECT statement) to make sure the backend is never left
|
||||
"idle in transaction".
|
||||
after a single :sql:`SELECT` statement) to make sure the backend is never
|
||||
left "idle in transaction". See also :mod:`psycopg2.pool` for lightweight
|
||||
connection pooling.
|
||||
|
||||
What are the advantages or disadvantages of using named cursors?
|
||||
The only disadvantages is that they use up resources on the server and
|
||||
|
|
|
@ -38,6 +38,7 @@ PostgreSQL arrays.
|
|||
advanced
|
||||
extensions
|
||||
tz
|
||||
pool
|
||||
extras
|
||||
errorcodes
|
||||
faq
|
||||
|
|
62
doc/src/pool.rst
Normal file
62
doc/src/pool.rst
Normal file
|
@ -0,0 +1,62 @@
|
|||
`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 into 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 :func:`~psycopg2.connect` function.
|
||||
|
||||
The following methods are expected to be implemented by subclasses:
|
||||
|
||||
.. method:: getconn(key=None)
|
||||
|
||||
Get a free connection and assign it to *key* if not ``None``.
|
||||
|
||||
.. method:: putconn(conn, key=None)
|
||||
|
||||
Put away a connection.
|
||||
|
||||
.. method:: closeall
|
||||
|
||||
Close all the connections handled by the pool.
|
||||
|
||||
Notice that all the connections are closed, including ones
|
||||
eventually in use by the application.
|
||||
|
||||
|
||||
The following classes are :class:`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.
|
||||
|
||||
|
||||
.. autoclass:: PersistentConnectionPool
|
||||
|
||||
.. note::
|
||||
|
||||
This pool class is mostly designed to interact with Zope and probably
|
||||
not useful in generic applications.
|
||||
|
|
@ -197,9 +197,9 @@ class PersistentConnectionPool(AbstractConnectionPool):
|
|||
"""A pool that assigns persistent connections to different threads.
|
||||
|
||||
Note that this connection pool generates by itself the required keys
|
||||
using the current thread id. This means that untill a thread put away
|
||||
using the current thread id. This means that until a thread puts away
|
||||
a connection it will always get the same connection object by successive
|
||||
.getconn() calls. This also means that a thread can't use more than one
|
||||
:meth:`!getconn` calls. This also means that a thread can't use more than one
|
||||
single connection from the pool.
|
||||
"""
|
||||
|
||||
|
|
Loading…
Reference in New Issue
Block a user