API reference¶
-
turbodbc.
connect
(dsn=None, turbodbc_options=None, read_buffer_size=None, parameter_sets_to_buffer=None, use_async_io=False, connection_string=None, **kwargs)¶ Create a connection with the database identified by the
dsn
or theconnection_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 thisConnection
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.- sql – A (unicode) string that contains the SQL command or query. If you would like to
use parameters, please use a question mark
-
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.- sql – A (unicode) string that contains the SQL command or query. If you would like to
use parameters, please use a question mark
-
fetchall
()¶ Fetches a list of all rows in the active result set generated with
execute()
orexecutemany()
.Returns: A list of rows
-
fetchallnumpy
()¶ Fetches all rows in the active result set generated with
execute()
orexecutemany()
.Returns: An OrderedDict
of columns, where the keys of the dictionary are the column names. The columns are of NumPy’sMaskedArray
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()
orexecutemany()
.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()
orexecutemany()
.Returns: An iterator you can use to iterate over batches of rows of the result set. Each batch consists of an OrderedDict
of NumPyMaskedArray
instances. Seefetchallnumpy()
for details.
-
fetchone
()¶ Returns a single row of a result set. Requires an active result set on the database generated with
execute()
orexecutemany()
.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