Merge pull request #350 from pymssql/tds-version-pymssql-connect

Add tds_version parameter to pymssql.connect().

docs/ref/_mssql.rst

@@ -91,7 +91,7 @@ Functions
         SET TEXTSIZE 2147483647; -- http://msdn.microsoft.com/en-us/library/aa259190%28v=sql.80%29.aspx
 
     .. versionadded:: 2.1.1
-        The *conn_properties* argument.
+        The *conn_properties* parameter.
 
     .. versionchanged:: 2.1.1
         Before 2.1.1, the initialization queries now specified by
@@ -108,6 +108,22 @@ 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
+
+        * 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>`_)
+
 ``MSSQLConnection`` object properties
 -------------------------------------
 

docs/ref/pymssql.rst

@@ -29,53 +29,69 @@ 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)
-
-    Constructor for creating a connection to the database. Returns a
-    :class:`Connection` object.
-
-    :param server: database host
-    :type server: string
-    :param user: database user to connect as
-    :type user: string
-    :param password: user's password
-    :type password: string
-    :param database: the database to initially connect to
-    :type database: string
-    :param timeout: query timeout in seconds, default 0 (no timeout)
-    :type timeout: int
-    :param login_timeout: timeout for connection and login in seconds, default 60
-    :type login_timeout: int
-    :param charset: character set with which to connect to the database
-    :type charset: string
-    :keyword as_dict: whether rows should be returned as dictionaries instead of tuples
-    :type as_dict: boolean
-    :keyword appname: Set the application name to use for the connection
-    :type appname: string
-    :keyword port: the TCP port to use to connect to the server
-    :type port: string
-    :keyword conn_properties: SQL queries to send to the server upon connection
-                              establishment. Can be a string or another kind
-                              of iterable of strings. Default value: See
-                              :class:`_mssql.connect <_mssql.MSSQLConnection>`
-
-    .. warning::
-        Currently, setting *timeout* or *login_timeout* have a process-wide
-        effect because the FreeTDS db-lib API functions used to implement such
-        timeouts have a global effect.
-
-    .. note::
-        If you need to connect to Azure:
-
-        * Use FreeTDS 0.91 or newer
-        * Make sure FreeTDS is built with SSL support
-        * Specify the database name you are connecting to in the ``connect()`` call
-
-    .. versionadded:: 2.1.1
-        The ability to connect to Azure.
-
-    .. versionadded:: 2.1.1
-        The *conn_properties* argument.
+                      conn_properties, autocommit=False, tds_version='7.1')
+
+   Constructor for creating a connection to the database. Returns a
+   :class:`Connection` object.
+
+   :param str server: database host
+   :param str user: database user to connect as
+   :param str password: user's password
+   :param str database: the database to initially connect to
+   :param int timeout: query timeout in seconds, default 0 (no timeout)
+   :param int login_timeout: timeout for connection and login in seconds, default 60
+   :param str charset: character set with which to connect to the database
+   :keyword conn_properties: SQL queries to send to the server upon connection
+                             establishment. Can be a string or another kind of
+                             iterable of strings.  Default value: See
+                             :class:`_mssql.connect() <_mssql.MSSQLConnection>`
+   :keyword bool as_dict: whether rows should be returned as dictionaries instead of tuples
+   :keyword str appname: Set the application name to use for the connection
+   :keyword str port: the TCP port to use to connect to the server
+   :keyword bool autocommit: Whether to use default autocommiting mode or not
+   :keyword str tds_version: TDS protocol version to use.
+
+   .. warning::
+       Currently, setting *timeout* or *login_timeout* has a process-wide
+       effect because the FreeTDS db-lib API functions used to implement such
+       timeouts have a global effect.
+
+   .. note::
+       If you need to connect to Azure:
+
+       * Use FreeTDS 0.91 or newer
+       * Make sure FreeTDS is built with SSL support
+       * Specify the database name you are connecting to in the ``connect()`` call
+
+   .. versionadded:: 2.1.1
+       The ability to connect to Azure.
+
+   .. versionadded:: 2.1.1
+       The *conn_properties* parameter.
+
+   .. versionadded:: 2.1.1
+       The *autocommit* parameter.
+
+   .. 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.
+
+     This will change with pymssql 2.2.0 when
+
+     * 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>`_)
 
 .. function:: get_dbversion()
 

pymssql.pyx

@@ -579,7 +579,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):
+        host='', appname=None, port='1433', conn_properties=None, autocommit=False, tds_version='7.1'):
     """
     Constructor for creating a connection to the database. Returns a
     Connection object.
@@ -607,8 +607,10 @@ def connect(server='.', user='', password='', database='', timeout=0,
     :keyword conn_properties: SQL queries to send to the server upon connection
                               establishment. Can be a string or another kind
                               of iterable of strings
-    :keyword autocommit whether to use default autocommiting mode or not
+    :keyword autocommit: Whether to use default autocommiting mode or not
     :type autocommit: boolean
+    :keyword tds_version: TDS protocol version to use.
+    :type tds_version: string
     """
 
     # set the login timeout
@@ -631,7 +633,7 @@ def connect(server='.', user='', password='', database='', timeout=0,
     try:
         conn = _mssql.connect(server=server, user=user, password=password,
                               charset=charset, database=database,
-                              appname=appname, port=port,
+                              appname=appname, port=port, tds_version=tds_version,
                               conn_properties=conn_properties)
 
     except _mssql.MSSQLDatabaseException, e: