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
(cherry picked from commit 88ae6a6cdd9f37d65ea212736f1229bb62d677a9)

diff --git a/doc/build/core/engines.rst b/doc/build/core/engines.rst
index 67469bbee92c062f23c7aa8362119dd73fa0b25d..7b97740d4ad88fd80341d047615e876edcc3ee50 100644 (file)
--- a/doc/build/core/engines.rst
+++ b/doc/build/core/engines.rst
@@ -242,8 +242,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
 
@@ -252,6 +253,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/__init__.py b/lib/sqlalchemy/engine/__init__.py
index 594b2251b278ffdf9f206d6efee6d6927d34bcf2..fbf6cf70a959b8ba8000f52a39ffeab4ccce5922 100644 (file)
--- a/lib/sqlalchemy/engine/__init__.py
+++ b/lib/sqlalchemy/engine/__init__.py
@@ -162,6 +162,18 @@ def create_engine(*args, **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/events.py b/lib/sqlalchemy/events.py
index 572488ed7bcc1858614574dacef55945be3dbedb..3a758d60363f3cd8b62be6f575c59c387f49f554 100644 (file)
--- a/lib/sqlalchemy/events.py
+++ b/lib/sqlalchemy/events.py
@@ -1262,6 +1262,10 @@ class DialectEvents(event.Events):
 
         .. versionadded:: 1.0.3
 
+        .. seealso::
+
+            :ref:`custom_dbapi_args`
+
         """
 
     def do_executemany(self, cursor, statement, parameters, context):