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.
Documentation
See the python-oracledb Documentation and Release
Notes.
Help
Questions can be asked in GitHub Discussions.
Problem reports can be raised in GitHub Issues.
Tests
See /tests
Contributing
This project welcomes contributions from the community. Before submitting a
pull request, please review our contribution guide.
Security
Please consult the security guide for our responsible security
vulnerability disclosure process.
License
See LICENSE, THIRD_PARTY_LICENSES, and
NOTICE.