python-oracledb

The python-oracledb driver is the widely used, open-source Python
extension module allowing Python programs to connect directly to Oracle
Database with no extra libraries needed. The module is built with
Cython for safety and speed. It is lightweight and high-performance. It is
stable, well tested, and has comprehensive documentation. The
module is maintained by Oracle.

The module conforms to the Python Database API 2.0 specification with
a considerable number of additions and a couple of minor exclusions, see the
feature list. It is used by many Python frameworks, SQL generators,
ORMs, and libraries.

Python-oracledb has a rich feature set which is easy to use. It gives you
control over SQL and PL/SQL statement execution; for working with data frames;
for fast data ingestion; for calling NoSQL-style document APIs; for message
queueing; for receiving database notifications; and for starting and stopping
the database. It also has high availability and security features. Synchronous
and concurrent coding styles are supported. Database operations
can optionally be pipelined.

Python-oracledb is the successor to the now obsolete cx_Oracle driver.

Python-oracledb Installation

Run:

python -m pip install oracledb --upgrade

See Installing python-oracledb for details.

Samples

Examples can be found in the /samples directory and the
Python and Oracle Database Tutorial.

A basic example:

import oracledb
import getpass

un = "scott"                  # Sample database username
cs = "localhost/orclpdb"      # Sample database connection string
# cs = "localhost/freepdb1"   # For Oracle Database Free users
# cs = "localhost/orclpdb1"   # Some databases may have this service
pw = getpass.getpass(f"Enter password for {un}@{cs}: ")

with oracledb.connect(user=un, password=pw, dsn=cs) as connection:
    with connection.cursor() as cursor:
        sql = "select sysdate from dual"
        for r in cursor.execute(sql):
            print(r)

Dependencies and Interoperability

Python versions 3.10 through 3.15.

Pre-built packages are available on PyPI and other repositories.

Source code is also available.

Previous versions of python-oracledb supported older Python versions.
Oracle Client libraries are optional.

Thin mode: By default python-oracledb runs in a 'Thin' mode which
connects directly to Oracle Database.

Thick mode: Some advanced Oracle Database functionality is currently only
available when optional Oracle Client libraries are loaded by
python-oracledb. Libraries are available in the free Oracle Instant
Client packages. Python-oracledb can use Oracle Client
Release 19 or later. Older python-oracledb versions supported older Client
versions.
Oracle Database

Thin mode: Oracle Database 12.1 or later is required.

Thick mode: Oracle Database 11.2 or later is required, depending on the
Oracle Client release. Oracle Database's standard client-server version
interoperability allows connection to both older and newer databases. For
example when python-oracledb uses Oracle Client 19 libraries, then it can
connect to Oracle Database 11.2 or later.