oracledb Adapter¶

from sqlspec.adapters.oracledb import (
    OracleAsyncConfig,
    OracleAsyncDriver,
    OracleAsyncExceptionHandler,
    OracleConnectionParams,
    OracleDriverFeatures,
    OraclePoolParams,
    OracleSyncConfig,
    OracleSyncDriver,
    OracleSyncExceptionHandler,
)

Synchronous and asynchronous Oracle Database adapters built on python-oracledb (Thin and Thick modes) with VECTOR, JSON, LOB, and Advanced Queuing support. Inherited execution methods are documented on SyncDriverAdapterBase and AsyncDriverAdapterBase. See the Oracle Database Setup Guide for wallet, pool, and vector configuration.

Configuration & Parameters¶

OracleSyncConfig ¶

Bases: SyncDatabaseConfig[OracleSyncConnection, 'OracleSyncConnectionPool', OracleSyncDriver]

Configuration for Oracle synchronous database connections.

OracleAsyncConfig ¶

Bases: AsyncDatabaseConfig[OracleAsyncConnection, 'OracleAsyncConnectionPool', OracleAsyncDriver]

Configuration for Oracle asynchronous database connections.

`OracleConnectionParams` ¶

Bases: TypedDict

OracleDB connection parameters forwarded to python-oracledb.

Attributes:

Name	Type	Description
`dsn`	`NotRequired[str]`	Easy Connect string, TNS alias, or full connect descriptor.
`pool_alias`	`NotRequired[str]`	Named Thick-mode pool alias registered in the driver cache.
`user`	`NotRequired[str]`	Database username for authentication.
`proxy_user`	`NotRequired[str]`	Proxy target username appended inside `[proxy_user]` credentials.
`password`	`NotRequired[str]`	Database password for the authenticating user.
`newpassword`	`NotRequired[str]`	Replacement password applied atomically during connection establishment.
`wallet_password`	`NotRequired[str]`	Passphrase decrypting an encrypted PEM `ewallet.pem` or PKCS#12 `ewallet.p12` wallet.
`access_token`	`NotRequired[OracleAccessToken]`	OAuth 2.0 or IAM bearer token string, `(token, private_key)` tuple, or refresh callable.
`host`	`NotRequired[str]`	Oracle listener hostname or IP address when building a connect descriptor.
`port`	`NotRequired[int]`	Oracle listener TCP/TCPS port (defaults to `1521`).
`protocol`	`NotRequired[OracleProtocol]`	Transport protocol (`'tcp'` or `'tcps'` for TLS/mTLS).
`https_proxy`	`NotRequired[str]`	HTTPS proxy hostname used when tunneling TCPS connections.
`https_proxy_port`	`NotRequired[int]`	HTTPS proxy TCP port used with `https_proxy`.
`service_name`	`NotRequired[str]`	Oracle database service name registered with the listener.
`instance_name`	`NotRequired[str]`	Specific RAC instance name targeted within the service.
`sid`	`NotRequired[str]`	Legacy Oracle System Identifier used when `service_name` is unavailable.
`server_type`	`NotRequired[OracleServerType]`	Server handler mode (`'dedicated'`, `'shared'`, or `'pooled'` for DRCP).
`cclass`	`NotRequired[str]`	Database Resident Connection Pooling (DRCP) connection class name.
`purity`	`NotRequired[OraclePurity]`	DRCP session purity (`PURITY_NEW` or `PURITY_SELF`).
`expire_time`	`NotRequired[int]`	Dead-connection detection probe interval in minutes.
`externalauth`	`NotRequired[bool]`	Authenticate via OS credentials or an Oracle external password store wallet.
`mode`	`NotRequired[OracleAuthMode]`	Administrative privilege mode such as `AUTH_MODE_SYSDBA` or `AUTH_MODE_SYSOPER`.
`wallet_location`	`NotRequired[str]`	Directory path containing `ewallet.pem` or `ewallet.p12` for mTLS.
`config_dir`	`NotRequired[str]`	Directory path containing `tnsnames.ora` and `sqlnet.ora` configuration files.
`tcp_connect_timeout`	`NotRequired[float]`	Maximum seconds to wait when establishing the initial TCP socket.
`retry_count`	`NotRequired[int]`	Number of connection-level retry attempts across listener endpoints.
`retry_delay`	`NotRequired[int]`	Delay in seconds between connection retry attempts.
`ssl_server_dn_match`	`NotRequired[bool]`	Verify that the server certificate distinguished name matches the target service.
`ssl_server_cert_dn`	`NotRequired[str]`	Expected distinguished name on the Oracle server TLS certificate.
`events`	`NotRequired[bool]`	Enable Thick-mode Continuous Query Notification and FAN HA event delivery.
`disable_oob`	`NotRequired[bool]`	Disable TCP out-of-band break messages on networks that drop urgent packets.
`stmtcachesize`	`NotRequired[int]`	Per-connection cursor statement cache size.
`edition`	`NotRequired[str]`	Edition-Based Redefinition (EBR) edition name activated on connect.
`tag`	`NotRequired[str]`	Pool session state tag requested when acquiring a connection.
`matchanytag`	`NotRequired[bool]`	Allow acquiring a pooled connection with a different tag when an exact match is unavailable.
`appcontext`	`NotRequired[list[OracleAppContext]]`	Initial `(namespace, name, value)` application context entries set on connect.
`shardingkey`	`NotRequired[list[Any]]`	Primary sharding key values routing the connection to an Oracle shard.
`supershardingkey`	`NotRequired[list[Any]]`	Composite super-sharding key values for multi-tier sharded topologies.
`debug_jdwp`	`NotRequired[str]`	JDWP `host:port` endpoint attached for PL/SQL and Java stored-procedure debugging.
`connection_id_prefix`	`NotRequired[str]`	Prefix prepended to driver-generated end-to-end diagnostic connection identifiers.
`ssl_context`	`NotRequired[Any]`	Custom `ssl.SSLContext` overriding default Thin-mode TLS verification.
`sdu`	`NotRequired[int]`	Oracle Net Session Data Unit buffer size in bytes.
`pool_boundary`	`NotRequired[OraclePoolBoundary]`	Implicit DRCP/PRCP release boundary (`'statement'` or `'transaction'`).
`use_tcp_fast_open`	`NotRequired[bool]`	Enable TCP Fast Open (TFO) for Oracle Autonomous Database connections.
`ssl_version`	`NotRequired[TLSVersion]`	Minimum or pinned `ssl.TLSVersion` negotiated for TCPS connections.
`program`	`NotRequired[str]`	Client program name reported in `V$SESSION.PROGRAM`.
`machine`	`NotRequired[str]`	Client host name reported in `V$SESSION.MACHINE`.
`terminal`	`NotRequired[str]`	Client terminal identifier reported in `V$SESSION.TERMINAL`.
`osuser`	`NotRequired[str]`	Operating system username reported in `V$SESSION.OSUSER`.
`driver_name`	`NotRequired[str]`	Client driver label reported in `V$SESSION_CONNECT_INFO.CLIENT_DRIVER`.
`use_sni`	`NotRequired[bool]`	Send TLS Server Name Indication (SNI) to bypass double-handshake listener negotiation.
`thick_mode_dsn_passthrough`	`NotRequired[bool]`	Forward the raw DSN string unchanged to Oracle Client libraries in Thick mode.
`extra_auth_params`	`NotRequired[dict[str, Any]]`	Additional provider parameters passed to cloud token authentication plugins.
`pool_name`	`NotRequired[str]`	Explicit server-side DRCP/PRCP pool name when multiple pools exist.
`on_connect_callback`	`NotRequired[Callable[..., Any]]`	Driver-level callback invoked by `python-oracledb` immediately on physical connect.
`handle`	`NotRequired[int]`	Raw OCI service context pointer wrapped in Thick mode.
`extra`	`NotRequired[dict[str, Any]]`	Additional keyword arguments merged into `oracledb.connect` or `create_pool`.
`topology`	`NotRequired[OracleTopologyConfig \| dict[str, Any]]`	Multi-endpoint RAC/Data Guard topology descriptor compiled into a TNS `DESCRIPTION`.
`wallet_zip`	`NotRequired[str \| Path \| bytes]`	Autonomous Database wallet ZIP path, directory, or raw bytes extracted into a secure temporary directory.
`tns_alias`	`NotRequired[str]`	Alias resolved from `tnsnames.ora` inside `config_dir` or an extracted `wallet_zip`.

`OraclePoolParams` ¶

Bases: OracleConnectionParams

OracleDB session pool parameters extending OracleConnectionParams.

Attributes:

Name	Type	Description
`thick_mode`	`NotRequired[bool]`	Initialize Oracle Client Thick mode via `oracledb.init_oracle_client()` before creating the pool.
`lib_dir`	`NotRequired[str]`	Filesystem path to Oracle Instant Client libraries implying Thick mode.
`pool_class`	`NotRequired[type[Any]]`	Custom `ConnectionPool` subclass passed to `python-oracledb`.
`params`	`NotRequired[PoolParams]`	Pre-constructed `oracledb.PoolParams` instance merged with keyword settings.
`min`	`NotRequired[int]`	Minimum number of sessions maintained in the pool.
`max`	`NotRequired[int]`	Maximum number of concurrent sessions permitted in the pool.
`increment`	`NotRequired[int]`	Number of new sessions opened at once when all pooled sessions are busy.
`connectiontype`	`NotRequired[type[Any]]`	Custom `oracledb.Connection` subclass instantiated for pooled sessions.
`getmode`	`NotRequired[OraclePoolGetMode]`	Behavior when the pool is at capacity (`POOL_GETMODE_WAIT`, `NOWAIT`, `FORCEGET`, or `TIMEDWAIT`).
`homogeneous`	`NotRequired[bool]`	Use identical database credentials across all pooled sessions (defaults to `True`).
`timeout`	`NotRequired[int]`	Idle seconds after which surplus sessions above `min` are closed.
`wait_timeout`	`NotRequired[int]`	Maximum milliseconds to wait for an available session under `POOL_GETMODE_TIMEDWAIT`.
`max_lifetime_session`	`NotRequired[int]`	Maximum lifetime in seconds before a pooled session is retired.
`session_callback`	`NotRequired[Callable[..., Any]]`	Callback `(connection, requested_tag)` invoked when a pooled session is acquired.
`max_sessions_per_shard`	`NotRequired[int]`	Maximum pooled sessions allocated to any single Oracle shard.
`soda_metadata_cache`	`NotRequired[bool]`	Enable Thick-mode SODA collection metadata caching across pooled sessions.
`ping_interval`	`NotRequired[int]`	Idle seconds elapsed before a pooled session is health-checked on checkout.
`ping_timeout`	`NotRequired[int]`	Maximum milliseconds allowed for a checkout health-check ping before replacing the session.

`OracleDriverFeatures` ¶

Bases: TypedDict

Oracle driver feature flags controlling VECTOR/UUID codecs, LOB coercion, and enterprise hooks.

Native async pipeline execution is runtime-gated on Oracle Database 26ai+ in Thin mode and can be disabled via SQLSPEC_ORACLE_DISABLE_PIPELINE.

Attributes:

Name	Type	Description
`enable_numpy_vectors`	`NotRequired[bool]`	Register bidirectional NumPy `ndarray` handlers for Oracle 23ai+ `VECTOR` columns (defaults to `True` when NumPy is installed).
`enable_lowercase_column_names`	`NotRequired[bool]`	Normalize unquoted uppercase Oracle column names to lowercase while preserving quoted aliases (defaults to `True`).
`enable_uuid_binary`	`NotRequired[bool]`	Convert Python `UUID` values to and from `RAW(16)` columns.
`vector_return_format`	`NotRequired[OracleVectorReturnFormat]`	Decoded type for dense `VECTOR` columns (`'numpy'`, `'list'`, or `'array'`).
`oracle_varchar2_byte_limit`	`NotRequired[int]`	UTF-8 byte threshold above which `str` parameters bind as `DB_TYPE_CLOB` (defaults to `4000`).
`oracle_raw_byte_limit`	`NotRequired[int]`	Byte threshold above which `bytes` parameters bind as `DB_TYPE_BLOB` (defaults to `2000`).
`arraysize`	`NotRequired[int]`	Per-cursor `arraysize` row fetch buffer override.
`prefetchrows`	`NotRequired[int]`	Per-cursor `prefetchrows` initial round-trip prefetch count override.
`fetch_lobs`	`NotRequired[bool]`	Return LOB columns as locator objects when `True` or inline `str`/`bytes` when `False`.
`fetch_decimals`	`NotRequired[bool]`	Return `NUMBER` columns as `decimal.Decimal` values when `True`.
`on_connection_create`	`NotRequired[Callable[..., Any]]`	Hook `(connection, tag)` invoked after built-in JSON, VECTOR, and UUID handlers are registered.
`enable_events`	`NotRequired[bool]`	Enable SQLSpec event channels (separate from `connection_config['events']` FAN/CQN notifications).
`events_backend`	`NotRequired[OracleEventsBackend]`	Event queue backend (`'poll_queue'` default, `'aq'`, or `'txeventq'`).
`enable_direct_path_load`	`NotRequired[bool]`	Route `load_from_arrow` through Thin-mode `Connection.direct_path_load` with `executemany` fallback (defaults to `True`).
`session_context_hook`	`NotRequired[OracleSessionContextConfig \| dict[str, Any]]`	Declarative `DBMS_SESSION` / `CLIENT_IDENTIFIER` context applied on checkout and cleared on release.
`enable_session_tracing`	`NotRequired[bool]`	Piggyback active correlation and trace identifiers onto `module`, `action`, `client_identifier`, and `econtext_id` in zero extra RTTs.
`dbms_cloud_credential`	`NotRequired[str \| None]`	Default `DBMS_CLOUD` credential name used for server-side `DBMS_CLOUD.COPY_DATA` object-store loads.

Driver & Pool¶

OracleSyncDriver ¶

Bases: OraclePipelineMixin, SyncDriverAdapterBase

Synchronous Oracle Database driver.

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

OracleAsyncDriver ¶

Bases: OraclePipelineMixin, AsyncDriverAdapterBase

Asynchronous Oracle Database driver.

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

OracleSyncExceptionHandler ¶

Bases: BaseSyncExceptionHandler

Synchronous context manager for handling Oracle database exceptions.

Maps Oracle ORA-XXXXX error codes to SQLSpec exceptions stored on pending_exception.

OracleAsyncExceptionHandler ¶

Bases: BaseAsyncExceptionHandler

Async context manager for handling Oracle database exceptions.

Maps Oracle ORA-XXXXX error codes to SQLSpec exceptions stored on pending_exception.

Extension Stores¶

OracleSyncStore ¶

Bases: BaseSQLSpecStore['OracleSyncConfig']

Oracle session store using sync OracleDB driver.

Implements server-side session storage for Litestar using Oracle Database via the synchronous python-oracledb driver. Uses async_() wrapper to provide an async interface compatible with the Store protocol.

Provides efficient session management with

Sync operations wrapped for async compatibility
MERGE statement for atomic UPSERT
Automatic expiration handling
Efficient cleanup of expired sessions
Optional In-Memory Column Store support (requires Oracle Database In-Memory license)

Parameters:

Name	Type	Description	Default
`config`	`OracleSyncConfig`	OracleSyncConfig with extension_config["litestar"] settings.	required

OracleAsyncStore ¶

Bases: BaseSQLSpecStore['OracleAsyncConfig']

Oracle session store using async OracleDB driver.

Implements server-side session storage for Litestar using Oracle Database via the async python-oracledb driver. Provides efficient session management with: - Native async Oracle operations - MERGE statement for atomic UPSERT - Automatic expiration handling - Efficient cleanup of expired sessions - Optional In-Memory Column Store support (requires Oracle Database In-Memory license)

Parameters:

Name	Type	Description	Default
`config`	`OracleAsyncConfig`	OracleAsyncConfig with extension_config["litestar"] settings.	required

OracleSyncADKStore ¶

Bases: BaseSyncADKStore['OracleSyncConfig']

Oracle synchronous ADK store using oracledb sync driver.

Implements session and event storage for Google Agent Development Kit using Oracle Database via the python-oracledb synchronous driver. Provides: - Session state management with version-specific JSON storage - Full-fidelity event storage via event_data column - Atomic create_event_and_update_state for durable session mutations - TIMESTAMP WITH TIME ZONE for timezone-aware timestamps - Foreign key constraints with cascade delete - Efficient upserts using MERGE statement

Parameters:

Name	Type	Description	Default
`config`	`OracleSyncConfig`	OracleSyncConfig with extension_config["adk"] settings.	required

Notes

JSON storage type detected by capability (native JSON, BLOB IS JSON, or plain LOB)
event_data stored as JSON (21c+) or BLOB (older versions)
TIMESTAMP WITH TIME ZONE for timezone-aware timestamps
Named parameters using :param_name
State merging handled at application level
owner_id_column supports NUMBER, VARCHAR2, RAW for Oracle FK types
Configuration is read from config.extension_config["adk"]

OracleAsyncADKStore ¶

Bases: BaseAsyncADKStore['OracleAsyncConfig']

Oracle async ADK store using oracledb async driver.

Implements session and event storage for Google Agent Development Kit using Oracle Database via the python-oracledb async driver. Provides: - Session state management with version-specific JSON storage - Full-fidelity event storage via event_data column - Atomic append_event_and_update_state for durable session mutations - TIMESTAMP WITH TIME ZONE for timezone-aware timestamps - Foreign key constraints with cascade delete - Efficient upserts using MERGE statement

Parameters:

Name	Type	Description	Default
`config`	`OracleAsyncConfig`	OracleAsyncConfig with extension_config["adk"] settings.	required

Notes

JSON storage type detected by capability (native JSON, BLOB IS JSON, or plain LOB)
event_data stored as JSON (21c+) or BLOB (older versions)
TIMESTAMP WITH TIME ZONE for timezone-aware timestamps
Named parameters using :param_name
State merging handled at application level
owner_id_column supports NUMBER, VARCHAR2, RAW for Oracle FK types
Configuration is read from config.extension_config["adk"]

OracleSyncADKMemoryStore ¶

Bases: BaseSyncADKMemoryStore['OracleSyncConfig']

Oracle ADK memory store using sync oracledb driver.

OracleAsyncADKMemoryStore ¶

Bases: BaseAsyncADKMemoryStore['OracleAsyncConfig']

Oracle ADK memory store using async oracledb driver.

OracleSyncEventQueueStore ¶

Bases: BaseEventQueueStore['OracleSyncConfig']

Oracle sync event queue store with auto-detected JSON storage.

Automatically detects the Oracle version and uses the optimal JSON storage: - Oracle 21c+: Native JSON type - Oracle 12c-19c: BLOB with IS JSON constraint - Oracle 11g: Plain BLOB

Parameters:

Name	Type	Description	Default
`config`	`OracleSyncConfig`	OracleSyncConfig with extension_config["events"] settings.	required

OracleAsyncEventQueueStore ¶

Bases: BaseEventQueueStore['OracleAsyncConfig']

Oracle async event queue store with auto-detected JSON storage.

Automatically detects the Oracle version and uses the optimal JSON storage: - Oracle 21c+: Native JSON type - Oracle 12c-19c: BLOB with IS JSON constraint - Oracle 11g: Plain BLOB

Parameters:

Name	Type	Description	Default
`config`	`OracleAsyncConfig`	OracleAsyncConfig with extension_config["events"] settings.	required

OracleSyncAQEventBackend ¶

Oracle AQ backend for sync Oracle adapters.

OracleAsyncAQEventBackend ¶

Oracle AQ backend for async Oracle adapters.

oracledb Adapter¶

Configuration & Parameters¶

OracleSyncConfig ¶

OracleAsyncConfig ¶

OracleConnectionParams ¶

OraclePoolParams ¶

OracleDriverFeatures ¶

Driver & Pool¶

OracleSyncDriver ¶

OracleAsyncDriver ¶

OracleSyncExceptionHandler ¶

OracleAsyncExceptionHandler ¶

Extension Stores¶

OracleSyncStore ¶

OracleAsyncStore ¶

OracleSyncADKStore ¶

OracleAsyncADKStore ¶

OracleSyncADKMemoryStore ¶

OracleAsyncADKMemoryStore ¶

OracleSyncEventQueueStore ¶

OracleAsyncEventQueueStore ¶

OracleSyncAQEventBackend ¶

OracleAsyncAQEventBackend ¶

`OracleConnectionParams` ¶

`OraclePoolParams` ¶

`OracleDriverFeatures` ¶