release 1.6 mikhail denisenko
TRANSCRIPT
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
python-tds Documentation, Release 1.6
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
python-tds Documentation, Release 1.6
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
python-tds Documentation, Release 1.6
• 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
python-tds Documentation, Release 1.6
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(),
6 Chapter 1. pytds – main module
python-tds Documentation, Release 1.6
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
python-tds Documentation, Release 1.6
8 Chapter 1. pytds – main module
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
python-tds Documentation, Release 1.6
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
python-tds Documentation, Release 1.6
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
python-tds Documentation, Release 1.6
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
python-tds Documentation, Release 1.6
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
python-tds Documentation, Release 1.6
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
python-tds Documentation, Release 1.6
20 Chapter 7. Testing
CHAPTER 8
Indices and tables
• genindex
• modindex
• search
21
python-tds Documentation, Release 1.6
22 Chapter 8. Indices and tables
Python Module Index
llogin (Unix, Windows, MacOSX), 9
ppytds, 3pytds.extensions, 13pytds.login, 9pytds.tz, 11
23
python-tds Documentation, Release 1.6
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
python-tds Documentation, Release 1.6
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