From: Gord Thompson <gord@gordthompson.com>
Date: Mon, 20 Apr 2020 19:16:20 +0000 (-0600)
Subject: Fix typo in pymssql documentation; minor clarification
X-Git-Tag: rel_1_3_17~21
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f9499e5f3661ce5055db61add9b8742072112908;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git

Fix typo in pymssql documentation; minor clarification

Change-Id: I4aaf0627d2f1ccae82c2eb41db9ec219d73ce4ea
(cherry picked from commit 469e786c9d77e182ef403ba18e7f19b3f58fe3bf)
---

diff --git a/lib/sqlalchemy/dialects/mssql/pymssql.py b/lib/sqlalchemy/dialects/mssql/pymssql.py
index b8b3bf67de..cfcfb4afc3 100644
--- a/lib/sqlalchemy/dialects/mssql/pymssql.py
+++ b/lib/sqlalchemy/dialects/mssql/pymssql.py
@@ -10,14 +10,28 @@
     :name: pymssql
     :dbapi: pymssql
     :connectstring: mssql+pymssql://<username>:<password>@<freetds_name>/?charset=utf8
-    :url: http://pymssql.org/
 
 pymssql is a Python module that provides a Python DBAPI interface around
-`FreeTDS <http://www.freetds.org/>`_.  Compatible builds are available for
-Linux, MacOSX and Windows platforms.
+`FreeTDS <http://www.freetds.org/>`_.
+
+Modern versions of this driver worked very well with SQL Server and FreeTDS
+from Linux and were highly recommended. However, pymssql is currently
+unmaintained and has fallen behind the progress of the Microsoft ODBC driver in
+its support for newer features of SQL Server. The latest official release of
+pymssql at the time of this document is version 2.1.4 (August, 2018) and it
+lacks support for:
+
+1. table-valued parameters (TVPs),
+2. ``datetimeoffset`` columns using timezone-aware ``datetime`` objects
+   (values are sent and retrieved as strings), and
+3. encrypted connections (e.g., to Azure SQL), when pymssql is installed from
+   the pre-built wheels. Support for encrypted connections requires building
+   pymssql from source, which can be a nuisance, especially under Windows.
+
+The above features are all supported by mssql+pyodbc when using Microsoft's
+ODBC Driver for SQL Server (msodbcsql), which is now available for Windows,
+(several flavors of) Linux, and macOS.
 
-Modern versions of this driver work very well with SQL Server and
-FreeTDS from Linux and is highly recommended.
 
 """  # noqa
 import re