ctds¶

cTDS is a pure C implementation of the Python DB API 2.0 specification for Microsoft SQL Server.

ctds.apilevel¶: PEP 0249#apilevel

ctds.paramstyle¶: PEP 0249#paramstyle

ctds.threadsafety¶: PEP 0249#threadsafety

ctds.freetds_version¶: The version of FreeTDS in use at runtime.

ctds.version_info¶: The cTDS version, as a (MAJOR, MINOR, PATCH) tuple.

exception ctds.Error¶

Exception that is the base class of all other error exceptions. You can use this to catch all errors with one single except statement.

exception ctds.InterfaceError¶

PEP 0249#interfaceerror

Exception raised for errors that are related to the database interface rather than the database itself.

exception ctds.DatabaseError¶

PEP 0249#databaseerror

Exception raised for errors that are related to the database.

The exception contains the following properties:

db_error¶

A dict containing information relating to an error returned by the database.

{
    'number': 123,
    'description': 'An error description'
}

os_error¶

A dict containing information relating to an error caused by a database connection issue. This will be None if the error was not caused by a connection issue.

{
    'number': 123,
    'description': 'An error description'
}

last_message¶

A dict containing more detailed information about. the error returned from the database. This may be None if the error does not include more information from the database, e.g. a connection error.

{
    'number': 123,
    'state': 0,
    'severity': 16,
    'description': 'An error description'
    'server': 'database-hostname'
    'proc': 'procedure_name'
    'line': 34
}

exception ctds.DataError¶

PEP 0249#dataerror

Exception raised for errors that are due to problems with the processed data like division by zero, numeric value out of range, etc.

exception ctds.OperationalError¶

PEP 0249#operationalerror

Exception raised for errors that are related to the database’s operation and not necessarily under the control of the programmer, e.g. an unexpected disconnect occurs, the data source name is not found, a transaction could not be processed, a memory allocation error occurred during processing, etc.

exception ctds.IntegrityError¶

PEP 0249#integrityerror

Exception raised when the relational integrity of the database is affected, e.g. a foreign key check fails.

exception ctds.InternalError¶

PEP 0249#internalerror

Exception raised when the database encounters an internal error, e.g. the cursor is not valid anymore, the transaction is out of sync, etc.

exception ctds.ProgrammingError¶

PEP 0249#programmingerror

Exception raised for programming errors, e.g. table not found or already exists, syntax error in the SQL statement, wrong number of parameters specified, etc.

exception ctds.NotSupportedError¶

PEP 0249#notsupportederror

Exception raised in case a method or database API was used which is not supported by the database, e.g. calling rollback() on a connection that does not support transactions or has transactions turned off.

exception ctds.Warning¶

PEP 0249#warning

Exception raised for important warnings like data truncations while inserting, etc.

ctds.Binary(string)¶

This function constructs an object capable of holding a binary (long) string value.

PEP 0249#binary

Parameters: string (str) – The string value to convert to binary.
Returns: A new binary object.
Return type: SqlBinary

ctds.Date(year, month, day)¶

This function constructs an object holding a date value.

PEP 0249#date

Parameters

year (int) – The year.
month (int) – The month.
day (int) – The day.

Returns

A new date object.

Return type

datetime.date

ctds.DateFromTicks(ticks)¶

This function constructs an object holding a date value from the given ticks value (number of seconds since the epoch; see the documentation of the standard Python time module for details).

PEP 0249#datefromticks

Parameters: ticks (int) – The number of seconds since the epoch.
Returns: A new date object.
Return type: datetime.date

ctds.Time(hour, minute, second)¶

This function constructs an object holding a time value.

PEP 0249#time

Parameters

hour (int) – The hour.
minute (int) – The minute.
second (int) – The second.

Returns

A new time object.

Return type

datetime.time

ctds.TimeFromTicks(ticks)¶

This function constructs an object holding a time value from the given ticks value (number of seconds since the epoch; see the documentation of the standard Python time module for details).

PEP 0249#timefromticks

Parameters: ticks (int) – The number of seconds since the epoch.
Returns: A new time object.
Return type: datetime.time

ctds.Timestamp(year, month, day, hour, minute, second)¶

This function constructs an object holding a time stamp value.

PEP 0249#timestamp

Parameters

year (int) – The year.
month (int) – The month.
day (int) – The day.
hour (int) – The hour.
minute (int) – The minute.
second (int) – The second.

Returns

A new datetime object.

Return type

datetime.datetime

ctds.TimestampFromTicks(ticks)¶

This function constructs an object holding a time stamp value from the given ticks value (number of seconds since the epoch; see the documentation of the standard Python time module for details).

PEP 0249#timestampfromticks

Parameters: ticks (int) – The number of seconds since the epoch.
Returns: A new datetime object.
Return type: datetime.datetime

ctds.connect(server, port=1433, instance=None, user='', password='', database=None, appname='ctds', hostname=None, login_timeout=5, timeout=5, tds_version=None, autocommit=False, ansi_defaults=True, enable_bcp=True, paramstyle=None, read_only=False, ntlmv2=False)¶

Connect to a database.

Note

ctds.Connection.close() should be called when the returned connection object is no longer required.

PEP 0249#connect

New in version 1.6: paramstyle

New in version 1.6: read_only

New in version 1.8: hostname

New in version 1.8: ntlmv2

Parameters

server (str) – The database server host.
port (int) – The database server port. This value is ignored if instance is provided.
instance (str) – An optional database instance to connect to.
user (str) – The database server username.
password (str) – The database server password.
database (str) – An optional database to initially connect to.
appname (str) – An optional application name to associate with the connection.
hostname (str) – An optional client host name to associate with the connection instead of the local device hostname.
login_timeout (int) – An optional login timeout, in seconds.
timeout (int) – An optional timeout for database requests, in seconds.
tds_version (str) – The TDS protocol version to use. If None is specified, the highest version supported by FreeTDS will be used.
autocommit (bool) – Autocommit transactions on the connection.
ansi_defaults (bool) – Set ANSI_DEFAULTS and related settings to mimic ODBC drivers.
enable_bcp (bool) – Enable bulk copy support on the connection. This is required for bulk_insert() to function.
paramstyle (str) – Override the default ctds.paramstyle value for this connection. Supported values: numeric, named.
read_only (bool) – Indicate ‘read-only’ application intent.
ntlmv2 (bool) – Enable NTLMv2 authentication.

Returns

A new Connection object connected to the database.

Return type

Connection