Cross reference do_connect() event w/ creator

two questions today involving creator / do_connect,
do_connect is not well known enough, ensure docs are present
and prominent.

Change-Id: I85d518b9fc7b9b069a18010969abefa360134fe9

3 files changed, 35 insertions, 2 deletions

diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst
index d672392c1..1fd66ec8c 100644
--- a/doc/build/core/engines.rst
+++ b/doc/build/core/engines.rst
@@ -244,8 +244,9 @@ may convert its type from string to its proper type.
 
     db = create_engine('postgresql://scott:tiger@localhost/test', connect_args = {'argument1':17, 'argument2':'bar'})
 
-The most customizable connection method of all is to pass a ``creator``
-argument, which specifies a callable that returns a DBAPI connection:
+The two methods that are the most customizable include using the
+:paramref:`_sa.create_engine.creator` parameter, which specifies a callable that returns a
+DBAPI connection:
 
 .. sourcecode:: python+sql
 
@@ -254,6 +255,22 @@ argument, which specifies a callable that returns a DBAPI connection:
 
     db = create_engine('postgresql://', creator=connect)
 
+Alternatively, the :meth:`_events.DialectEvents.do_connect` hook may be
+used on an existing engine which allows full replacement of the connection
+approach, given connection arguments::
+
+
+    from sqlalchemy import event
+
+    db = create_engine('postgresql://scott:tiger@localhost/test')
+
+    @event.listens_for(db, "do_connect")
+    def receive_do_connect(dialect, conn_rec, cargs, cparams):
+        # cargs and cparams can be modified in place...
+        cparams['password'] = 'new password'
+
+        # alternatively, return the new DBAPI connection
+        return psycopg2.connect(*cargs, **cparams)
 
 
 .. _dbengine_logging:
diff --git a/lib/sqlalchemy/engine/create.py b/lib/sqlalchemy/engine/create.py
index dbe1e8b57..e683b6297 100644
--- a/lib/sqlalchemy/engine/create.py
+++ b/lib/sqlalchemy/engine/create.py
@@ -122,6 +122,18 @@ def create_engine(url, **kwargs):
         connections. Usage of this function causes connection
         parameters specified in the URL argument to be bypassed.
 
+        This hook is not as flexible as the newer
+        :class:`_events.DialectEvents.do_connect` hook which allows complete
+        control over how a connection is made to the database, given the full
+        set of URL arguments and state beforehand.
+
+        .. seealso::
+
+            :class:`_events.DialectEvents.do_connect` - event hook that allows
+            full control over DBAPI connection mechanics.
+
+            :ref:`custom_dbapi_args`
+
     :param echo=False: if True, the Engine will log all statements
         as well as a ``repr()`` of their parameter lists to the default log
         handler, which defaults to ``sys.stdout`` for output.   If set to the
diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py
index 759f7f2bd..293c7afdd 100644
--- a/lib/sqlalchemy/engine/events.py
+++ b/lib/sqlalchemy/engine/events.py
@@ -758,6 +758,10 @@ class DialectEvents(event.Events):
 
         .. versionadded:: 1.0.3
 
+        .. seealso::
+
+            :ref:`custom_dbapi_args`
+
         """
 
     def do_executemany(self, cursor, statement, parameters, context):