Mike Bayer committed dd9f5d5

add glossary, "release" term

  • Participants
  • Parent commits f21b992
  • Branches rel_0_7

Comments (0)

Files changed (5)

File doc/build/core/connections.rst

 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
-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.

File doc/build/core/pooling.rst

 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`::

File doc/build/glossary.rst

+.. _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`

File doc/build/orm/session.rst

 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.
 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.
 ``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)

File doc/build/static/docs.css

     padding: 0px 10px;
+dl.glossary > dt {
+  font-weight:bold;
+  font-size:1.1em;
 dt:target, span.highlight {