API reference

turbodbc.connect(dsn=None, turbodbc_options=None, connection_string=None, **kwargs)

Create a connection with the database identified by the dsn or the connection_string.

Parameters:
  • dsn – Data source name as given in the (unix) odbc.ini file or (Windows) ODBC Data Source Administrator tool.
  • turbodbc_options – Options that control how turbodbc interacts with the database. Create such a struct with turbodbc.make_options() or leave this blank to take the defaults.
  • connection_string – Preformatted ODBC connection string. Specifying this and dsn or kwargs at the same time raises ParameterError.
  • **kwargs – You may specify additional options as you please. These options will go into the connection string that identifies the database. Valid options depend on the specific database you would like to connect with (e.g. user and password, or uid and pwd)
Returns:

A connection to your database

turbodbc.make_options(read_buffer_size=None, parameter_sets_to_buffer=None, prefer_unicode=None, use_async_io=None, autocommit=None)

Create options that control how turbodbc interacts with a database. These options affect performance for the most part, but some options may require adjustment so that all features work correctly with certain databases.

If a parameter is set to None, this means the default value is used.

Parameters:
  • read_buffer_size – Affects performance. Controls the size of batches fetched from the database when reading result sets. Can be either an instance of turbodbc.Megabytes (recommended) or turbodbc.Rows.
  • parameter_sets_to_buffer – Affects performance. Number of parameter sets (rows) which shall be transferred to the server in a single batch when executemany() is called. Must be an integer.
  • use_async_io – Affects performance. Set this option to True if you want to use asynchronous I/O, i.e., while Python is busy converting database results to Python objects, new result sets are fetched from the database in the background.
  • prefer_unicode – May affect functionality and performance. Some databases do not support strings encoded with UTF-8, leading to UTF-8 characters being misinterpreted, misrepresented, or downright rejected. Set this option to True if you want to transfer character data using the UCS-2/UCS-16 encoding that use (multiple) two-byte instead of (multiple) one-byte characters.
  • autocommit – Affects behavior. If set to True, all queries and commands executed with cursor.execute() or cursor.executemany() will be succeeded by an implicit commit operation, persisting any changes made to the database. If not set or set to False, users has to take care of calling cursor.commit() themselves.
Returns:

An option struct that is suitable to pass to the turbodbc_options parameter of turbodbc.connect()

class turbodbc.connection.Connection(impl)
autocommit

This attribute controls whether changes are automatically committed after each execution or not.

close()

Close the connection and all associated cursors. This will implicitly roll back any uncommitted operations.

commit()

Commits the current transaction

cursor()

Create a new Cursor instance associated with this Connection

Returns:A new Cursor instance
rollback()

Roll back all changes in the current transaction

class turbodbc.cursor.Cursor(impl)

This class allows you to send SQL commands and queries to a database and retrieve associated result sets.

close()

Close the cursor.

description

Retrieve a description of the columns in the current result set

Returns:A tuple of seven elements. Only some elements are meaningful:
  • Element #0 is the name of the column
  • Element #1 is the type code of the column
  • Element #6 is true if the column may contain NULL values
execute(sql, parameters=None)

Execute an SQL command or query

Parameters:
  • sql – A (unicode) string that contains the SQL command or query. If you would like to use parameters, please use a question mark ? at the location where the parameter shall be inserted.
  • parameters – An iterable of parameter values. The number of values must match the number of parameters in the SQL string.
Returns:

The Cursor object to allow chaining of operations.

executemany(sql, parameters=None)

Execute an SQL command or query with multiple parameter sets.

Parameters:
  • sql – A (unicode) string that contains the SQL command or query. If you would like to use parameters, please use a question mark ? at the location where the parameter shall be inserted.
  • parameters – An iterable of iterable of parameter values. The outer iterable represents separate parameter sets. The inner iterable contains parameter values for a given parameter set. The number of values of each set must match the number of parameters in the SQL string.
Returns:

The Cursor object to allow chaining of operations.

fetchall()

Fetches a list of all rows in the active result set generated with execute() or executemany().

Returns:A list of rows
fetchallnumpy()

Fetches all rows in the active result set generated with execute() or executemany().

Returns:An OrderedDict of columns, where the keys of the dictionary are the column names. The columns are of NumPy’s MaskedArray type, where the optimal data type for each result set column is chosen automatically.
fetchmany(size=None)

Fetches a batch of rows in the active result set generated with execute() or executemany().

Parameters:size – Controls how many rows are returned. The default None means that the value of Cursor.arraysize is used.
Returns:A list of rows
fetchnumpybatches()

Returns an iterator over all rows in the active result set generated with execute() or executemany().

Returns:An iterator you can use to iterate over batches of rows of the result set. Each batch consists of an OrderedDict of NumPy MaskedArray instances. See fetchallnumpy() for details.
fetchone()

Returns a single row of a result set. Requires an active result set on the database generated with execute() or executemany().

Returns:Returns None when no more rows are available in the result set
setinputsizes(sizes)

Has no effect since turbodbc automatically picks appropriate return types and sizes. Method exists since PEP-249 requires it.

setoutputsize(size, column=None)

Has no effect since turbodbc automatically picks appropriate input types and sizes. Method exists since PEP-249 requires it.

class turbodbc.exceptions.Error

turbodbc’s basic error class

class turbodbc.exceptions.InterfaceError

An error that is raised whenever you use turbodbc incorrectly

class turbodbc.exceptions.DatabaseError

An error that is raised when the database encounters an error while processing your commands and queries

class turbodbc.exceptions.ParameterError

An error that is raised when you use connection arguments that are supposed to be mutually exclusive