From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Sun, 5 Jul 2020 14:28:20 +0000 (-0400)
Subject: Document pyodbc built-in pooling
X-Git-Tag: rel_1_4_0b1~241
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=9204b6610c9667ba2e4f73440339d2f520631777;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Document pyodbc built-in pooling

PyODBC apparently pools connections by default and this
is a module-wide setting only.    Documenent that this happens
and how to disable it.

Fixes: #5440
Change-Id: I415bda7beb2211c66991b6c804b0ddb4d79e427f
---

diff --git a/lib/sqlalchemy/dialects/mssql/pyodbc.py b/lib/sqlalchemy/dialects/mssql/pyodbc.py
index 6cf45e7b8e..14eb0adc7c 100644
--- a/lib/sqlalchemy/dialects/mssql/pyodbc.py
+++ b/lib/sqlalchemy/dialects/mssql/pyodbc.py
@@ -70,6 +70,32 @@ illustrated below using ``urllib.parse.quote_plus``::
 
     engine = create_engine("mssql+pyodbc:///?odbc_connect=%s" % params)
 
+Pyodbc Pooling / connection close behavior
+------------------------------------------
+
+PyODBC uses internal `pooling
+<https://github.com/mkleehammer/pyodbc/wiki/The-pyodbc-Module#pooling>`_ by
+default, which means connections will be longer lived than they are within
+SQLAlchemy itself.  As SQLAlchemy has its own pooling behavior, it is often
+preferable to disable this behavior.  This behavior can only be disabled
+globally at the PyODBC module level, **before** any connections are made::
+
+    import pyodbc
+
+    pyodbc.pooling = False
+
+    # don't use the engine before pooling is set to False
+    engine = create_engine("mssql+pyodbc://user:pass@dsn")
+
+If this variable is left at its default value of ``True``, **the application
+will continue to maintain active database connections**, even when the
+SQLAlchemy engine itself fully discards a connection or if the engine is
+disposed.
+
+.. seealso::
+
+    `pooling <https://github.com/mkleehammer/pyodbc/wiki/The-pyodbc-Module#pooling>`_ -
+    in the PyODBC documentation.
 
 Driver / Unicode Support
 -------------------------