add glossary, "release" term

diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst
index d051ccac9a7ce2ecfd981ffe78d08c438715798f..2658fedd18dd081be390489e8c81fab73c76e324 100644 (file)
--- 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 6b566639ffa186d2c5240e5c69c73075b9faf1c6..ceac0f21b06f352d9be29c8bc592e071f3f8a790 100644 (file)
--- 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 (file)
index 0000000..8c40fce
--- /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 98be1ede6c4692cb30314ee990c17862cc57cc3e..c02842396f805f1866fafaba41eea92ff72b16bc 100644 (file)
--- 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 33f715af11b3676dc9415f9ae0777c43c382df5d..23c3abe63254d3296a0a1b9ae51dca73b561eef6 100644 (file)
--- 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;