- modernize the mysql connection timeout docs

Change-Id: Icb0474509539c1eb7536544749f2a48b4972078a
(cherry picked from commit 4ce46fb0a085c1cc739e21881cc25567e663f8dc)

4 files changed, 35 insertions, 18 deletions

diff --git a/doc/build/core/pooling.rst b/doc/build/core/pooling.rst
index 257cd4420..a23420390 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 d2e33f3c5..40bef6a50 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 1781f9bb7..d6701aeae 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 32e84c53f..da70b5187 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