python-oracledb

oracledb (python-oracledb) is the official, Oracle-maintained Python driver for Oracle Database, conforming to the Python Database API 2.0 specification (PEP 249) with a large set of Oracle-specific extensions. It is the direct successor to the older cx_Oracle driver, rebuilt around a ‘Thin’ mode that connects straight to the database over the network with zero external client libraries, alongside an optional ‘Thick’ mode that loads Oracle Instant Client for advanced features not yet available in Thin mode.

Beyond basic query execution, it supports synchronous and asyncio-based connections, connection pooling, PL/SQL execution, LOB handling, Advanced Queuing (AQ), continuous query notification, SODA document access, Arrow-based dataframes for fast data ingestion, and high-availability features like transparent application failover. It is widely used as the underlying driver for Python ORMs, SQL generators, and data pipelines that target Oracle Database.

What You Get

• A PEP 249-compliant Connection/Cursor API for executing SQL and PL/SQL, with Oracle-specific extensions layered on top
• Thin mode that connects directly to Oracle Database over the network with no Oracle Client libraries to install
• Optional Thick mode (via Oracle Instant Client) for advanced features and older database versions
• Native asyncio support for connections, cursors, and pooling alongside the classic synchronous API
• Connection pooling with configurable sizing, session callbacks, and drain/reconfigure support
• Support for LOBs, DbObjects (Oracle object types), Advanced Queuing, SODA documents, and Arrow-based DataFrames
• High-availability features including Application Continuity, Transparent Application Failover, and connection health checks

Common Use Cases

• Building Python web services and backends that read and write Oracle Database directly
• Powering the Oracle dialect underneath ORMs and SQL toolkits (e.g. SQLAlchemy, Django) without a separate client install
• ETL and data pipelines that bulk-load or extract data from Oracle Database, including via Arrow DataFrames for analytics tooling
• Async services (FastAPI, aiohttp, etc.) that need non-blocking Oracle Database access via the asyncio API
• Enterprise integrations that call PL/SQL procedures, queue messages via AQ, or react to database change notifications

Under The Hood

Architecture The package is split into a stable Python-facing API (src/oracledb/connection.py, cursor.py, pool.py, dataframe.py, etc.) sitting atop two swappable implementation backends selected at runtime via driver_mode.py: thin_impl.pyx, a pure-Python/Cython reimplementation of the Oracle Net protocol requiring no external libraries, and thick_impl.pyx, a thin wrapper over the ODPI-C C library for feature parity with older Oracle Client releases. Both backends implement a shared base_impl.pyx/base_impl.pxd interface so the public classes (Connection, Cursor, Pool, LOB, DbObject) behave identically regardless of mode, with AsyncConnection/AsyncCursor variants layered on top for asyncio users. Many user-facing modules such as connection.py are explicitly generated from templates (see utils/build_from_template.py) to keep the sync and async code paths in lockstep.

Tech Stack Implemented primarily in Python (60%) and Cython (32%), with a small C layer (7%) for low-level protocol and encoding work, plus PL/SQL fixtures for test scaffolding. Runtime dependencies are minimal and deliberate: cryptography for Thin-mode network encryption/authentication and typing_extensions for backporting newer typing constructs; the build system uses setuptools with a Cython build backend (pyproject.toml). Supports Python 3.10 through 3.15 and is distributed as prebuilt wheels per platform plus source.

Code Quality The tests/ directory contains a large, structured suite covering connections, pooling, LOBs, AQ, SODA, dataframes, and both sync and async variants, run via tox.ini across supported Python versions. Errors are centralized through a dedicated _Error/exceptions.py model (see errors.py) that wraps both driver-specific and underlying Oracle/ODPI-C errors into consistent, documented exception types rather than leaking raw protocol failures. Every source file carries a license header and, for generated files, an explicit “do not edit directly” notice pointing at its template, indicating a deliberate, maintained code-generation discipline rather than manual drift between sync/async implementations.

API Design The public API mirrors the standard Python DB API 2.0 (connect(), Connection, Cursor.execute()) so existing Python database code ports over with minimal changes, while Oracle-specific capabilities (bind variables, DbObject types, LOBs, pipelining) are exposed as clearly named extensions rather than overloading standard methods. Async support mirrors the sync API 1:1 (AsyncConnection, AsyncCursor) rather than introducing a separate async-first surface, which keeps the learning curve low for developers already familiar with either style. Documentation is extensive (readthedocs, a dedicated samples directory with 60+ runnable scripts, and an official tutorial), and getting started requires only pip install oracledb plus a connection string with no separate client install in the default Thin mode.