Connection¶

class ctds.Connection¶

A connection to the database server.

__enter__()¶

Enter the connection’s runtime context. On exit, the connection is closed automatically.

Returns: The connection object.
Return type: ctds.Connection

__exit__(exc_type, exc_val, exc_tb)¶

Exit the connection’s runtime context, closing the connection. If no error occurred, any pending transaction will be committed prior to closing the connection. If an error occurred, the transaction will be implicitly rolled back when the connection is closed.

Parameters

exc_type (type) – The exception type, if an exception is raised in the context, otherwise None.
exc_val (Exception) – The exception value, if an exception is raised in the context, otherwise None.
exc_tb (object) – The exception traceback, if an exception is raised in the context, otherwise None.

Returns

None

autocommit¶

Auto-commit transactions after ctds.Cursor.execute(), ctds.Cursor.executemany(), and ctds.Cursor.callproc(). If False, operations must be committed explicitly using commit().

Return type: bool

bulk_insert(table, rows, batch_size=None, tablock=False)¶

Bulk insert rows into a given table. This method utilizes the BULK INSERT functionality of SQL Server to efficiently insert large amounts of data into a table. By default, rows are not validated until all rows have been processed.

An optional batch size may be specified to validate the inserted rows after batch_size rows have been copied to server.

Parameters

table (str) – The table in which to insert the rows.
rows (typeiter) – An iterable of data rows. Data rows are Python sequence objects. Each item in the data row is inserted into the table in sequential order. Version 1.9 supports passing rows as dict. Keys must map to column names and must exist for all non-NULL columns.
batch_size (int) – An optional batch size.
tablock (bool) – Should the TABLOCK hint be passed?

Returns

The number of rows saved to the table.

Return type

int

close()¶

Close the connection now. Pending transactions will be rolled back. Subsequent calls to this object or any ctds.Cursor objects it created will raise ctds.InterfaceError.

PEP 0249#Connection.close

commit()¶

Commit any pending transaction to the database.

PEP 0249#commit

cursor()¶

Return a new ctds.Cursor object using the connection.

Note

ctds.Cursor.close() should be called when the returned cursor is no longer required.

Warning

Only one ctds.Cursor object should be used per connection. The last command executed on any cursor associated with a connection will overwrite any previous results from all other cursors.

PEP 0249#cursor

Returns: A new Cursor object.
Return type: ctds.Cursor

database¶

The current database or None if the connection is closed.

Return type: str

messages¶

A list of any informational messages received from the last ctds.Cursor.execute(), ctds.Cursor.executemany(), or ctds.Cursor.callproc() call. For example, this will include messages produced by the T-SQL PRINT and RAISERROR statements. Messages are preserved until the next call to any of the above methods. None is returned if the connection is closed.

PEP 0249#connection-messages

New in version 1.4.

Return type: list(dict)

rollback()¶

Rollback any pending transaction to the database.

PEP 0249#rollback

spid¶

The SQL Server Session Process ID (SPID) for the connection or None if the connection is closed.

Return type: int

tds_version¶

The TDS version in use for the connection or None if the connection is closed.

Return type: str

timeout¶

The connection timeout, in seconds, or None if the connection is closed.

Note

Setting the timeout requires FreeTDS version 1.00 or later.

Raises: ctds.NotSupportedError – cTDS was compiled against a version of FreeTDS which does not support setting the timeout on a connection.
Return type: int

use(database)¶

Set the current database.

Parameters: database (str) – The database.
Returns: None