arrow-odbc

Sync Arrow-over-ODBC adapter built on arrow-odbc. Streams pyarrow.RecordBatchReader results from any ODBC-compliant driver, making it a good fit for read-heavy analytical transfer between SQL Server, PostgreSQL, MySQL, or other ODBC sources and the Arrow ecosystem.

Configuration

class sqlspec.adapters.arrow_odbc.ArrowOdbcConfig

Bases: NoPoolSyncConfig[Connection, ArrowOdbcDriver]

Configuration for synchronous arrow-odbc connections.

driver_type

alias of ArrowOdbcDriver

connection_type

alias of Connection

__init__(*, connection_config=None, connection_instance=None, migration_config=None, statement_config=None, driver_features=None, bind_key=None, extension_config=None, observability_config=None, **kwargs)

Initialize arrow-odbc configuration.

create_connection()

Create and return a new arrow-odbc connection.

Return type:

Connection

provide_connection(*args, **kwargs)

Provide a connection context manager.

Return type:

ArrowOdbcConnectionContext

provide_session(*_args, statement_config=None, **_kwargs)

Provide a driver session context manager.

Return type:

ArrowOdbcSessionContext

get_signature_namespace()

Get the signature namespace for ArrowOdbcConfig types.

Return type:

dict[str, typing.Any]

get_event_runtime_hints()

Return polling defaults suitable for generic ODBC sources.

Return type:

EventRuntimeHints

class sqlspec.adapters.arrow_odbc.ArrowOdbcConnectionParams

Bases: TypedDict

arrow-odbc connection parameters.

class sqlspec.adapters.arrow_odbc.ArrowOdbcDriverFeatures

Bases: TypedDict

arrow-odbc driver feature flags.

Driver

class sqlspec.adapters.arrow_odbc.ArrowOdbcDriver

Bases: SyncDriverAdapterBase

Sync driver for generic ODBC connections with Arrow-native transfer.

__init__(connection, statement_config=None, driver_features=None)

Initialize driver adapter with connection and configuration.

Parameters:

• connection (Connection) -- Database connection instance

• statement_config (StatementConfig | None) -- Statement configuration for the driver

• driver_features (dict[str, typing.Any] | None) -- Driver-specific features like extensions, secrets, and connection callbacks

• observability -- Optional runtime handling lifecycle hooks, observers, and spans

property data_dictionary: ArrowOdbcDataDictionary

Get the data dictionary for this driver.

Returns:

Data dictionary instance for metadata queries

dispatch_execute(cursor, statement)

Execute a single SQL statement.

Must be implemented by each driver for database-specific execution logic.

Parameters:

• cursor (Connection) -- Database cursor/connection object

• statement (SQL) -- SQL statement object with all necessary data and configuration

Return type:

ExecutionResult

Returns:

ExecutionResult with execution data

dispatch_execute_many(cursor, statement)

Execute SQL with multiple parameter sets (executemany).

Must be implemented by each driver for database-specific executemany logic.

Parameters:

• cursor (Connection) -- Database cursor/connection object

• statement (SQL) -- SQL statement object with all necessary data and configuration

Return type:

ExecutionResult

Returns:

ExecutionResult with execution data for the many operation

dispatch_execute_script(cursor, statement)

Execute a SQL script containing multiple statements.

Default implementation splits the script and executes statements individually. Drivers can override for database-specific script execution methods.

Parameters:

• cursor (Connection) -- Database cursor/connection object

• statement (SQL) -- SQL statement object with all necessary data and configuration

Return type:

ExecutionResult

Returns:

ExecutionResult with script execution data including statement counts

collect_rows(cursor, fetched)

Collect rows from cursor after fetchall for the direct execution path.

Adapters should override this method to provide optimized row collection that bypasses full dispatch_execute overhead.

Parameters:

• cursor (Connection) -- Database cursor with description metadata.

• fetched (list[typing.Any]) -- Rows returned from cursor.fetchall().

Return type:

tuple[list[typing.Any], list[str], int]

Returns:

Tuple of (data, column_names, row_count).

Raises:

NotImplementedError -- If the adapter does not implement this method.

resolve_rowcount(cursor)

Resolve the number of affected rows from cursor for the direct execution path.

Adapters should override this method to provide optimized rowcount resolution that bypasses full dispatch_execute overhead.

Parameters:

cursor (Connection) -- Database cursor with rowcount metadata.

Return type:

int

Returns:

Number of affected rows, or 0 when unknown.

Raises:

NotImplementedError -- If the adapter does not implement this method.

begin()

Begin a database transaction on the current connection.

Return type:

None

commit()

Commit the current transaction on the current connection.

Return type:

None

rollback()

Rollback the current transaction on the current connection.

Return type:

None

with_cursor(connection)

Create and return a context manager for cursor acquisition and cleanup.

Returns a context manager that yields a cursor for database operations. Concrete implementations handle database-specific cursor creation and cleanup.

Return type:

ArrowOdbcCursor

handle_database_exceptions()

Handle database-specific exceptions and wrap them appropriately.

Return type:

ArrowOdbcExceptionHandler

Returns:

Exception handler with deferred exception pattern for mypyc compatibility. The handler stores mapped exceptions in pending_exception rather than raising from __exit__ to avoid ABI boundary violations.

select_to_arrow(statement, /, *parameters, statement_config=None, return_format='table', native_only=False, batch_size=None, arrow_schema=None, **kwargs)

Execute a query and return native Arrow results.

bulk_insert_arrow(target_table, source, *, chunk_size=None)

Insert an Arrow table or reader into a database table.

Return type:

None

Data Dictionary

class sqlspec.adapters.arrow_odbc.data_dictionary.ArrowOdbcDataDictionary

Bases: SyncDataDictionaryBase

Runtime-dialect data dictionary for generic ODBC connections.

dialect: ClassVar[str] = 'sqlite'

Dialect identifier. Must be defined by subclasses as a class attribute.

__init__(dialect='sqlite')

get_dialect_config()

Return the runtime dialect configuration for this data dictionary.

Return type:

DialectConfig

get_query(name)

Return a named SQL query for the runtime dialect.

Return type:

SQL

get_query_text(name)

Return raw SQL text for a named runtime dialect query.

Return type:

str

resolve_schema(schema)

Return a schema name using runtime dialect defaults when missing.

Return type:

str | None

get_version(driver)

Get database version information when the runtime dialect provides a query.

Return type:

VersionInfo | None

get_feature_flag(driver, feature)

Check whether the runtime dialect supports a feature.

Return type:

bool

get_optimal_type(driver, type_category)

Get the optimal runtime dialect type for a category.

Return type:

str

get_tables(driver, schema=None)

Get table metadata for dialects with bundled catalog queries.

Return type:

list[TableMetadata]

get_columns(driver, table=None, schema=None)

Get column metadata for dialects with bundled catalog queries.

Return type:

list[ColumnMetadata]

get_indexes(driver, table=None, schema=None)

Get index metadata for dialects with bundled catalog queries.

Return type:

list[IndexMetadata]

get_foreign_keys(driver, table=None, schema=None)

Get foreign-key metadata for dialects with bundled catalog queries.

Return type:

list[ForeignKeyMetadata]