python-tds Documentation

Transcription

1 python-tds Documentation Release 1.6 Mikhail Denisenko Dec 09, 2017

2

3 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 Isolation level constants Connection to Mirrored Servers 15 6 Table Valued Parameters 17 7 Testing 19 8 Indices and tables 21 Python Module Index 23 i

4 ii

5 Pytds is the top to bottom pure Python TDS implementation, that means cross-platform, and no dependency on ADO or 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 FreeTDS bindings. It also supports Python 3. Contents Contents 1

6 2 Contents

7 CHAPTER 1 pytds main module DB-SIG compliant module for communicating with MS SQL servers class pytds.connection Connection object, this object should be created by calling connect() as_dict Instructs all cursors this connection creates to return results as a dictionary rather than a tuple. autocommit The current state of autocommit on the connection. autocommit_state An alias for autocommit, provided for compatibility with pymssql chunk_handler Returns 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 a row. 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_level Isolation level for transactions, for possible values see Isolation level constants See also: SET TRANSACTION ISOLATION LEVEL in MSSQL documentation mars_enabled Whether MARS is enabled or not on connection 3

8 product_version Version 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_version Version 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 connection. 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. connection Provides 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 will insert 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 default value for column kb_per_batch (int) Kilobytes per batch can be used to optimize performance, see MSSQL server documentation for details rows_per_batch (int) Rows per batch can be used to optimize performance, see MSSQL server documentation for details 4 Chapter 1. pytds main module

9 order (list) The ordering of the data in source table. List of columns with ASC or DESC suffix. E.g. ['order_id ASC', 'name DESC'] Can be used to optimize performance, 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. description Cursor description, see 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 returns first 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 be iterated 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 messages Messages generated by server, see native_description todo 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_value Alias to get_proc_return_status() rowcount Number of rows affected by previous statement 5

10 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. spid MSSQL Server s SPID (session id) pytds.connect(dsn=none, database=none, user=none, password=none, timeout=none, login_timeout=15, as_dict=none, appname=none, port=none, tds_version= , 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 accessible 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 by MSSQL 2012, earlier versions will ignore this parameter load_balancer An instance of load balancer class to use, if not provided will not use load balancer use_tz Provides timezone for naive database times, if not provided date and time will be returned in naive format bytes_to_unicode (bool) If true single byte database strings will be converted to unicode Python strings, otherwise will return strings as bytes without conversion. row_strategy (function of list of column names returning row factory) strategy used to create rows, determines type of returned rows, can be custom or one of: tuple_row_strategy(), list_row_strategy(), 6 Chapter 1. pytds main module

11 dict_row_strategy(), recordtype_row_strategy() namedtuple_row_strategy(), cafile (str) Name of the file containing trusted CAs in PEM format, if provided will enable TLS validate_host (bool) Host name validation during TLS connection is enabled by default, 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 authentication portion. This means that anyone who can observe traffic on your network will be able to 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

12 8 Chapter 1. pytds main module

13 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

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

15 CHAPTER 3 pytds.tz timezones class pytds.tz.fixedoffsettimezone(offset, name=none) Fixed offset in minutes east from UTC. class pytds.tz.utc 11

16 12 Chapter 3. pytds.tz timezones

17 CHAPTER 4 pytds.extensions Extensions to the DB API 4.1 Isolation level constants pytds.extensions.isolation_level_read_uncommitted Transaction can read uncommitted data pytds.extensions.isolation_level_read_committed Transaction can read only committed data, will block on attempt to read modified uncommitted data pytds.extensions.isolation_level_repeatable_read Transaction will place lock on read records, other transactions will block trying to modify such records pytds.extensions.isolation_level_serializable Transaction will lock tables to prevent other transactions from inserting new data that would match selected recordsets pytds.extensions.isolation_level_snapshot Allows non-blocking consistent reads on a snapshot for transaction without blocking other transactions changes 13

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

19 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 mirror server. See also MSDN article. 15

20 16 Chapter 5. Connection to Mirrored Servers

21 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

22 18 Chapter 6. Table Valued Parameters

23 CHAPTER 7 Testing To run tests you need to have tox installed. Also you would want to have different versions of Python, you can use pyenv 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. You can specify different user name, password, database with SQLUSER, SQLPASSWORD, DATABASE environment variables. To enable testing NTLM authentication you should specify NTLM_USER and NTLM_PASSWORD environment variables. 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

24 20 Chapter 7. Testing

25 CHAPTER 8 Indices and tables genindex modindex search 21

26 22 Chapter 8. Indices and tables

27 Python Module Index l login (Unix, Windows, MacOSX), 9 p pytds, 3 pytds.extensions, 13 pytds.login, 9 pytds.tz, 11 23

28 24 Python Module Index

29 Index A as_dict (pytds.connection attribute), 3 autocommit (pytds.connection attribute), 3 autocommit_state (pytds.connection attribute), 3 C callproc() (pytds.cursor method), 4 cancel() (pytds.cursor method), 4 chunk_handler (pytds.connection attribute), 3 close() (pytds.connection method), 3 close() (pytds.cursor method), 4 commit() (pytds.connection method), 3 connect() (in module pytds), 6 Connection (class in pytds), 3 connection (pytds.cursor attribute), 4 copy_to() (pytds.cursor method), 4 Cursor (class in pytds), 4 cursor() (pytds.connection method), 3 D description (pytds.cursor attribute), 5 dict_row_strategy() (in module pytds), 7 E execute() (pytds.cursor method), 5 execute_scalar() (pytds.cursor method), 5 F fetchall() (pytds.cursor method), 5 fetchmany() (pytds.cursor method), 5 fetchone() (pytds.cursor method), 5 FixedOffsetTimezone (class in pytds.tz), 11 G get_proc_return_status() (pytds.cursor method), 5 I isolation_level (pytds.connection attribute), 3 ISOLATION_LEVEL_READ_COMMITTED (in module pytds.extensions), 13 ISOLATION_LEVEL_READ_UNCOMMITTED (in module pytds.extensions), 13 ISOLATION_LEVEL_REPEATABLE_READ (in module pytds.extensions), 13 ISOLATION_LEVEL_SERIALIZABLE (in module pytds.extensions), 13 ISOLATION_LEVEL_SNAPSHOT (in module pytds.extensions), 13 L list_row_strategy() (in module pytds), 7 login (module), 9 M mars_enabled (pytds.connection attribute), 3 messages (pytds.cursor attribute), 5 N namedtuple_row_strategy() (in module pytds), 7 native_description (pytds.cursor attribute), 5 nextset() (pytds.cursor method), 5 NtlmAuth (class in pytds.login), 9 P product_version (pytds.connection attribute), 3 pytds (module), 3 pytds.extensions (module), 13 pytds.login (module), 9 pytds.tz (module), 11 R recordtype_row_strategy() (in module pytds), 7 return_value (pytds.cursor attribute), 5 rollback() (pytds.connection method), 4 rowcount (pytds.cursor attribute), 5 S set_autocommit() (pytds.connection method), 4 25

30 setinputsizes() (pytds.cursor static method), 6 setoutputsize() (pytds.cursor static method), 6 spid (pytds.cursor attribute), 6 SspiAuth (class in pytds.login), 9 T tds_version (pytds.connection attribute), 4 tuple_row_strategy() (in module pytds), 7 U UTC (class in pytds.tz), Index