Turbodbc

https://turbodbc.readthedocs.io/en/latest/
Admin
Turbodbc is a Python module for high-performance relational database access via ODBC with built-in...
Tokens:28,944
Snippets:136
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Turbodbc Development Container Build Steps

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

Example build steps for a turbodbc development container, including CMake configuration, compilation, installation, and running unit tests.

```bash
cmake -DBOOST_ROOT=$CONDA_PREFIX -DBUILD_COVERAGE=ON -DCMAKE_INSTALL_PREFIX=./dist -DPYTHON_EXECUTABLE=/miniconda/envs/turbodbc-dev/bin/python -GNinja ..
ninja
cmake –build . –target install
ctest -E turbodbc_integration_test –verbose
```

--------------------------------

### Manage Docker Compose for Integration Tests

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

Commands to start and stop the docker-compose setup required for running turbodbc integration tests.

```bash
docker-compose -f earthly/docker-compose.yml up
```

```bash
docker-compose -f earthly/docker-compose.yml down
```

--------------------------------

### Install turbodbc with Pip on Windows

Source: https://turbodbc.readthedocs.io/en/latest/pages/getting_started

Installs turbodbc on Windows using pip. This method downloads a binary wheel, requiring no compilation. Prerequisites include a 64-bit OS, Python 3.5/3.6 (64-bit), and MSVS 2015 Update 3 Redistributable. For later Python versions, Boost must be manually installed.

```bash
pip install turbodbc
```

--------------------------------

### Install PyArrow for turbodbc

Source: https://turbodbc.readthedocs.io/en/latest/pages/getting_started

Installs the Apache Arrow Python package. This is recommended to be installed before turbodbc if you wish to use the optional Apache Arrow support features.

```bash
pip install pyarrow
```

--------------------------------

### Turbodbc Exasol Connection Example

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/exasol

Python code demonstrating how to establish a connection to an Exasol database using turbodbc, with a specific configuration for an increased read buffer size to optimize performance.

```python
from turbodbc import connect, make_options, Megabytes
options = make_options(read_buffer_size=Megabytes(100))
connect(dsn="Exasol", turbodbc_options=options)
```

--------------------------------

### Install turbodbc with Pip on Linux/OSX

Source: https://turbodbc.readthedocs.io/en/latest/pages/getting_started

Installs turbodbc using pip on Linux and OSX. This method triggers a source build and requires C++11 compiler, Boost library, ODBC library, and Python headers. It's recommended to install numpy and pyarrow before turbodbc for optional features.

```bash
pip install turbodbc
```

--------------------------------

### Install turbodbc with Conda

Source: https://turbodbc.readthedocs.io/en/latest/pages/getting_started

Installs turbodbc using the conda package manager from the conda-forge channel. This method is recommended as it fetches pre-compiled binaries and dependencies for your platform.

```bash
conda install -c conda-forge turbodbc
```

--------------------------------

### Install CMake with pip

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

Installs the CMake build system using pip, which is a prerequisite for building turbodbc.

```bash
pip install cmake
```

--------------------------------

### Connecting to MySQL with turbodbc

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/mysql

This Python code example demonstrates how to establish a connection to a MySQL database using the turbodbc library by specifying the DSN.

```python
from turbodbc import connect

connect(dsn="MySQL")

```

--------------------------------

### Install pip Dependencies

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

Installs necessary Python packages for turbodbc development using pip, including numpy, pytest, mock, and pyarrow.

```bash
pip install numpy pytest pytest-cov mock pyarrow
```

--------------------------------

### Create Python Source Distribution

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

Builds a source distribution (sdist) of turbodbc, creating a .tar.gz file that can be installed using pip.

```bash
make install
cd dist
python setup.py sdist
```

--------------------------------

### Install NumPy for turbodbc

Source: https://turbodbc.readthedocs.io/en/latest/pages/getting_started

Installs the NumPy Python package. This is a prerequisite for turbodbc to compile optional NumPy support features, and should be installed before turbodbc.

```bash
pip install numpy
```

--------------------------------

### Create Conda Environment and Install Dependencies

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

Creates a new conda environment named 'turbodbc-dev' and installs all required dependencies from conda-forge, including Python packages and build tools like cmake, pybind11, and boost-cpp.

```bash
conda create -y -q -n turbodbc-dev pyarrow numpy pybind11 boost-cpp \
    pytest pytest-cov mock cmake unixodbc gtest gmock -c conda-forge
source activate turbodbc-dev
```

--------------------------------

### Testing ODBC Configuration with isql

Source: https://turbodbc.readthedocs.io/en/latest/pages/troubleshooting

Demonstrates how to test an ODBC configuration using the `isql` tool, which is part of unixODBC. This is a crucial step before using turbodbc to ensure the underlying ODBC setup is correct. The command connects to a data source using optional user and password credentials.

```bash
> isql "data source name" user password -v

```

--------------------------------

### Netezza Data Source Configuration (DSN)

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/netezza

Example configuration for a Data Source Name (DSN) to connect to a Netezza database. This includes server details, port, database name, and authentication credentials.

```INI
[Netezza]
Driver                     = NZSQL
Description                = NetezzaSQL ODBC Connection
Servername                 = <server_hostname>
Port                       = 5480
Database                   = <default_database>
Username                   = <username>
Password                   = <password>
```

--------------------------------

### turbodbc API Reference Overview

Source: https://turbodbc.readthedocs.io/en/latest/pages/api_reference

This section outlines the main components and functionalities available in the turbodbc library's API. It serves as a guide to accessing and utilizing turbodbc for database operations.

```APIDOC
turbodbc API Reference:

This document details the public API of the turbodbc library.

Key components include:
- Connection Management: Establishing and managing connections to ODBC data sources.
- Data Transfer: Functions for efficiently transferring data between Python and databases.
- Query Execution: Methods for executing SQL queries and retrieving results.
- Data Handling: Utilities for working with database result sets in Python.

For detailed information on specific functions and classes, please refer to the respective sections within the turbodbc documentation.
```

--------------------------------

### Set BOOST_ROOT environment variable on Windows

Source: https://turbodbc.readthedocs.io/en/latest/pages/getting_started

Sets the BOOST_ROOT environment variable on Windows to point to the Boost C++ libraries directory. This is required when installing turbodbc with a later version of Python on Windows after manually installing Boost.

```bash
set BOOST_ROOT=C:\your path to\boost_1_72_0
```

--------------------------------

### Execute SQL Query and Fetch Results

Source: https://turbodbc.readthedocs.io/en/latest/pages/getting_started

Executes a SQL query and retrieves the results. A cursor object is used for execution. Results can be fetched by iterating over the cursor or using fetchall() to get all rows.

```Python
cursor = connection.cursor()
cursor.execute('SELECT 42')

for row in cursor:
    print row
# Output: [42L]
```

```Python
cursor = connection.cursor()
cursor.execute('SELECT 42')
print cursor.fetchall()
# Output: [[42L]]
```

--------------------------------

### Run Integration Tests with MSSQL

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

SQL and command-line steps to set up an MSSQL database and run integration tests for turbodbc.

```bash
/opt/mssql-tools/bin/sqlcmd -S localhost -U SA -P 'StrongPassword1' -Q 'CREATE DATABASE test_db'
ctest --verbose
```

--------------------------------

### Build and Test Turbodbc with Earthly

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

Commands to build and run the full test suite for turbodbc using Earthly. Includes options for default testing, interactive mode, and testing specific configurations.

```bash
earthly --allow-privileged +test
```

```bash
earthly -i --allow-privileged +test
```

```bash
earthly -P +test-python3.8-arrow3.x.x
```

```bash
earthly --allow-privileged +test-all
```

--------------------------------

### Run turbodbc Test Suite

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

Sets an environment variable to specify the configuration files for testing and then runs the test suite using 'ctest'. The configuration files should contain database credentials.

```bash
export TURBODBC_TEST_CONFIGURATION_FILES="<Postgres json file>,<MySql json file>, <MS SQL json file>"
ctest --output-on-failure
```

--------------------------------

### Basic turbodbc Connection to Netezza

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/netezza

Demonstrates a basic turbodbc connection to a Netezza database using default options, suitable for most use cases.

```Python
from turbodbc import connect, make_options, Megabytes
options = make_options(read_buffer_size=Megabytes(100))
connect(dsn="Netezza", turbodbc_options=options)
```

--------------------------------

### Connect to Database with Direct Parameters

Source: https://turbodbc.readthedocs.io/en/latest/pages/getting_started

Establishes a database connection by specifying all required configuration options directly as keyword arguments. This bypasses the need for a DSN or a full connection string.

```Python
from turbodbc import connect
connection = connect(driver="PostgreSQL",
                     server="hostname",
                     port="5432",
                     database="myDataBase",
                     uid="myUsername",
                     pwd="myPassword")
```

--------------------------------

### turbodbc Module Functions

Source: https://turbodbc.readthedocs.io/en/latest/genindex

Provides functions for establishing database connections and creating configuration options.

```APIDOC
turbodbc:
  connect(*args, **kwargs)
    Description: Establishes a database connection.

  make_options(**kwargs)
    Description: Creates a configuration options object.
```

--------------------------------

### Connect with Default Options

Source: https://turbodbc.readthedocs.io/en/latest/pages/advanced_usage

Demonstrates how to establish a database connection using Turbodbc with default configuration options.

```python
>>> from turbodbc import connect, make_options
>>> options = make_options()
>>> connect(dsn="my_dsn", turbodbc_options=options)
```

--------------------------------

### C++ Backend: Accessing Query Results

Source: https://turbodbc.readthedocs.io/en/latest/pages/changelog

Direct access to the C++ `field` type in `turbodbc::cursor` is deprecated. Use `cursor.get_query()` to get the query, and then `get_results()` to construct a `turbodbc::result_sets::field_result_set`.

```C++
auto query = cursor.get_query();
auto results = query.get_results();
```

--------------------------------

### Connect to Database using Connection String

Source: https://turbodbc.readthedocs.io/en/latest/pages/getting_started

Establishes a database connection using a provided ODBC connection string. This method allows specifying driver, server, port, database, username, and password directly.

```Python
from turbodbc import connect
connection = connect(connection_string='Driver={PostgreSQL};Server=IP address;Port=5432;Database=myDataBase;Uid=myUsername;Pwd=myPassword;')
```

--------------------------------

### Fetch Result Sets as NumPy Arrays

Source: https://turbodbc.readthedocs.io/en/latest/pages/changelog

Introduces NumPy support for retrieving result sets. Use `cursor.fetchallnumpy` to get results as an `OrderedDict` where keys are column names and values are NumPy `MaskedArray`s.

```Python
cursor.fetchallnumpy()
```

--------------------------------

### Turbodbc Connection to PostgreSQL

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/postgresql

Demonstrates how to establish a connection to a PostgreSQL database using turbodbc with a specified DSN.

```Python
from turbodbc import connect
connect(dsn="PostgreSQL")
```

--------------------------------

### Turbodbc Version 2.2.0: Large Decimals and VARCHAR Limits

Source: https://turbodbc.readthedocs.io/en/latest/pages/changelog

Introduces `large_decimals_as_64_bit_types` in `make_options()` for handling large decimals. Adds support for `datetime64[ns]` and `limit_varchar_results_to_max` for controlling VARCHAR field truncation. Also includes installation extras for NumPy and Arrow.

```Python
from turbodbc import make_options

options = make_options(large_decimals_as_64_bit_types=True, varchar_max_character_limit=100)
connection = connect(..., turbodbc_options=options)
```

```bash
pip install turbodbc[arrow,numpy]
```

--------------------------------

### Turbodbc Setup.py Configuration

Source: https://turbodbc.readthedocs.io/en/latest/pages/changelog

Adds the capability to set unixODBC include and library directories within `setup.py`, which is necessary for conda builds.

```Python
# Configuration for unixODBC include and library directories in setup.py
```

--------------------------------

### ODBC Driver Manager Functionality and Platforms

Source: https://turbodbc.readthedocs.io/en/latest/pages/odbc/concepts

Describes the ODBC driver manager as a central library that provides data type definitions and manages data source configurations. It explains that a data source includes a name (DSN), an associated ODBC driver, and connection options like host and credentials. The text also notes the availability of driver managers on different platforms, mentioning Windows' built-in manager and unixODBC/iODBC on Linux/OSX, and specifies turbodbc's tested compatibility.

```English
The driver manager is a somewhat odd centerpiece. It is a library that can be used just like any ODBC driver. It provides definitions for various data types, and actual ODBC drivers often rely on these definitions for compilation. The driver manager has a built-in configuration of data sources. A data source has a name (the data source name or DSN), is associated with an ODBC driver, contains configuration options such as the database host or the connection locale, and sometimes it also contains credentials for authentication with the database. Finally, the driver manager typically comes with a tool to edit data sources.
Driver managers are less numerous, but still easily available on all major platforms. Windows comes with a preinstalled ODBC database manager. On Linux and OSX, there are competing driver managers in unixodbc and iodbc.
Note
Turbodbc is tested with Windows’s built-in driver manager and unixodbc on Linux and OSX.
```

--------------------------------

### Exasol odbcinst.ini (OSX)

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/exasol

Configuration for the Exasol ODBC driver on OSX systems, utilizing the iodbc library. It includes the driver path and threading settings necessary for proper operation.

```ini
[Exasol driver]
Driver = /path/to/libexaodbc-io418sys.dylib
Threading = 2
```

--------------------------------

### PostgreSQL Data Source Configuration

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/postgresql

Defines connection parameters for a PostgreSQL data source, including driver, database name, server, credentials, port, protocol, fetch settings, and preparation methods.

```INI
[PostgreSQL]
Driver               = PostgreSQL Driver
Database             = <database name>
Servername           = <host>
UserName             = <user>
Password             = <password>
Port                 = <port, default is 5432>
Protocol             = 7.4
UseDeclareFetch      = 1
Fetch                = 10000
UseServerSidePrepare = 1
BoolsAsChar          = 0
ConnSettings         = set time zone 'UTC';
```

--------------------------------

### MySQL Data Source Configuration (DSN)

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/mysql

This snippet details the recommended settings for a MySQL data source configuration (DSN). It includes parameters for the driver, server, user ID, password, database name, port, and an initialization statement for timezone consistency.

```ini
[MySQL]
Driver   = MySQL Driver
SERVER   = <host>
UID      = <user>
PASSWORD = <password>
DATABASE = <database name>
PORT     = <port, default is 3306>
INITSTMT = set session time_zone ='+00:00';

```

--------------------------------

### Build Docker Image with Earthly

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

Command to build a Docker image for development usage with turbodbc using Earthly. The image is tagged as turbodbc:latest.

```bash
earthly +docker
```

--------------------------------

### ODBC Application Interaction and Benefits

Source: https://turbodbc.readthedocs.io/en/latest/pages/odbc/concepts

Explains how applications utilize the ODBC API by linking to the driver manager. It details that applications specify a data source name or connection options to establish a database connection. The text emphasizes the advantages of linking to the driver manager, such as simplifying driver changes at runtime and enabling the manager to handle compatibility issues through alternative functions and workarounds.

```English
Applications finally use the ODBC API and link to the driver manager. Any time they open a connection, they need to specify the data source name that contains connection attributes that relate to the desired database. Alternatively, they can specify all necessary connection options directly.
Linking to the driver manager instead of the ODBC driver directly means that changing to another driver is as simple as exchanging the connection string at runtime instead of tediously linking to a new driver. Linking to the driver manager also means that the driver manager handles many capability and compatibility options by transparently using alternative functions and workarounds as required.
```

--------------------------------

### Download and Extract pybind11

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

Downloads a specific version (v2.9.1) of pybind11 from GitHub and extracts the archive.

```bash
wget -q https://github.com/pybind/pybind11/archive/v2.9.1.tar.gz
tar xvf v2.9.1.tar.gz
```

--------------------------------

### Common ODBC Configuration Errors

Source: https://turbodbc.readthedocs.io/en/latest/pages/troubleshooting

Details common ODBC configuration errors encountered when using unixODBC and `isql`, providing troubleshooting steps for each. This includes issues with data source names not being found and problems opening the ODBC driver library.

```bash
[IM002][unixODBC][Driver Manager]Data source name not found, and no default driver specified
[ISQL]ERROR: Could not SQLConnect

```

```bash
[01000][unixODBC][Driver Manager]Can't open lib '/path/to/driver.so' : file not found
[ISQL]ERROR: Could not SQLConnect

```

--------------------------------

### Build turbodbc

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

Compiles the turbodbc source code using the 'make' command after CMake configuration.

```bash
make
```

--------------------------------

### Turbodbc Performance Options Management

Source: https://turbodbc.readthedocs.io/en/latest/pages/changelog

Introduces `make_options()` to manage performance and compatibility settings as keyword arguments, deprecating direct use of these options in `connect()`. These options should now be passed via the `turbodbc_options` argument in `connect()`.

```Python
options = turbodbc.make_options(read_buffer_size=1024*1024, use_async_io=True)
turbodbc.connect(turbodbc_options=options, ...)
# Deprecated: turbodbc.connect(read_buffer_size=..., use_async_io=..., ...)
```

--------------------------------

### PostgreSQL Driver Configuration (macOS)

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/postgresql

Specifies the path to the PostgreSQL ODBC driver and sets threading options for stability on macOS.

```INI
[PostgreSQL Driver]
Driver      = /usr/local/lib/psqlodbcw.so
Threading   = 2
```

--------------------------------

### PostgreSQL Driver Configuration (Linux)

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/postgresql

Specifies the path to the PostgreSQL ODBC driver and sets threading options for stability.

```INI
[PostgreSQL Driver]
Driver      = /usr/lib/x86_64-linux-gnu/odbc/psqlodbcw.so
Threading   = 2
```

--------------------------------

### SQLAlchemy Integration with turbodbc

Source: https://turbodbc.readthedocs.io/en/latest/pages/faq

This section details how to use turbodbc with SQLAlchemy for specific databases. It lists supported database integrations and their respective SQLAlchemy packages.

```en
EXASOL: sqlalchemy_exasol
MSSQL: sqlalchemy-turbodbc
Vertica: Unofficial fork of sqlalchemy-vertica
```

--------------------------------

### turbodbc Development and Updates

Source: https://turbodbc.readthedocs.io/en/latest/pages/faq

Information on how to stay updated with turbodbc's latest developments. This includes following the project on GitHub, reading the changelog, and following the official Twitter account.

```en
Follow the turbodbc project on GitHub.
Periodically read turbodbc’s change log.
Follow @turbodbc on Twitter.
```

--------------------------------

### Exasol Data Source Configuration

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/exasol

Defines the connection parameters for an Exasol data source. This includes the driver name, host, port range, user credentials, default schema, and locale settings for Unicode support.

```ini
[Exasol]
DRIVER = Exasol driver
EXAHOST = <host>:<port_range>
EXAUID = <user>
EXAPWD = <password>
EXASCHEMA = <default_schema>
CONNECTIONLCALL = en_US.utf-8
```

--------------------------------

### Clone turbodbc Repository

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

Clones the turbodbc source code from its GitHub repository into the current directory.

```bash
git clone https://github.com/blue-yonder/turbodbc.git
```

--------------------------------

### Exasol odbcinst.ini (Linux)

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/exasol

Configuration for the Exasol ODBC driver on Linux systems. It specifies the driver path and threading settings, which are crucial for handling potential thread issues with the driver.

```ini
[Exasol driver]
Driver = /path/to/libexaodbc-uo2214lv1.so    # only when libodbc.so.2 is not present
Driver = /path/to/libexaodbc-uo2214lv2.so    # only when libodbc.so.2 is present
Threading = 2
```

--------------------------------

### turbodbc C++ Layer and ODBC API

Source: https://turbodbc.readthedocs.io/en/latest/pages/faq

Blog posts explaining the internal workings of turbodbc, focusing on the C++ layer used for ODBC API calls and the transformation of ODBC API concepts into a Python-compliant API using pybind11.

```en
Part one: Wrestling with the side effects of a C API. This explains the C++ layer that is used to handle all calls to the ODBC API.
Part two: C++ to Python This explains how concepts of the ODBC API are transformed into an API compliant with Python’s database API, including making use of pybind11.
```

--------------------------------

### MySQL ODBC Driver Configuration (odbcinst.ini)

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/mysql

This snippet shows the recommended configuration for the MySQL ODBC driver in the odbcinst.ini file on Linux. It specifies the driver path and threading option.

```ini
[MySQL Driver]
Driver      = /usr/lib/x86_64-linux-gnu/odbc/libmyodbc.so
Threading   = 2

```

--------------------------------

### ODBC Driver Concepts and Availability

Source: https://turbodbc.readthedocs.io/en/latest/pages/odbc/concepts

Explains that ODBC drivers adhere to the ODBC API, offering a set of C functions. It highlights that drivers can have variations in implementation and support. The text also lists various sources for obtaining ODBC drivers, including major database vendors, open-source projects, Linux distributions, Homebrew, and commercial providers.

```English
ODBC drivers comply with the ODBC API, meaning that they offer a set of about 80 C functions with well-defined behavior that internally use database-specific commands to achieve the desired behavior. There is some wiggle room that allows ODBC drivers to implement certain things differently or even exclude support for some advanced usage patterns. But in essence, all ODBC drivers are born more or less equal.
ODBC drivers are easy to come by. Major database vendors offer ODBC drivers as free downloads (Microsoft SQL Server, Exasol, Teradata, etc). Open source databases provide ODBC databases as part of their projects (PostgreSQL, Impala, MongoDB). Many ODBC drivers are also shipped with Linux distributions or are readily available via Homebrew for OSX. Last but not least, commercial ODBC drivers are available at Progress or easysoft, claiming better performance than their freely available counterparts.
```

--------------------------------

### turbodbc connect

Source: https://turbodbc.readthedocs.io/en/latest/pages/api_reference

Creates a database connection using a DSN or connection string. Supports various connection parameters and turbodbc-specific options.

```APIDOC
turbodbc.connect(_*args_, _**kwds_)¶ 
    
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

Source: https://turbodbc.readthedocs.io/en/latest/pages/api_reference

Creates configuration options for turbodbc to control database interaction, affecting performance and behavior. Defaults are used if parameters are None.

```APIDOC
turbodbc.make_options(_read_buffer_size=None_ , _parameter_sets_to_buffer=None_ , _varchar_max_character_limit=None_ , _prefer_unicode=None_ , _use_async_io=None_ , _autocommit=None_ , _large_decimals_as_64_bit_types=None_ , _limit_varchar_results_to_max=None_ , _force_extra_capacity_for_unicode=None_ , _fetch_wchar_as_char=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.
  * **varchar_max_character_limit** – Affects behavior/performance. If a result set contains fields of type `VARCHAR(max)` or `NVARCHAR(max)` or the equivalent type of your database, buffers will be allocated to hold the specified number of characters. This may lead to truncation. The default value is `65535` characters. Please note that large values reduce the risk of truncation, but may affect the number of rows in a batch of result sets (see `read_buffer_size`). Please note that this option only relates to retrieving results, not sending parameters to the database.
  * **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.
  * **large_decimals_as_64_bit_types** – Affects behavior. If set to `True`, `DECIMAL(x, y)` results with `x > 18` will be rendered as 64 bit integers (`y == 0`) or 64 bit floating point numbers (`y > 0`), respectively. Use this option if your decimal data types are larger than the data they actually hold. Using this data type can lead to overflow errors and loss of precision. If not set or set to `False`, large decimals are rendered as strings.
  * **limit_varchar_results_to_max** – Affects behavior/performance. If set to `True`, any text-like fields such as `VARCHAR(n)` and `NVARCHAR(n)` will be limited to a maximum size of `varchar_max_character_limit` characters. This may lead to values being truncated, but reduces the amount of memory required to allocate string buffers, leading to larger, more efficient batches. If not set or set to `False`, strings can exceed `varchar_max_character_limit` in size if the database reports them this way. For fields such as `TEXT`, some databases report a size of 2 billion characters. Please note that this option only relates to retrieving results, not sending parameters to the database.
```

--------------------------------

### Netezza odbcinst.ini Configuration

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/netezza

Recommended settings for the `odbcinst.ini` file to configure the Netezza ODBC driver on Linux. This includes specifying the driver path and Unicode/character translation options.

```INI
[NZSQL]
Driver                     = /path/to/nz/lib/libnzsqlodbc3.so  # 32bit driver
Driver64                   = /path/to/nz/lib64/libnzodbc.so    # 64bit driver
UnicodeTranslationOption   = utf8
CharacterTranslationOption = all
PreFetch                   = 10000
Socket                     = 32000
```

--------------------------------

### Configure Build with CMake

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

Configures the build directory for turbodbc using CMake. The `-DPYTHON_EXECUTABLE` flag helps in detecting the correct Python version, especially within virtual environments.

```bash
cmake -DCMAKE_INSTALL_PREFIX=.. -DPYTHON_EXECUTABLE=$(which python) ../turbodbc
```

--------------------------------

### Connect to Database using DSN

Source: https://turbodbc.readthedocs.io/en/latest/pages/getting_started

Connects to a database using a Data Source Name (DSN) defined in the ODBC configuration. This is a convenient way to reuse connection settings. Optional parameters can override DSN settings.

```Python
from turbodbc import connect
connection = connect(dsn='My data source name as defined by your ODBC configuration')
```

```Python
from turbodbc import connect
connection = connect(dsn='my dsn', user='my user has precedence')
```

```Python
from turbodbc import connect
connection = connect(dsn='my dsn', username='field names depend on the driver')
```

--------------------------------

### Connect with Custom Options

Source: https://turbodbc.readthedocs.io/en/latest/pages/advanced_usage

Illustrates connecting to a database with customized Turbodbc options, such as read buffer size, parameter buffering, and Unicode preferences.

```python
>>> from turbodbc import Megabytes
>>> options = make_options(read_buffer_size=Megabytes(100),
...                        parameter_sets_to_buffer=1000,
...                        varchar_max_character_limit=10000,
...                        use_async_io=True,
...                        prefer_unicode=True,
...                        autocommit=True,
...                        large_decimals_as_64_bit_types=True,
...                        limit_varchar_results_to_max=True)
```

--------------------------------

### Turbodbc Introduction and Features

Source: https://turbodbc.readthedocs.io/en/latest/pages/introduction

Turbodbc is a Python module for accessing relational databases through the ODBC interface. It emphasizes speed and offers built-in support for NumPy and Apache Arrow, along with efficient parameter transfer and asynchronous I/O.

```Python
import turbodbc

# Example usage (conceptual)
# conn = turbodbc.connect(dsn='my_dsn', user='user', password='password')
# cursor = conn.cursor()
# cursor.execute('SELECT * FROM my_table')
# results = cursor.fetchall()
# print(results)
```

--------------------------------

### Unixodbc odbcinst.ini Configuration

Source: https://turbodbc.readthedocs.io/en/latest/pages/odbc/driver_manager_config

Lists available ODBC drivers for Unixodbc, allowing them to be referenced in odbc.ini. Each section defines a driver name, its library path, and optional parameters like threading level or description.

```ini
[driver A]
Driver = /path/to/driver_library.so
Threading = 2
Description = A driver to access ShinyDB databases

[driver B]
Driver = /some/other/driver/library.so

```

--------------------------------

### turbodbc Version 2.6.0 Context Managers and Unicode Handling

Source: https://turbodbc.readthedocs.io/en/latest/pages/changelog

Version 2.6.0 adds `with` block support for Cursor and Connection objects, introduces `force_extra_capacity_for_unicode` for improved unicode memory allocation, updates Apache Arrow support, and fixes a cursor garbage collection bug.

```changelog
Added support for `with` blocks for `Cursor` and `Connection` objects. This makes turbodbc conform with PEP 343 (thanks @AtomBaf)
Added new keyword argument `force_extra_capacity_for_unicode` to `make_options()`. If set to `True`, memory allocation is modified to operate under the assumption that the database driver reports field lengths in characters, rather than code units (thanks @yaxxie).
Updated Apache Arrow support to work with both versions 0.8.0 and 0.9.0 (thanks @pacman82)
Fixed a bug that led to `handle limit exceeded` error messages when `Cursor` objects were not closed _manually_. With this fix, cursors are garbage collected as expected.
```

--------------------------------

### Set ODBCINI Environment Variable

Source: https://turbodbc.readthedocs.io/en/latest/pages/odbc/driver_manager_config

Illustrates how to set the ODBCINI environment variable on Unix-like systems to specify a custom path for the user-specific odbc.ini file.

```bash
> export ODBCINI=/full/path/to/odbc.ini
```

--------------------------------

### Execute SQL INSERT Query with Parameters

Source: https://turbodbc.readthedocs.io/en/latest/pages/getting_started

Executes SQL INSERT statements, supporting parameterization to prevent SQL injection and improve efficiency. Parameters are passed as a list or tuple to the execute() method.

```Python
cursor = connection.cursor()
cursor.execute("INSERT INTO TABLE my_integer_table VALUES (?, ?)",
               [42, 17])
```

--------------------------------

### Turbodbc Supported Environments and Databases

Source: https://turbodbc.readthedocs.io/en/latest/pages/introduction

Turbodbc is tested on 64-bit Linux, macOS, and Windows operating systems with Python 3.7+. It officially supports PostgreSQL, MySQL, and MSSQL, with ongoing testing for various driver combinations and potential compatibility with other databases.

```Python
# Supported environments and databases are listed in the documentation.
# Example: 
# Supported OS: Linux, OSX, Windows (64-bit)
# Supported Python: 3.7, 3.8, 3.9
# Supported Databases: PostgreSQL, MySQL, MSSQL
```

--------------------------------

### Input/Output Size Settings (No Effect)

Source: https://turbodbc.readthedocs.io/en/latest/pages/api_reference

Methods to set input and output sizes, which have no effect in turbodbc as types and sizes are automatically determined.

```Python
setinputsizes(_sizes_)

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

```Python
setoutputsize(_size_ , _column=None_)
    
Has no effect since turbodbc automatically picks appropriate input types and sizes. Method exists since PEP-249 requires it.
```

--------------------------------

### MSSQL Data Source Configuration (Windows) - Official Microsoft Driver

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/mssql

Registry configuration for the official Microsoft ODBC driver on Windows. Includes driver path, server, and database settings.

```INI
[HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBC.INI\MSSQL]
"Driver"="C:\\Windows\\system32\\msodbcsql17.dll"
"Server"="<host>"
"Database"="<database>"

```

--------------------------------

### Set ODBCSYSINI Environment Variable

Source: https://turbodbc.readthedocs.io/en/latest/pages/odbc/driver_manager_config

Demonstrates how to set the ODBCSYSINI environment variable on Unix-like systems to specify a custom folder for unixODBC configuration files.

```bash
> export ODBCSYSINI=/my/folder
```

--------------------------------

### MSSQL Data Source Configuration - FreeTDS

Source: https://turbodbc.readthedocs.io/en/latest/pages/databases/mssql

Configuration for FreeTDS data sources, including driver name, server, port, and database. Note that credentials cannot be specified here.

```INI
[MSSQL]
Driver   = FreeTDS Driver
Server   = <host>
Port     = <post>
Database = <database>

```

--------------------------------

### turbodbc Connection Methods

Source: https://turbodbc.readthedocs.io/en/latest/genindex

Provides methods for managing database connections, including committing transactions, rolling back changes, closing connections, and creating cursors.

```APIDOC
turbodbc.connection.Connection:
  autocommit (attribute)
    Description: Controls whether transactions are automatically committed.

  close()
    Description: Closes the database connection.

  commit()
    Description: Commits the current transaction.

  cursor()
    Description: Creates a new cursor object for executing SQL statements.

  rollback()
    Description: Rolls back the current transaction.
```

--------------------------------

### Turbodbc Connection Class

Source: https://turbodbc.readthedocs.io/en/latest/pages/api_reference

Provides methods for managing database connections, including autocommit settings, closing connections, committing transactions, creating cursors, and rolling back changes.

```APIDOC
class turbodbc.connection.Connection(_impl_)

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

  close() -> None
    Close the connection and all associated cursors. This will implicitly roll back any uncommitted operations.

  commit(**kwds) -> None
    Commits the current transaction

  cursor(**kwds) -> Cursor
    Create a new `Cursor` instance associated with this `Connection`
    Returns: A new `Cursor` instance

  rollback(**kwds) -> None
    Roll back all changes in the current transaction
```

--------------------------------

### Turbodbc Connection Options

Source: https://turbodbc.readthedocs.io/en/latest/pages/api_reference

Configuration options for turbodbc connections, specifically for handling Unicode string data and optimizing memory allocation for VARCHAR/NVARCHAR fields to prevent truncation.

```Python
force_extra_capacity_for_unicode: bool
  Affects behavior/performance. Some ODBC drivers report the length of the `VARCHAR`/`NVARCHAR` field rather than the number of code points for which space is required to be allocated, resulting in string truncations. Set this option to `True` to increase the memory allocated for `VARCHAR` and `NVARCHAR` fields and prevent string truncations. Please note that this option only relates to retrieving results, not sending parameters to the database.

fetch_wchar_as_char: bool
  Affects behavior. Some ODBC drivers retrieve single byte encoded strings into `NVARCHAR` fields of result sets, which are decoded incorrectly by turbodbc default settings, resulting in corrupt strings. Set this option to `True` to have turbodbc treat `NVARCHAR` types as narrow character types when decoding the fields in result sets. Please note that this option only relates to retrieving results, not sending parameters to the database.
```

--------------------------------

### Build turbodbc with C++11 ABI Fix

Source: https://turbodbc.readthedocs.io/en/latest/pages/contributing

A CMake command to use when encountering linker errors on Linux distributions with C++11 compliant ABI, ensuring compatibility with manylinux wheels.

```bash
cmake -DCMAKE_INSTALL_PREFIX=.. -DPYTHON_EXECUTABLE=$(which python) -DCMAKE_CXX_FLAGS="-D_GLIBCXX_USE_CXX11_ABI=0" ../turbodbc
```
Tokens:
Raw