Commits

Mike Bayer  committed f6f4a8f

more warnings

  • Participants
  • Parent commits a730364

Comments (0)

Files changed (2)

File doc/build/orm/session.rst

             print "Skipped record %s" % record
     session.commit()
 
+.. _session_autocommit:
 
 Autocommit Mode
 ---------------
 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

File lib/sqlalchemy/orm/session.py

         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