Repository files navigation

Python-oracledb is an open-sourcePython extension module allowingPython programs to connect toOracle Database. The module conformsto thePython Database API 2.0 specification with a considerablenumber of additions and a couple of minor exclusions, see thefeaturelist. It is maintained by Oracle.

Python-oracledb is used for executing SQL and PL/SQL; for calling NoSQL-styledocument APIs; for working with data frames; for receiving databasenotifications and messages; and for starting and stopping the database. It hasfeatures for high availability and security. It is used by many PythonFrameworks, SQL Generators, ORMs, and libraries.

Synchronous andconcurrent coding styles are supported. Databaseoperations can optionally bepipelined.

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

Run:

python -m pip install oracledb --upgrade

Seepython-oracledb Installation for details.

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

A basic example:

import oracledbimport getpassun = "scott"cs = "localhost/orclpdb"# cs = "localhost/freepdb1"   # for Oracle Database Free users# cs = "localhost/orclpdb1"   # some databases may have this servicepw = 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)

• Python versions 3.9 through 3.13.

  Pre-built packages are available onPyPI and other repositories.

  Source code is also available.

  Previous versions of python-oracledb supported older Python versions.

• Oracle Client libraries areoptional.

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

  Thick mode: Some advanced Oracle Database functionality is currently onlyavailable when optional Oracle Client libraries are loaded bypython-oracledb. Libraries are available in the freeOracle InstantClient packages. Python-oracledb can use Oracle Clientlibraries 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 theOracle Client library version. Oracle Database's standard client-serverversion interoperability allows connection to both older and newerdatabases. For example when python-oracledb uses Oracle Client 19c libraries,then it can connect to Oracle Database 11.2 or later.

See thepython-oracledb Documentation andReleaseNotes.

Questions can be asked inGitHub Discussions.

Problem reports can be raised inGitHub Issues.

See/tests

This project welcomes contributions from the community. Before submitting apull request, pleasereview our contribution guide.

Please consult thesecurity guide for our responsible securityvulnerability disclosure process.

SeeLICENSE,THIRD_PARTY_LICENSES, andNOTICE.