From: Mike Bayer Date: Sun, 30 Sep 2012 15:56:55 +0000 (-0400) Subject: add glossary, "release" term X-Git-Tag: rel_0_7_9~6 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=46e218e5f178fcccae87257fcb25c09d0654f95c;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git add glossary, "release" term --- diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index d051ccac9a..2658fedd18 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -64,7 +64,7 @@ an UPDATE statement (without any returned rows), releases cursor resources immediately upon construction. When the :meth:`~.Connection.close` method is called, the referenced DBAPI -connection is returned to the connection pool. From the perspective +connection is :term:`released` to the connection pool. From the perspective of the database itself, nothing is actually "closed", assuming pooling is in use. The pooling mechanism issues a ``rollback()`` call on the DBAPI connection so that any transactional state or locks are removed, and @@ -441,7 +441,7 @@ call :meth:`.Engine.contextual_connect`:: call_operation3(conn) conn.close() -Calling :meth:`~.Connection.close` on the "contextual" connection does not release +Calling :meth:`~.Connection.close` on the "contextual" connection does not :term:`release` its resources until all other usages of that resource are closed as well, including that any ongoing transactions are rolled back or committed. diff --git a/doc/build/core/pooling.rst b/doc/build/core/pooling.rst index 6b566639ff..ceac0f21b0 100644 --- a/doc/build/core/pooling.rst +++ b/doc/build/core/pooling.rst @@ -139,6 +139,14 @@ when it is garbage collected, though it's not deterministic in Python that this occurs immediately (though it is typical with cPython). +The ``close()`` step also performs the important step of calling the +``rollback()`` method of the DBAPI connection. This is so that any +existing transaction on the connection is removed, not only ensuring +that no existing state remains on next usage, but also so that table +and row locks are released as well as that any isolated data snapshots +are removed. This behavior can be disabled using the ``reset_on_return`` +option of :class:`.Pool`. + A particular pre-created :class:`.Pool` can be shared with one or more engines by passing it to the ``pool`` argument of :func:`.create_engine`:: diff --git a/doc/build/glossary.rst b/doc/build/glossary.rst new file mode 100644 index 0000000000..8c40fcec00 --- /dev/null +++ b/doc/build/glossary.rst @@ -0,0 +1,38 @@ +.. _glossary: + +======== +Glossary +======== + +.. note:: + + The Glossary is a brand new addition to the documentation. While + sparse at the moment we hope to fill it up with plenty of new + terms soon! + +.. glossary:: + + release + releases + released + This term refers to when an operation terminates some state which + corresponds to a service of some kind. Specifically within + SQLAlchemy, it usually refers to a reference to a database connection, + and typically a transaction associated with that connection. + When we say "the operation releases transactional resources", + it means basically that we have a :class:`.Connection` object + and we are calling the :meth:`.Connection.close` method, which has + the effect of the underlying DBAPI connection being returned + to the connection pool. The connection pool, when it receives + a connection for return, unconditionally calls the ``rollback()`` + method of the DBAPI connection, so that any locks or data snapshots within + that connection are removed. Then, the connection is either + stored locally in memory, still connected but not in a transaction, + for subsequent reuse by another operation, or it is closed + immediately, depending on the configuration and current + state of the connection pool. + + .. seealso:: + + :ref:`pooling_toplevel` + diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst index 98be1ede6c..c02842396f 100644 --- a/doc/build/orm/session.rst +++ b/doc/build/orm/session.rst @@ -870,7 +870,7 @@ Closing ------- The :meth:`~.Session.close` method issues a -:meth:`~.Session.expunge_all`, and releases any +:meth:`~.Session.expunge_all`, and :term:`releases` any transactional/connection resources. When connections are returned to the connection pool, transactional state is rolled back as well. @@ -1211,8 +1211,7 @@ rolled back corresponding to the invocation of the also call the :meth:`.TwoPhaseTransaction.prepare` method on all transactions if applicable. When the transactional state is completed after a rollback or commit, the :class:`.Session` -releases all :class:`.Transaction` and :class:`.Connection` resources (which has the effect -of returning DBAPI connections to the connection pool of each :class:`.Engine`), +:term:`releases` all :class:`.Transaction` and :class:`.Connection` resources, and goes back to the "begin" state, which will again invoke new :class:`.Connection` and :class:`.Transaction` objects as new requests to emit SQL statements are received. @@ -1328,7 +1327,7 @@ specifically when the "begin" state occurs. A session which is configured with ``autocommit=True`` may be placed into the "begin" state using the :meth:`.Session.begin` method. After the cycle completes upon :meth:`.Session.commit` or :meth:`.Session.rollback`, -connection and transaction resources are released and the :class:`.Session` +connection and transaction resources are :term:`released` and the :class:`.Session` goes back into "autocommit" mode, until :meth:`.Session.begin` is called again:: Session = sessionmaker(bind=engine, autocommit=True) diff --git a/doc/build/static/docs.css b/doc/build/static/docs.css index 33f715af11..23c3abe632 100644 --- a/doc/build/static/docs.css +++ b/doc/build/static/docs.css @@ -348,6 +348,10 @@ dl.exception > dt padding: 0px 10px; } +dl.glossary > dt { + font-weight:bold; + font-size:1.1em; +} dt:target, span.highlight { background-color:#FBE54E;