Don't link on_connect to first_connect event handler

Adjusted the dialect initialization process such that the
:meth:`_engine.Dialect.on_connect` is not called a second time on the first
connection.   The hook is called first, then the
:meth:`_engine.Dialect.initialize` is called if that connection is the
first for that dialect, then no more events are called.   This eliminates
the two calls to the "on_connect" function which can produce very difficult
debugging situations.

Fixes: #5497
Change-Id: Icefc2e884e30ee7b4ac84b99dc54bf992a6085e3

4 files changed, 26 insertions, 13 deletions

diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py
index 985a12fa0..dc895ee15 100644
--- a/lib/sqlalchemy/engine/create.py
+++ b/lib/sqlalchemy/engine/create.py
@@ -627,9 +627,9 @@ def create_engine(url, **kwargs):
                 )
                 if conn is None:
                     return
+
                 do_on_connect(conn)
 
-            event.listen(pool, "first_connect", on_connect)
             event.listen(pool, "connect", on_connect)
 
         def first_connect(dbapi_connection, connection_record):
@@ -640,9 +640,17 @@ def create_engine(url, **kwargs):
             dialect.initialize(c)
             dialect.do_rollback(c.connection)
 
-        event.listen(
-            pool, "first_connect", first_connect, _once_unless_exception=True
-        )
+        if do_on_connect:
+            event.listen(
+                pool, "connect", first_connect, _once_unless_exception=True
+            )
+        else:
+            event.listen(
+                pool,
+                "first_connect",
+                first_connect,
+                _once_unless_exception=True,
+            )
 
     dialect_cls.engine_created(engine)
     if entrypoint is not dialect_cls:
diff --git a/lib/sqlalchemy/engine/default.py b/lib/sqlalchemy/engine/default.py
index 8d3c5de15..c76f820f9 100644
--- a/lib/sqlalchemy/engine/default.py
+++ b/lib/sqlalchemy/engine/default.py
@@ -120,6 +120,8 @@ class DefaultDialect(interfaces.Dialect):
     max_identifier_length = 9999
     _user_defined_max_identifier_length = None
 
+    isolation_level = None
+
     # length at which to truncate
     # the name of an index.
     # Usually None to indicate
diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py
index 1baef29af..7d51ab159 100644
--- a/lib/sqlalchemy/engine/interfaces.py
+++ b/lib/sqlalchemy/engine/interfaces.py
@@ -208,6 +208,9 @@ class Dialect(object):
         The initialize() method of the base dialect should be called via
         super().
 
+        .. note:: as of SQLAlchemy 1.4, this method is called **before**
+           any :meth:`_engine.Dialect.on_connect` hooks are called.
+
         """
 
         pass
@@ -745,16 +748,13 @@ class Dialect(object):
         isolation modes, Unicode modes, etc.
 
         The "do_on_connect" callable is invoked by using the
-        :meth:`_events.PoolEvents.first_connect` and
         :meth:`_events.PoolEvents.connect` event
-        hooks, then unwrapping the DBAPI connection and passing it into the
-        callable.  The reason it is invoked for both events is so that any
-        dialect-level initialization that occurs upon first connection, which
-        also makes use of the :meth:`_events.PoolEvents.first_connect` method,
-        will
-        proceed after this hook has been called. This currently means the
-        hook is in fact called twice for the very first  connection in which a
-        dialect creates; and once per connection afterwards.
+        hook, then unwrapping the DBAPI connection and passing it into the
+        callable.
+
+        .. versionchanged:: 1.4 the on_connect hook is no longer called twice
+           for the first connection of a dialect.  The on_connect hook is still
+           called before the :meth:`_engine.Dialect.initialize` method however.
 
         If None is returned, no event listener is generated.
 
diff --git a/lib/sqlalchemy/testing/engines.py b/lib/sqlalchemy/testing/engines.py
index 280e6901e..bb137cb32 100644
--- a/lib/sqlalchemy/testing/engines.py
+++ b/lib/sqlalchemy/testing/engines.py
@@ -336,6 +336,9 @@ class DBAPIProxyCursor(object):
     def executemany(self, stmt, params, **kw):
         return self.cursor.executemany(stmt, params, **kw)
 
+    def __iter__(self):
+        return iter(self.cursor)
+
     def __getattr__(self, key):
         return getattr(self.cursor, key)