From: Mike Bayer Date: Tue, 22 Aug 2017 20:50:19 +0000 (-0400) Subject: - modernize the mysql connection timeout docs X-Git-Tag: origin~47 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=2db525614371de011b2c65a41a8b342b15865f3c;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git - modernize the mysql connection timeout docs Change-Id: Icb0474509539c1eb7536544749f2a48b4972078a (cherry picked from commit 4ce46fb0a085c1cc739e21881cc25567e663f8dc) --- diff --git a/doc/build/core/pooling.rst b/doc/build/core/pooling.rst index 257cd44203..a23420390d 100644 --- a/doc/build/core/pooling.rst +++ b/doc/build/core/pooling.rst @@ -161,6 +161,8 @@ Connection pools support an event interface that allows hooks to execute upon first connect, upon each new connection, and upon checkout and checkin of connections. See :class:`.PoolEvents` for details. +.. _pool_disconnects: + Dealing with Disconnects ------------------------ diff --git a/doc/build/faq/connections.rst b/doc/build/faq/connections.rst index d2e33f3c57..40bef6a50a 100644 --- a/doc/build/faq/connections.rst +++ b/doc/build/faq/connections.rst @@ -42,18 +42,22 @@ in the query string of the URL:: "MySQL Server has gone away" ---------------------------- -There are two major causes for this error: - -1. The MySQL client closes connections which have been idle for a set period -of time, defaulting to eight hours. This can be avoided by using the ``pool_recycle`` -setting with :func:`.create_engine`, described at :ref:`mysql_connection_timeouts`. - -2. Usage of the MySQLdb :term:`DBAPI`, or a similar DBAPI, in a non-threadsafe manner, or in an otherwise -inappropriate way. The MySQLdb connection object is not threadsafe - this expands -out to any SQLAlchemy system that links to a single connection, which includes the ORM -:class:`.Session`. For background -on how :class:`.Session` should be used in a multithreaded environment, -see :ref:`session_faq_threadsafe`. +The primary cause of this error is that the MySQL connection has timed out +and has been closed by the server. The MySQL server closes connections +which have been idle a period of time which defaults to eight hours. +To accommodate this, the immediate setting is to enable the +:paramref:`.create_engine.pool_recycle` setting, which will ensure that a +connection which is older than a set amount of seconds will be discarded +and replaced with a new connection when it is next checked out. + +For the more general case of accommodating database restarts and other +temporary loss of connectivity due to network issues, connections that +are in the pool may be recycled in response to more generalized disconnect +detection techniques. The section :ref:`:ref:`pool_disconnects` provides +background on both "pessimistic" (e.g. pre-ping) and "optimistic" +(e.g. graceful recovery) techniques. Modern SQLAlchemy tends to favor +the "pessimistic" approach. + Why does SQLAlchemy issue so many ROLLBACKs? -------------------------------------------- diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py index 1781f9bb71..d6701aeae4 100644 --- a/lib/sqlalchemy/dialects/mysql/base.py +++ b/lib/sqlalchemy/dialects/mysql/base.py @@ -23,19 +23,26 @@ supported in any given server release. .. _mysql_connection_timeouts: -Connection Timeouts -------------------- +Connection Timeouts and Disconnects +----------------------------------- MySQL features an automatic connection close behavior, for connections that -have been idle for eight hours or more. To circumvent having this issue, use -the ``pool_recycle`` option which controls the maximum age of any connection:: +have been idle for a fixed period of time, defaulting to eight hours. +To circumvent having this issue, use +the :paramref:`.create_engine.pool_recycle` option which ensures that +a connection will be discarded and replaced with a new one if it has been +present in the pool for a fixed number of seconds:: engine = create_engine('mysql+mysqldb://...', pool_recycle=3600) -.. seealso:: +For more comprehensive disconnect detection of pooled connections, including +accommodation of server restarts and network issues, a pre-ping approach may +be employed. See :ref:`pool_disconnects` for current approaches. - :ref:`pool_setting_recycle` - full description of the pool recycle feature. +.. seealso:: + :ref:`pool_disconnects` - Background on several techniques for dealing + with timed out connections as well as database restarts. .. _mysql_storage_engines: diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py index 32e84c53f5..da70b5187e 100644 --- a/lib/sqlalchemy/engine/__init__.py +++ b/lib/sqlalchemy/engine/__init__.py @@ -382,6 +382,10 @@ def create_engine(*args, **kwargs): this is configurable with the MySQLDB connection itself and the server configuration as well). + .. seealso:: + + :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