more warnings

diff --git a/doc/build/orm/session.rst b/doc/build/orm/session.rst
index d5cc21e82ac2f1718945ea4ab8bbb949aedbe7a3..3406894dec8ac73e37db64892d270761c3a553b0 100644 (file)
--- a/doc/build/orm/session.rst
+++ b/doc/build/orm/session.rst
@@ -1295,6 +1295,7 @@ things like unique constraint exceptions::
             print "Skipped record %s" % record
     session.commit()
 
+.. _session_autocommit:
 
 Autocommit Mode
 ---------------
@@ -1309,16 +1310,21 @@ results have been iterated.   The :meth:`.Session.flush` operation
 still occurs within the scope of a single transaction, though this transaction
 is closed out after the :meth:`.Session.flush` operation completes.
 
-"autocommit" mode should **not be considered for general use**.   While
-very old versions of SQLAlchemy standardized on this mode, the modern
-:class:`.Session` benefits highly from being given a clear point of transaction
-demarcation via :meth:`.Session.rollback` and :meth:`.Session.commit`.
-The autoflush action can safely emit SQL to the database as needed without
-implicitly producing permanent effects, the contents of attributes
-are expired only when a logical series of steps has completed.   If the
-:class:`.Session` were to be used in pure "autocommit" mode without
-an ongoing transaction, these features should be disabled, that is,
-``autoflush=False, expire_on_commit=False``.
+.. warning::
+
+    "autocommit" mode should **not be considered for general use**.
+    If used, it should always be combined with the usage of
+    :meth:`.Session.begin` and :meth:`.Session.commit`, to ensure
+    a transaction demarcation.
+
+    Executing queries outside of a demarcated transaction is a legacy mode
+    of usage, and can in some cases lead to concurrent connection
+    checkouts.
+
+    In the absense of a demarcated transaction, the :class:`.Session`
+    cannot make appropriate decisions as to when autoflush should
+    occur nor when auto-expiration should occur, so these features
+    should be disabled with ``autoflush=False, expire_on_commit=False``.
 
 Modern usage of "autocommit" is for framework integrations that need to control
 specifically when the "begin" state occurs.  A session which is configured with

diff --git a/lib/sqlalchemy/orm/session.py b/lib/sqlalchemy/orm/session.py
index e4cb90847985edbfb756cc3784efc649f52291b6..16c882a412c354056d8e3f935f3f1a3b6e32eb5e 100644 (file)
--- a/lib/sqlalchemy/orm/session.py
+++ b/lib/sqlalchemy/orm/session.py
@@ -457,22 +457,29 @@ class Session(_SessionClassMethods):
         generate a :class:`.Session`-producing callable with a given
         set of arguments.
 
-        :param autocommit: Defaults to ``False``. When ``True``, the
-          ``Session`` does not keep a persistent transaction running, and
+        :param autocommit:
+
+          .. warning::
+
+             The autocommit flag is **not for general use**, and if it is used,
+             queries should only be invoked within the span of a
+             :meth:`.Session.begin` / :meth:`.Session.commit` pair.   Executing
+             queries outside of a demarcated transaction is a legacy mode
+             of usage, and can in some cases lead to concurrent connection
+             checkouts.
+
+          Defaults to ``False``. When ``True``, the
+          :class:`.Session` does not keep a persistent transaction running, and
           will acquire connections from the engine on an as-needed basis,
           returning them immediately after their use. Flushes will begin and
           commit (or possibly rollback) their own transaction if no
           transaction is present. When using this mode, the
-          `session.begin()` method may be used to begin a transaction
-          explicitly.
-
-          Leaving it on its default value of ``False`` means that the
-          ``Session`` will acquire a connection and begin a transaction the
-          first time it is used, which it will maintain persistently until
-          ``rollback()``, ``commit()``, or ``close()`` is called. When the
-          transaction is released by any of these methods, the ``Session``
-          is ready for the next usage, which will again acquire and maintain
-          a new connection/transaction.
+          :meth:`.Session.begin` method is used to explicitly start
+          transactions.
+
+          .. seealso::
+
+            :ref:`session_autocommit`
 
         :param autoflush: When ``True``, all query operations will issue a
            ``flush()`` call to this ``Session`` before proceeding. This is a