OracleDB¶

Sync and async Oracle adapter using python-oracledb. Features native pipeline mode for multi-statement batching, BLOB support, and LOB coercion with byte-length thresholds.

Sync Configuration¶

class sqlspec.adapters.oracledb.OracleSyncConfig[source]¶

Bases: SyncDatabaseConfig[Connection, OracleSyncConnectionPool, OracleSyncDriver]

Configuration for Oracle synchronous database connections.

driver_type¶: alias of OracleSyncDriver

migration_tracker_type¶: alias of OracleSyncMigrationTracker

__init__(*, connection_config=None, connection_instance=None, migration_config=None, statement_config=None, driver_features=None, bind_key=None, extension_config=None, **kwargs)[source]¶

Initialize Oracle synchronous configuration.

Parameters:

connection_config¶ – Connection and pool configuration parameters.
connection_instance¶ – Existing pool instance to use.
migration_config¶ – Migration configuration.
statement_config¶ – Default SQL statement configuration.
driver_features¶ – Optional driver feature configuration (TypedDict or dict).
bind_key¶ – Optional unique identifier for this configuration.
extension_config¶ – Extension-specific configuration (e.g., Litestar plugin settings).
**kwargs¶ – Additional keyword arguments.

create_connection()[source]¶

Create a single connection (not from pool).

Return type:: Connection
Returns:: An Oracle Connection instance.

provide_connection()[source]¶

Provide a connection context manager.

Return type:: OracleSyncConnectionContext
Returns:: An Oracle Connection context manager.

provide_session(*_args, statement_config=None, **_kwargs)[source]¶

Provide a driver session context manager.

Parameters:

*_args¶ (Any) – Positional arguments (unused).
statement_config¶ (StatementConfig | None) – Optional statement configuration override.
**_kwargs¶ (Any) – Keyword arguments (unused).

Return type:

OracleSyncSessionContext

Returns:

An OracleSyncDriver session context manager.

provide_pool()[source]¶

Provide pool instance.

Return type:: ConnectionPool
Returns:: The connection pool.

get_signature_namespace()[source]¶

Get the signature namespace for OracleDB types.

Provides OracleDB-specific types for Litestar framework recognition.

Return type:: dict[str, typing.Any]
Returns:: Dictionary mapping type names to types.

Async Configuration¶

class sqlspec.adapters.oracledb.OracleAsyncConfig[source]¶

Bases: AsyncDatabaseConfig[AsyncConnection, OracleAsyncConnectionPool, OracleAsyncDriver]

Configuration for Oracle asynchronous database connections.

driver_type¶: alias of OracleAsyncDriver

migration_tracker_type¶: alias of OracleAsyncMigrationTracker

Initialize Oracle asynchronous configuration.

Parameters:

connection_config¶ – Connection and pool configuration parameters.
connection_instance¶ – Existing pool instance to use.
migration_config¶ – Migration configuration.
statement_config¶ – Default SQL statement configuration.
driver_features¶ – Optional driver feature configuration (TypedDict or dict).
bind_key¶ – Optional unique identifier for this configuration.
extension_config¶ – Extension-specific configuration (e.g., Litestar plugin settings).
**kwargs¶ – Additional keyword arguments.

async close_pool()[source]¶

Close the connection pool.

Return type:: None

async create_connection()[source]¶

Create a single async connection (not from pool).

Return type:: AsyncConnection
Returns:: An Oracle AsyncConnection instance.

provide_connection()[source]¶

Provide an async connection context manager.

Return type:: OracleAsyncConnectionContext
Returns:: An Oracle AsyncConnection context manager.

provide_session(*_args, statement_config=None, **_kwargs)[source]¶

Provide an async driver session context manager.

Parameters:

*_args¶ (Any) – Positional arguments (unused).
statement_config¶ (StatementConfig | None) – Optional statement configuration override.
**_kwargs¶ (Any) – Keyword arguments (unused).

Return type:

OracleAsyncSessionContext

Returns:

An OracleAsyncDriver session context manager.

async provide_pool()[source]¶

Provide async pool instance.

Return type:: AsyncConnectionPool
Returns:: The async connection pool.

get_signature_namespace()[source]¶

Get the signature namespace for OracleAsyncConfig types.

Return type:: dict[str, typing.Any]
Returns:: Dictionary mapping type names to types.

Sync Driver¶

class sqlspec.adapters.oracledb.OracleSyncDriver[source]¶

Bases: OraclePipelineMixin, SyncDriverAdapterBase

Synchronous Oracle Database driver.

Provides Oracle Database connectivity with parameter style conversion, error handling, and transaction management.

__init__(connection, statement_config=None, driver_features=None)[source]¶

dispatch_execute(cursor, statement)[source]¶

Execute single SQL statement with Oracle data handling.

Parameters:

cursor¶ (Cursor) – Oracle cursor object
statement¶ (SQL) – SQL statement to execute

Return type:

ExecutionResult

Returns:

Execution result containing data for SELECT statements or row count for others

dispatch_execute_many(cursor, statement)[source]¶

Execute SQL with multiple parameter sets using Oracle batch processing.

Parameters:

cursor¶ (Cursor) – Oracle cursor object
statement¶ (SQL) – SQL statement with multiple parameter sets

Return type:

ExecutionResult

Returns:

Execution result with affected row count

Raises:

ValueError – If no parameters are provided

dispatch_execute_script(cursor, statement)[source]¶

Execute SQL script with statement splitting and parameter handling.

Parameters are embedded as static values for script execution compatibility.

Parameters:

cursor¶ (Cursor) – Oracle cursor object
statement¶ (SQL) – SQL script statement to execute

Return type:

ExecutionResult

Returns:

Execution result containing statement count and success information

begin()[source]¶

Begin a database transaction.

Oracle handles transactions automatically, so this is a no-op.

Return type:: None

commit()[source]¶

Commit the current transaction.

Raises:: SQLSpecError – If commit fails
Return type:: None

rollback()[source]¶

Rollback the current transaction.

Raises:: SQLSpecError – If rollback fails
Return type:: None

with_cursor(connection)[source]¶

Create context manager for Oracle cursor.

Parameters:: connection¶ (Connection) – Oracle database connection
Return type:: OracleSyncCursor
Returns:: Context manager for cursor operations

handle_database_exceptions()[source]¶

Handle database-specific exceptions and wrap them appropriately.

Return type:: OracleSyncExceptionHandler

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

Execute query and return results as Apache Arrow format using Oracle native support.

This implementation uses Oracle’s native execute_df()/fetch_df_all() methods which return OracleDataFrame objects with Arrow PyCapsule interface, providing zero-copy data transfer and 5-10x performance improvement over dict conversion. If native Arrow is unavailable and native_only is False, it falls back to the conversion path.

Parameters:

statement¶ – SQL query string, Statement, or QueryBuilder
*parameters¶ – Query parameters (same format as execute()/select())
statement_config¶ – Optional statement configuration override
return_format¶ – “table” for pyarrow.Table (default), “batch” for RecordBatch, “batches” for list of RecordBatch, “reader” for RecordBatchReader
native_only¶ – If True, raise error if native Arrow is unavailable
batch_size¶ – Rows per batch when using “batch” or “batches” format
arrow_schema¶ – Optional pyarrow.Schema for type casting
**kwargs¶ – Additional keyword arguments

Returns:

ArrowResult containing pyarrow.Table or RecordBatch

Examples

>>> result = driver.select_to_arrow(
...     "SELECT * FROM users WHERE age > :1", (18,)
... )
>>> df = result.to_pandas()
>>> print(df.head())

execute_stack(stack, *, continue_on_error=False)[source]¶

Execute a StatementStack using Oracle’s pipeline when available.

Return type:: tuple[StackResult, ...]

select_to_storage(statement, destination, /, *parameters, statement_config=None, partitioner=None, format_hint=None, telemetry=None, **kwargs)[source]¶: Execute a query and stream Arrow-formatted output to storage (sync).

load_from_arrow(table, source, *, partitioner=None, overwrite=False, telemetry=None)[source]¶: Load Arrow data into Oracle using batched executemany calls.

load_from_storage(table, source, *, file_format, partitioner=None, overwrite=False)[source]¶

Load staged artifacts into Oracle.

Return type:: StorageBridgeJob

property data_dictionary: OracledbSyncDataDictionary¶

Get the data dictionary for this driver.

Returns:: Data dictionary instance for metadata queries

collect_rows(cursor, fetched)[source]¶

Collect Oracle sync rows for the direct execution path.

Return type:: tuple[list[typing.Any], list[str], int]

resolve_rowcount(cursor)[source]¶

Resolve rowcount from Oracle cursor for the direct execution path.

Return type:: int

Async Driver¶

class sqlspec.adapters.oracledb.OracleAsyncDriver[source]¶

Bases: OraclePipelineMixin, AsyncDriverAdapterBase

Asynchronous Oracle Database driver.

Provides Oracle Database connectivity with parameter style conversion, error handling, and transaction management for async operations.

__init__(connection, statement_config=None, driver_features=None)[source]¶

async dispatch_execute(cursor, statement)[source]¶

Execute single SQL statement with Oracle data handling.

Parameters:

cursor¶ (AsyncCursor) – Oracle cursor object
statement¶ (SQL) – SQL statement to execute

Return type:

ExecutionResult

Returns:

Execution result containing data for SELECT statements or row count for others

async dispatch_execute_many(cursor, statement)[source]¶

Execute SQL with multiple parameter sets using Oracle batch processing.

Parameters:

cursor¶ (AsyncCursor) – Oracle cursor object
statement¶ (SQL) – SQL statement with multiple parameter sets

Return type:

ExecutionResult

Returns:

Execution result with affected row count

Raises:

ValueError – If no parameters are provided

async dispatch_execute_script(cursor, statement)[source]¶

Execute SQL script with statement splitting and parameter handling.

Parameters are embedded as static values for script execution compatibility.

Parameters:

cursor¶ (AsyncCursor) – Oracle cursor object
statement¶ (SQL) – SQL script statement to execute

Return type:

ExecutionResult

Returns:

Execution result containing statement count and success information

async begin()[source]¶

Begin a database transaction.

Oracle handles transactions automatically, so this is a no-op.

Return type:: None

async commit()[source]¶

Commit the current transaction.

Raises:: SQLSpecError – If commit fails
Return type:: None

async rollback()[source]¶

Rollback the current transaction.

Raises:: SQLSpecError – If rollback fails
Return type:: None

with_cursor(connection)[source]¶

Create context manager for Oracle cursor.

Parameters:: connection¶ (AsyncConnection) – Oracle database connection
Return type:: OracleAsyncCursor
Returns:: Context manager for cursor operations

handle_database_exceptions()[source]¶

Handle database-specific exceptions and wrap them appropriately.

Return type:: OracleAsyncExceptionHandler

async select_to_arrow(statement, /, *parameters, statement_config=None, return_format='table', native_only=False, batch_size=None, arrow_schema=None, **kwargs)[source]¶

Execute query and return results as Apache Arrow format using Oracle native support.

Parameters:

statement¶ – SQL query string, Statement, or QueryBuilder
*parameters¶ – Query parameters (same format as execute()/select())
statement_config¶ – Optional statement configuration override
return_format¶ – “table” for pyarrow.Table (default), “batch” for RecordBatch, “batches” for list of RecordBatch, “reader” for RecordBatchReader
native_only¶ – If True, raise error if native Arrow is unavailable
batch_size¶ – Rows per batch when using “batch” or “batches” format
arrow_schema¶ – Optional pyarrow.Schema for type casting
**kwargs¶ – Additional keyword arguments

Returns:

ArrowResult containing pyarrow.Table or RecordBatch

Examples

>>> result = await driver.select_to_arrow(
...     "SELECT * FROM users WHERE age > :1", (18,)
... )
>>> df = result.to_pandas()
>>> print(df.head())

async execute_stack(stack, *, continue_on_error=False)[source]¶

Execute a StatementStack using Oracle’s pipeline when available.

Return type:: tuple[StackResult, ...]

async select_to_storage(statement, destination, /, *parameters, statement_config=None, partitioner=None, format_hint=None, telemetry=None, **kwargs)[source]¶: Execute a query and write Arrow-compatible output to storage (async).

async load_from_arrow(table, source, *, partitioner=None, overwrite=False, telemetry=None)[source]¶: Asynchronously load Arrow data into Oracle.

async load_from_storage(table, source, *, file_format, partitioner=None, overwrite=False)[source]¶

Asynchronously load staged artifacts into Oracle.

Return type:: StorageBridgeJob

property data_dictionary: OracledbAsyncDataDictionary¶

Get the data dictionary for this driver.

Returns:: Data dictionary instance for metadata queries

collect_rows(cursor, fetched)[source]¶

Collect Oracle async rows for the direct execution path.

Uses synchronous LOB coercion. For async LOB coercion, the standard dispatch path via collect_async_rows is used instead.

Return type:: tuple[list[typing.Any], list[str], int]

resolve_rowcount(cursor)[source]¶

Resolve rowcount from Oracle cursor for the direct execution path.

Return type:: int