python-oracledb

Python-oracledb is an open-source Python extension module allowing
Python programs to connect to Oracle Database. 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 maintained by Oracle.

Python-oracledb is used for executing SQL and PL/SQL; for calling NoSQL-style
document APIs; for working with data frames; for receiving database
notifications and messages; and for starting and stopping the database. It has
features for high availability and security. It is used by many Python
Frameworks, SQL Generators, ORMs, and libraries.

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 python-oracledb Installation 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"
cs = "localhost/orclpdb"
# 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.9 through 3.13.

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
libraries 11.2 through 23ai.
Oracle Database

Thin mode: Oracle Database 12.1 (or later) is required.

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