Download python-tds Documentation

python-tds Documentation
Release 1.6
Mikhail Denisenko
March 29, 2016
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
4.1 Isolation level constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
13
13
5
Connection to Mirrored Servers
15
6
Indices and tables
17
Python Module Index
19
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 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
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.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
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
3
python-tds Documentation, Release 1.6
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)
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
• 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
description
Cursor description, see http://legacy.python.org/dev/peps/pep-0249/#description
4
Chapter 1. pytds – main module
python-tds Documentation, Release 1.6
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 http://legacy.python.org/dev/peps/pep-0249/#cursor-messages
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
Returns -1 if this information was not supplied by MSSQL server
setinputsizes(sizes=None)
This method does nothing, as permitted by DB-API specification.
setoutputsize(size=None, column=0)
This method does nothing, as permitted by DB-API specification.
spid
MSSQL Server’s SPID (session id)
5
python-tds Documentation, Release 1.6
pytds.connect(dsn=None, database=None, user=None, password=None, timeout=None, login_timeout=15, as_dict=None, appname=None, port=None, tds_version=1946157060,
encryption_level=0, 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)
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
• encryption_level – Encryption level to use, not supported
• 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(),
dict_row_strategy(),
namedtuple_row_strategy(),
recordtype_row_strategy()
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
6
Chapter 1. pytds – main module
python-tds Documentation, Release 1.6
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_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
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 mirror
server. See also MSDN article.
15
python-tds Documentation, Release 1.6
16
Chapter 5. Connection to Mirrored Servers
CHAPTER 6
Indices and tables
• genindex
• modindex
• search
17
python-tds Documentation, Release 1.6
18
Chapter 6. Indices and tables
Python Module Index
l
login (Unix, Windows, MacOSX), 9
p
pytds, 3
pytds.extensions, 13
pytds.login, 9
pytds.tz, 11
19
python-tds Documentation, Release 1.6
20
Python Module Index
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), 5
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
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), 6
login (module), 9
M
mars_enabled (pytds.Connection attribute), 3
messages (pytds.Cursor attribute), 5
N
description (pytds.Cursor attribute), 4
dict_row_strategy() (in module pytds), 6
namedtuple_row_strategy() (in module pytds), 7
native_description (pytds.Cursor attribute), 5
nextset() (pytds.Cursor method), 5
NtlmAuth (class in pytds.login), 9
E
P
execute() (pytds.Cursor method), 4
execute_scalar() (pytds.Cursor method), 5
product_version (pytds.Connection attribute), 3
pytds (module), 3
pytds.extensions (module), 13
pytds.login (module), 9
pytds.tz (module), 11
D
F
fetchall() (pytds.Cursor method), 5
fetchmany() (pytds.Cursor method), 5
fetchone() (pytds.Cursor method), 5
FixedOffsetTimezone (class in pytds.tz), 11
R
get_proc_return_status() (pytds.Cursor method), 5
recordtype_row_strategy() (in module pytds), 7
return_value (pytds.Cursor attribute), 5
rollback() (pytds.Connection method), 3
rowcount (pytds.Cursor attribute), 5
I
S
G
isolation_level (pytds.Connection attribute), 3
set_autocommit() (pytds.Connection method), 3
ISOLATION_LEVEL_READ_COMMITTED (in mod- setinputsizes() (pytds.Cursor method), 5
ule pytds.extensions), 13
setoutputsize() (pytds.Cursor method), 5
21
python-tds Documentation, Release 1.6
spid (pytds.Cursor attribute), 5
SspiAuth (class in pytds.login), 9
T
tds_version (pytds.Connection attribute), 3
tuple_row_strategy() (in module pytds), 7
U
UTC (class in pytds.tz), 11
22
Index