diff options
Diffstat (limited to 'doc/build/errors.rst')
| -rw-r--r-- | doc/build/errors.rst | 60 |
1 files changed, 5 insertions, 55 deletions
diff --git a/doc/build/errors.rst b/doc/build/errors.rst index 2b163ec26..2318d39b0 100644 --- a/doc/build/errors.rst +++ b/doc/build/errors.rst @@ -536,68 +536,18 @@ sooner. .. _error_8s2b: -Can't reconnect until invalid transaction is rolled back ----------------------------------------------------------- +Can't reconnect until invalid transaction is rolled back. Please rollback() fully before proceeding +----------------------------------------------------------------------------------------------------- This error condition refers to the case where a :class:`_engine.Connection` was invalidated, either due to a database disconnect detection or due to an explicit call to :meth:`_engine.Connection.invalidate`, but there is still a -transaction present that was initiated by the :meth:`_engine.Connection.begin` -method. When a connection is invalidated, any :class:`_engine.Transaction` +transaction present that was initiated either explicitly by the :meth:`_engine.Connection.begin` +method, or due to the connection automatically beginning a transaction as occurs +in the 2.x series of SQLAlchemy when any SQL statements are emitted. When a connection is invalidated, any :class:`_engine.Transaction` that was in progress is now in an invalid state, and must be explicitly rolled back in order to remove it from the :class:`_engine.Connection`. -.. _error_8s2a: - -This connection is on an inactive transaction. Please rollback() fully before proceeding ------------------------------------------------------------------------------------------- - -This error condition was added to SQLAlchemy as of version 1.4. The error -refers to the state where a :class:`_engine.Connection` is placed into a -transaction using a method like :meth:`_engine.Connection.begin`, and then a -further "marker" transaction is created within that scope; the "marker" -transaction is then rolled back using :meth:`.Transaction.rollback` or closed -using :meth:`.Transaction.close`, however the outer transaction is still -present in an "inactive" state and must be rolled back. - -The pattern looks like:: - - engine = create_engine(...) - - connection = engine.connect() - transaction1 = connection.begin() - - # this is a "sub" or "marker" transaction, a logical nesting - # structure based on "real" transaction transaction1 - transaction2 = connection.begin() - transaction2.rollback() - - # transaction1 is still present and needs explicit rollback, - # so this will raise - connection.execute(text("select 1")) - -Above, ``transaction2`` is a "marker" transaction, which indicates a logical -nesting of transactions within an outer one; while the inner transaction -can roll back the whole transaction via its rollback() method, its commit() -method has no effect except to close the scope of the "marker" transaction -itself. The call to ``transaction2.rollback()`` has the effect of -**deactivating** transaction1 which means it is essentially rolled back -at the database level, however is still present in order to accommodate -a consistent nesting pattern of transactions. - -The correct resolution is to ensure the outer transaction is also -rolled back:: - - transaction1.rollback() - -This pattern is not commonly used in Core. Within the ORM, a similar issue can -occur which is the product of the ORM's "logical" transaction structure; this -is described in the FAQ entry at :ref:`faq_session_rollback`. - -The "subtransaction" pattern is to be removed in SQLAlchemy 2.0 so that this -particular programming pattern will no longer be available and this -error message will no longer occur in Core. - .. _error_dbapi: DBAPI Errors |