- A warning is emitted if the ``isolation_level`` parameter is used

with :meth:`.Connection.execution_options` when a :class:`.Transaction`
is in play; DBAPIs and/or SQLAlchemy dialects such as psycopg2,
MySQLdb may implicitly rollback or commit the transaction, or
not change the setting til next transaction, so this is never safe.
- Added new parameter :paramref:`.Session.connection.execution_options`
which may be used to set up execution options on a :class:`.Connection`
when it is first checked out, before the transaction has begun.
This is used to set up options such as isolation level on the
connection before the transaction starts.
- added new documentation section
detailing best practices for setting transaction isolation with
sessions.
fixes #3296

1 files changed, 25 insertions, 3 deletions

diff --git a/test/engine/test_transaction.py b/test/engine/test_transaction.py
index 0f5bb4cb5..b7d900917 100644
--- a/test/engine/test_transaction.py
+++ b/test/engine/test_transaction.py
@@ -1,8 +1,6 @@
 from sqlalchemy.testing import eq_, assert_raises, \
-    assert_raises_message, ne_
+    assert_raises_message, ne_, expect_warnings
 import sys
-import time
-import threading
 from sqlalchemy import event
 from sqlalchemy.testing.engines import testing_engine
 from sqlalchemy import create_engine, MetaData, INT, VARCHAR, Sequence, \
@@ -1361,6 +1359,30 @@ class IsolationLevelTest(fixtures.TestBase):
         c3.close()
         c4.close()
 
+    def test_warning_in_transaction(self):
+        eng = testing_engine()
+        c1 = eng.connect()
+        with expect_warnings(
+            "Connection is already established with a Transaction; "
+            "setting isolation_level may implicitly rollback or commit "
+            "the existing transaction, or have no effect until next "
+            "transaction"
+        ):
+            with c1.begin():
+                c1 = c1.execution_options(
+                    isolation_level=self._non_default_isolation_level()
+                )
+
+                eq_(
+                    eng.dialect.get_isolation_level(c1.connection),
+                    self._non_default_isolation_level()
+                )
+        # stays outside of transaction
+        eq_(
+            eng.dialect.get_isolation_level(c1.connection),
+            self._non_default_isolation_level()
+        )
+
     def test_per_statement_bzzt(self):
         assert_raises_message(
             exc.ArgumentError,