diff options
| -rw-r--r-- | doc/build/core/engines.rst | 21 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/create.py | 12 | ||||
| -rw-r--r-- | lib/sqlalchemy/engine/events.py | 4 |
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): |