From d8bb208a85f6366c58426a85b3d4ec1d6e43ac6c Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Tue, 28 Aug 2018 14:58:05 -0400 Subject: [PATCH] Fix links and update verbiage for reset_on_return Change-Id: I642056b78570b44fdefe7f0874a8e4c720389f14 --- lib/sqlalchemy/engine/__init__.py | 13 +++++++------ lib/sqlalchemy/pool/base.py | 25 +++++++++++-------------- 2 files changed, 18 insertions(+), 20 deletions(-) diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py index 841dc405e7..b0d765b8ea 100644 --- a/lib/sqlalchemy/engine/__init__.py +++ b/lib/sqlalchemy/engine/__init__.py @@ -386,13 +386,14 @@ def create_engine(*args, **kwargs): :ref:`pool_setting_recycle` - :param pool_reset_on_return='rollback': set the "reset on return" - behavior of the pool, which is whether ``rollback()``, - ``commit()``, or nothing is called upon connections - being returned to the pool. See the docstring for - ``reset_on_return`` at :class:`.Pool`. + :param pool_reset_on_return='rollback': set the + :paramref:`.Pool.reset_on_return` parameter of the underlying + :class:`.Pool` object, which can be set to the values + ``"rollback"``, ``"commit"``, or ``None``. - .. versionadded:: 0.7.6 + .. seealso:: + + :paramref:`.Pool.reset_on_return` :param pool_timeout=30: number of seconds to wait before giving up on getting a connection from the pool. This is only used diff --git a/lib/sqlalchemy/pool/base.py b/lib/sqlalchemy/pool/base.py index 8551101605..7c85433d54 100644 --- a/lib/sqlalchemy/pool/base.py +++ b/lib/sqlalchemy/pool/base.py @@ -139,25 +139,22 @@ class Pool(log.Identified): any data changes present on the transaction are committed unconditionally. * ``None`` - don't do anything on the connection. - This setting should only be made on a database + This setting should generally only be made on a database that has no transaction support at all, - namely MySQL MyISAM. By not doing anything, - performance can be improved. This - setting should **never be selected** for a - database that supports transactions, - as it will lead to deadlocks and stale - state. - * ``"none"`` - same as ``None`` - - .. versionadded:: 0.9.10 + namely MySQL MyISAM; when used on this backend, performance + can be improved as the "rollback" call is still expensive on + MySQL. It is **strongly recommended** that this setting not be + used for transaction-supporting databases in conjunction with + a persistent pool such as :class:`.QueuePool`, as it opens + the possibility for connections still in a transaction to be + idle in the pool. The setting may be appropriate in the + case of :class:`.NullPool` or special circumstances where + the connection pool in use is not being used to maintain connection + lifecycle. * ``False`` - same as None, this is here for backwards compatibility. - .. versionchanged:: 0.7.6 - :paramref:`.Pool.reset_on_return` accepts ``"rollback"`` - and ``"commit"`` arguments. - :param events: a list of 2-tuples, each of the form ``(callable, target)`` which will be passed to :func:`.event.listen` upon construction. Provided here so that event listeners -- 2.47.2