Merge pull request pymssql#404 from pymssql/no-default-tds-version-value

Stop using 7.1 as default value for the TDS protocol version used in …

Author: ramiro

.travis.yml

@@ -20,6 +20,7 @@ install:
 script:
 - . dev/travis_env.sh
 - echo "\$PYMSSQL_TEST_DATABASE = \"$PYMSSQL_TEST_DATABASE\""
+- export TDSVER=7.1
 - py.test -v
 - cd docs && test -z "$(make SPHINXOPTS='-q' html 2>&1 | egrep -w 'SEVERE:|ERROR:')"
 - cd ..

ChangeLog

@@ -7,8 +7,21 @@ Version 2.2.0 - To be released
 General
 -------
 
+- Stop using 7.1 as default value for the TDS protocol version used in connections.
+
+  This is a backward incompatible change and affects connections using both
+  `pymssql` and `_mssql`.
+
+  Now you need to specify a TDS protocol version explicitly by using any of
+  the supported mechanisms (in descending order of precedence):
+
+  * Using the ``tds_version`` paramenter of ``pymssql.connect()`` and
+    ``_mssql.connect()``
+  * A ``TDSVER`` enviromnent variable (see FreeTDS documentation)
+  * A ``freetds.conf`` file (see FreeTDS documentation)
+
 - Drop support for versions of FreeTDS older than 0.91.
-- Add support for reporting TDS version 7.3 is i use via the ``tds_version``
+- Add support for reporting TDS version 7.3 is in use via the ``tds_version``
   property of a ``_mssql``-level connection.
 
 Features

docs/ref/_mssql.rst

@@ -71,7 +71,7 @@ Functions
 
     :param str port: the TCP port to use to connect to the server
 
-    :param str tds_version: TDS protocol version to ask for. Default value: '7.1'
+    :param str tds_version: TDS protocol version to ask for. Default value: ``None``
 
     :param conn_properties: SQL queries to send to the server upon connection
                             establishment. Can be a string or another kind
@@ -110,21 +110,29 @@ Functions
     .. versionadded:: 2.1.1
         The ability to connect to Azure.
 
-    .. warning::
-        The *tds_version* parameter, added in version 2.0.0, has a default value
-        of '7.1'.
-
-        This will change with pymssql 2.2.0 when
+    .. versionchanged:: 2.2.0
+        The default value of the *tds_version* parameter was changed to ``None``.
+        Between versions 2.0.0 and  2.1.2 its default value was ``'7.1'``.
 
-        * The default value will be changed to None
-        * The version of the TDS protocol to use by default won't be 7.1 anymore
-        * You won't able to rely on such default value anymore and will need to
-          either
-
-          * Specify its value explicitly or
-          * Configure it using facilities provided by FreeTDS (see `here
-            <http://www.freetds.org/userguide/freetdsconf.htm#TAB.FREETDS.CONF>`_
-            `and here <http://www.freetds.org/userguide/envvar.htm>`_)
+    .. warning::
+      The *tds_version* parameter has a default value of ``None``. This means two
+      things:
+
+      #. You can't rely anymore in the old ``'7.1'`` default value and
+      #. Now you'll need to either
+
+        * Specify its value explicitly by passing a value for this parameter or
+        * Configure it using facilities provided by FreeTDS (see `here
+          <http://www.freetds.org/userguide/freetdsconf.htm#TAB.FREETDS.CONF>`_
+          and `here <http://www.freetds.org/userguide/envvar.htm>`_)
+
+      This might look cumbersome but at the same time means you can now fully
+      configure the characteristics of a connection to SQL Server when using
+      pymssql/_mssql without using a stanza for the server in the
+      ``freetds.conf`` file or even with no ``freetds.conf`` at all. Starting
+      with pymssql version 2.0.0 and up to version 2.1.2 it was already possible
+      to set the TDS protocol version to ask for when connecting to the server
+      but version 7.1 was used if not specified.
 
 ``MSSQLConnection`` object properties
 -------------------------------------

docs/ref/pymssql.rst

@@ -29,7 +29,7 @@ Functions
 .. function:: connect(server='.', user='', password='', database='', \
                       timeout=0, login_timeout=60, charset='UTF-8', \
                       as_dict=False, host='', appname=None, port='1433',\
-                      conn_properties, autocommit=False, tds_version='7.1')
+                      conn_properties, autocommit=False, tds_version=None)
 
    Constructor for creating a connection to the database. Returns a
    :class:`Connection` object.
@@ -92,23 +92,29 @@ Functions
    .. versionadded:: 2.1.2
        The *tds_version* parameter.
 
-   .. warning::
-     The *tds_version* parameter, new in version 2.1.2, has a default value of
-     '7.1'. This is for consistency with the default value of the equally-named
-     parameter of the :class:`_mssql.connect() <_mssql.MSSQLConnection>`
-     function.
+   .. versionchanged:: 2.2.0
+       The default value of the *tds_version* parameter was changed to ``None``.
+       In version 2.1.2 its default value was ``'7.1'``.
 
-     This will change with pymssql 2.2.0 when
+   .. warning::
+     The *tds_version* parameter has a default value of ``None``. This means two
+     things:
 
-     * The default value will be changed to None
-     * The version of the TDS protocol to use by default won't be 7.1 anymore
-     * You won't able to rely on such default value anymore and will need to
-       either
+     #. You can't rely anymore in the old ``'7.1'`` default value and
+     #. Now you'll need to either
 
-       * Specify its value explicitly or
+       * Specify its value explicitly by passing a value for this parameter or
        * Configure it using facilities provided by FreeTDS (see `here
          <http://www.freetds.org/userguide/freetdsconf.htm#TAB.FREETDS.CONF>`_
-         `and here <http://www.freetds.org/userguide/envvar.htm>`_)
+         and `here <http://www.freetds.org/userguide/envvar.htm>`_)
+
+     This might look cumbersome but at the same time means you can now fully
+     configure the characteristics of a connection to SQL Server from Python
+     code when using pymssql without using a stanza for the server in the
+     ``freetds.conf`` file or even with no ``freetds.conf`` at all. Up to
+     version 2.1.1 it simply wasn't possible to control the TDS protocol
+     version, and in version 2.1.2 it was possible to set it but version 7.1 was
+     used if not specified.
 
 .. function:: get_dbversion()
 

src/_mssql.pyx

@@ -540,7 +540,7 @@ cdef class MSSQLConnection:
         self.column_types = None
 
     def __init__(self, server="localhost", user="sa", password="",
-            charset='UTF-8', database='', appname=None, port='1433', tds_version='7.1', conn_properties=None):
+            charset='UTF-8', database='', appname=None, port='1433', tds_version=None, conn_properties=None):
         log("_mssql.MSSQLConnection.__init__()")
 
         cdef LOGINREC *login
@@ -574,7 +574,8 @@ cdef class MSSQLConnection:
         DBSETLUSER(login, user_cstr)
         DBSETLPWD(login, password_cstr)
         DBSETLAPP(login, appname_cstr)
-        DBSETLVERSION(login, _tds_ver_str_to_constant(tds_version))
+        if tds_version is not None:
+            DBSETLVERSION(login, _tds_ver_str_to_constant(tds_version))
 
         # add the port to the server string if it doesn't have one already and
         # if we are not using an instance

src/pymssql.pyx

@@ -580,7 +580,7 @@ cdef class Cursor:
 
 def connect(server='.', user='', password='', database='', timeout=0,
         login_timeout=60, charset='UTF-8', as_dict=False,
-        host='', appname=None, port='1433', conn_properties=None, autocommit=False, tds_version='7.1'):
+        host='', appname=None, port='1433', conn_properties=None, autocommit=False, tds_version=None):
     """
     Constructor for creating a connection to the database. Returns a
     Connection object.

tests/test_config.py

@@ -34,6 +34,7 @@ def test_config_values(self):
             server='dontnameyourserverthis',
             user = 'bob',
             database = 'tempdb',
+            tds_version='7.1'
             )
         assert 'user_name = bob' in config_dump
         assert 'database = tempdb\n' in config_dump