Release 1.6 Mikhail Denisenko

python-tds DocumentationRelease 1.6

Mikhail Denisenko

Dec 09, 2017

Contents

1 pytds – main module 3

2 pytds.login – login with NTLM and SSPI 9

3 pytds.tz – timezones 11

4 pytds.extensions – Extensions to the DB API 134.1 Isolation level constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

5 Connection to Mirrored Servers 15

6 Table Valued Parameters 17

7 Testing 19

8 Indices and tables 21

Python Module Index 23

i

ii

python-tds Documentation, Release 1.6

Pytds is the top to bottom pure Python TDS implementation, that means cross-platform, and no dependency on ADOor FreeTDS. It supports large parameters (>4000 characters), MARS, timezones, new date types (datetime2, date,time, datetimeoffset). Even though it is implemented in Python performance is comparable to ADO and FreeTDSbindings.

It also supports Python 3.

Contents

Contents 1


2 Contents

CHAPTER 1

pytds – main module

DB-SIG compliant module for communicating with MS SQL servers

class pytds.ConnectionConnection object, this object should be created by calling connect()

as_dictInstructs all cursors this connection creates to return results as a dictionary rather than a tuple.

autocommitThe current state of autocommit on the connection.

autocommit_stateAn alias for autocommit, provided for compatibility with pymssql

chunk_handlerReturns current chunk handler Default is MemoryChunkedHandler()

close()Close connection to an MS SQL Server.

This function tries to close the connection and free all memory used. It can be called more than once in arow. No exception is raised in this case.

commit()Commit transaction which is currently in progress.

cursor()Return cursor object that can be used to make queries and fetch results from the database.

isolation_levelIsolation level for transactions, for possible values see Isolation level constants

See also:

SET TRANSACTION ISOLATION LEVEL in MSSQL documentation

mars_enabledWhether MARS is enabled or not on connection

3

http://msdn.microsoft.com/en-us/library/ms173763.aspx


product_versionVersion of the MSSQL server

rollback()Roll back transaction which is currently in progress.

set_autocommit(value)An alias for autocommit, provided for compatibility with ADO dbapi

tds_versionVersion of tds protocol that is being used by this connection

class pytds.Cursor(conn, session, tzinfo_factory)This class represents a database cursor, which is used to issue queries and fetch results from a database connec-tion.

callproc(procname, parameters=())Call a stored procedure with the given name.

Parameters

• procname (str) – The name of the procedure to call

• parameters (sequence) – The optional parameters for the procedure

cancel()Cancel current statement

close()Closes the cursor. The cursor is unusable from this point.

connectionProvides link back to Connection of this cursor

copy_to(file, table_or_view, sep=’\t’, columns=None, check_constraints=False, fire_triggers=False,keep_nulls=False, kb_per_batch=None, rows_per_batch=None, order=None, tablock=False,schema=None, null_string=None)

Experimental. Efficiently load data to database from file using BULK INSERT operation

Parameters

• file – Source file-like object, should be in csv format

• table_or_view (str) – Destination table or view in the database

Optional parameters:

Parameters

• sep (str) – Separator used in csv file

• columns (list) – List of column names in target table to insert to, if not provided willinsert into all columns

• check_constraints (bool) – Check table constraints for incoming data

• fire_triggers (bool) – Enable or disable triggers for table

• keep_nulls (bool) – If enabled null values inserted as-is, instead of inserting defaultvalue for column

• kb_per_batch (int) – Kilobytes per batch can be used to optimize performance, seeMSSQL server documentation for details

• rows_per_batch (int) – Rows per batch can be used to optimize performance, seeMSSQL server documentation for details

4 Chapter 1. pytds – main module


• order (list) – The ordering of the data in source table. List of columns with ASC orDESC suffix. E.g. ['order_id ASC', 'name DESC'] Can be used to optimizeperformance, see MSSQL server documentation for details

• tablock – Enable or disable table lock for the duration of bulk load

• schema – Name of schema for table or view, if not specified default schema will be used

• null_string – String that should be interpreted as a NULL when reading the CSV file.

descriptionCursor description, see http://legacy.python.org/dev/peps/pep-0249/#description

execute(operation, params=())Execute the query

Parameters operation (str) – SQL statement

execute_scalar(query_string, params=None)This method sends a query to the MS SQL Server to which this object instance is connected, then returnsfirst column of first row from result. An exception is raised on failure. If there are pending

results or rows prior to executing this command, they are silently discarded.

This method accepts Python formatting. Please see execute_query() for details.

This method is useful if you want just a single value, as in:

conn.execute_scalar('SELECT COUNT(*) FROM employees')

This method works in the same way as iter(conn).next()[0]. Remaining rows, if any, can still beiterated after calling this method.

fetchall()Fetches all remaining rows

fetchmany(size=None)Fetches next multiple rows

Parameters size – Maximum number of rows to return, default value is cursor.arraysize

Returns List of rows

fetchone()Fetches next row, or None if there are no more rows

get_proc_return_status()Last stored proc result

messagesMessages generated by server, see http://legacy.python.org/dev/peps/pep-0249/#cursor-messages

native_descriptiontodo document

nextset()Move to next recordset in batch statement, all rows of current recordset are discarded if present.

Returns true if successful or None when there are no more recordsets

return_valueAlias to get_proc_return_status()

rowcountNumber of rows affected by previous statement

5

http://legacy.python.org/dev/peps/pep-0249/#description

http://legacy.python.org/dev/peps/pep-0249/#cursor-messages


Returns -1 if this information was not supplied by MSSQL server

static setinputsizes(sizes=None)This method does nothing, as permitted by DB-API specification.

static setoutputsize(size=None, column=0)This method does nothing, as permitted by DB-API specification.

spidMSSQL Server’s SPID (session id)

pytds.connect(dsn=None, database=None, user=None, password=None, timeout=None, lo-gin_timeout=15, as_dict=None, appname=None, port=None, tds_version=1946157060,autocommit=False, blocksize=4096, use_mars=False, auth=None, readonly=False,load_balancer=None, use_tz=None, bytes_to_unicode=True, row_strategy=None,failover_partner=None, server=None, cafile=None, validate_host=True,enc_login_only=False)

Opens connection to the database

Parameters

• dsn (string) – SQL server host and instance: <host>[<instance>]

• failover_partner (string) – secondary database host, used if primary is not acces-sible

• database (string) – the database to initially connect to

• user (string) – database user to connect as

• password (string) – user’s password

• timeout (int) – query timeout in seconds, default 0 (no timeout)

• login_timeout (int) – timeout for connection and login in seconds, default 15

• as_dict (boolean) – whether rows should be returned as dictionaries instead of tuples.

• appname (string) – Set the application name to use for the connection

• port (int) – the TCP port to use to connect to the server

• tds_version (int) – Maximum TDS version to use, should only be used for testing

• autocommit (bool) – Enable or disable database level autocommit

• blocksize (int) – Size of block for the TDS protocol, usually should not be used

• use_mars (bool) – Enable or disable MARS

• auth – An instance of authentication method class, e.g. Ntlm or Sspi

• readonly (bool) – Allows to enable read-only mode for connection, only supported byMSSQL 2012, earlier versions will ignore this parameter

• load_balancer – An instance of load balancer class to use, if not provided will not useload balancer

• use_tz – Provides timezone for naive database times, if not provided date and time willbe returned in naive format

• bytes_to_unicode (bool) – If true single byte database strings will be converted tounicode Python strings, otherwise will return strings as bytes without conversion.

• row_strategy (function of list of column names returning rowfactory) – strategy used to create rows, determines type of returned rows, canbe custom or one of: tuple_row_strategy(), list_row_strategy(),



dict_row_strategy(), namedtuple_row_strategy(),recordtype_row_strategy()

• cafile (str) – Name of the file containing trusted CAs in PEM format, if provided willenable TLS

• validate_host (bool) – Host name validation during TLS connection is enabled bydefault, if you disable it you will be vulnerable to MitM type of attack.

• enc_login_only (bool) – Allows you to scope TLS encryption only to an authentica-tion portion. This means that anyone who can observe traffic on your network will be ableto see all your SQL requests and potentially modify them.

Returns An instance of Connection

pytds.dict_row_strategy(column_names)Dict row strategy, rows returned as dictionaries

pytds.list_row_strategy(column_names)List row strategy, rows returned as lists

pytds.namedtuple_row_strategy(column_names)Namedtuple row strategy, rows returned as named tuples

Column names that are not valid Python identifiers will be replaced with col<number>_

pytds.recordtype_row_strategy(column_names)Recordtype row strategy, rows returned as recordtypes

Column names that are not valid Python identifiers will be replaced with col<number>_

pytds.tuple_row_strategy(column_names)Tuple row strategy, rows returned as tuples, default

7



CHAPTER 2

pytds.login – login with NTLM and SSPI

class pytds.login.NtlmAuth(user_name, password)NTLM authentication, uses Python implementation

Parameters

• user_name (str) – User name

• password (str) – User password

class pytds.login.SspiAuth(user_name=’‘, password=’‘, server_name=’‘, port=None, spn=None)SSPI authentication

Platform Windows

Required parameters are server_name and port or spn

Parameters

• user_name (str) – User name, if not provided current security context will be used

• password (str) – User password, if not provided current security context will be used

• server_name (str) – MSSQL server host name

• port (int) – MSSQL server port

• spn (str) – Service name

9


10 Chapter 2. pytds.login – login with NTLM and SSPI

CHAPTER 3

pytds.tz – timezones

class pytds.tz.FixedOffsetTimezone(offset, name=None)Fixed offset in minutes east from UTC.

class pytds.tz.UTC

11


12 Chapter 3. pytds.tz – timezones

CHAPTER 4

pytds.extensions – Extensions to the DB API

4.1 Isolation level constants

pytds.extensions.ISOLATION_LEVEL_READ_UNCOMMITTEDTransaction can read uncommitted data

pytds.extensions.ISOLATION_LEVEL_READ_COMMITTEDTransaction can read only committed data, will block on attempt to read modified uncommitted data

pytds.extensions.ISOLATION_LEVEL_REPEATABLE_READTransaction will place lock on read records, other transactions will block trying to modify such records

pytds.extensions.ISOLATION_LEVEL_SERIALIZABLETransaction will lock tables to prevent other transactions from inserting new data that would match selectedrecordsets

pytds.extensions.ISOLATION_LEVEL_SNAPSHOTAllows non-blocking consistent reads on a snapshot for transaction without blocking other transactions changes

13


14 Chapter 4. pytds.extensions – Extensions to the DB API

CHAPTER 5

Connection to Mirrored Servers

When MSSQL server is setup with mirroring you should connect to it using two parameters of pytds.connect(),one parameter is server this should be a main server and parameter failover_partner should be a mirrorserver. See also MSDN article.

15

http://msdn.microsoft.com/en-us/library/ms175484.aspx


16 Chapter 5. Connection to Mirrored Servers

CHAPTER 6

Table Valued Parameters

Here is example of using TVP:

with conn.cursor() as cur:cur.execute('CREATE TYPE dbo.CategoryTableType AS TABLE ( CategoryID int,

→˓CategoryName nvarchar(50) )')conn.commit()

tvp = pytds.TableValuedParam(type_name='dbo.CategoryTableType', rows=rows_gen())cur.execute('SELECT * FROM %s', (tvp,))

17


18 Chapter 6. Table Valued Parameters

CHAPTER 7

Testing

To run tests you need to have tox installed. Also you would want to have different versions of Python, you can usepyenv to install those.

At a minimun you should set HOST environment variable to point to your SQL server, e.g.:

export HOST=mysqlserver

it could also specify SQL server named instance, e.g.:

export HOST=mysqlserver\\myinstance

By default tests will use SQL server integrated authentication using user sa with password sa and database test. Youcan specify different user name, password, database with SQLUSER, SQLPASSWORD, DATABASE environmentvariables.

To enable testing NTLM authentication you should specify NTLM_USER and NTLM_PASSWORD environmentvariables.

Once environment variables are setup you can run tests by running command:

tox

Test configuration stored in tox.ini file at the root of the repository.

19


20 Chapter 7. Testing

CHAPTER 8

Indices and tables

• genindex

• modindex

• search

21


22 Chapter 8. Indices and tables

Python Module Index

llogin (Unix, Windows, MacOSX), 9

ppytds, 3pytds.extensions, 13pytds.login, 9pytds.tz, 11

23


24 Python Module Index

Index

Aas_dict (pytds.Connection attribute), 3autocommit (pytds.Connection attribute), 3autocommit_state (pytds.Connection attribute), 3

Ccallproc() (pytds.Cursor method), 4cancel() (pytds.Cursor method), 4chunk_handler (pytds.Connection attribute), 3close() (pytds.Connection method), 3close() (pytds.Cursor method), 4commit() (pytds.Connection method), 3connect() (in module pytds), 6Connection (class in pytds), 3connection (pytds.Cursor attribute), 4copy_to() (pytds.Cursor method), 4Cursor (class in pytds), 4cursor() (pytds.Connection method), 3

Ddescription (pytds.Cursor attribute), 5dict_row_strategy() (in module pytds), 7

Eexecute() (pytds.Cursor method), 5execute_scalar() (pytds.Cursor method), 5

Ffetchall() (pytds.Cursor method), 5fetchmany() (pytds.Cursor method), 5fetchone() (pytds.Cursor method), 5FixedOffsetTimezone (class in pytds.tz), 11

Gget_proc_return_status() (pytds.Cursor method), 5

Iisolation_level (pytds.Connection attribute), 3

ISOLATION_LEVEL_READ_COMMITTED (in mod-ule pytds.extensions), 13

ISOLATION_LEVEL_READ_UNCOMMITTED (inmodule pytds.extensions), 13

ISOLATION_LEVEL_REPEATABLE_READ (in mod-ule pytds.extensions), 13

ISOLATION_LEVEL_SERIALIZABLE (in modulepytds.extensions), 13

ISOLATION_LEVEL_SNAPSHOT (in modulepytds.extensions), 13

Llist_row_strategy() (in module pytds), 7login (module), 9

Mmars_enabled (pytds.Connection attribute), 3messages (pytds.Cursor attribute), 5

Nnamedtuple_row_strategy() (in module pytds), 7native_description (pytds.Cursor attribute), 5nextset() (pytds.Cursor method), 5NtlmAuth (class in pytds.login), 9

Pproduct_version (pytds.Connection attribute), 3pytds (module), 3pytds.extensions (module), 13pytds.login (module), 9pytds.tz (module), 11

Rrecordtype_row_strategy() (in module pytds), 7return_value (pytds.Cursor attribute), 5rollback() (pytds.Connection method), 4rowcount (pytds.Cursor attribute), 5

Sset_autocommit() (pytds.Connection method), 4

25


setinputsizes() (pytds.Cursor static method), 6setoutputsize() (pytds.Cursor static method), 6spid (pytds.Cursor attribute), 6SspiAuth (class in pytds.login), 9

Ttds_version (pytds.Connection attribute), 4tuple_row_strategy() (in module pytds), 7

UUTC (class in pytds.tz), 11

26 Index

Documents

Release 1.6 Mikhail Denisenko