1. Introduction to the Python Driver for Oracle Database — python-oracledb 3.2.0b1 documentation (original) (raw)

The python-oracledb driver is a Python module that enables access to Oracle Database. It conforms to the Python Database API v2.0 Specification with a considerable number of additions and a couple of exclusions. Synchronous and concurrent coding styles are supported. It is distributed under an open-sourcelicense.

The module is available from standard package repositories including PyPI, conda-forge, and yum.oracle.com. The source code is hosted at github.com/oracle/python-oracledb.

This module is currently tested with Python 3.9, 3.10, 3.11, 3.12, and 3.13 against Oracle Database 23ai, 21c, 19c, 18c, 12c, and 11gR2. Previous versions of python-oracledb supported older Python versions.

Changes in python-oracledb releases can be found in the release notes.

The python-oracledb driver is the renamed, major version successor to cx_Oracle 8.3. For upgrade information, see Upgrading from cx_Oracle 8.3 to python-oracledb. The cx_Oracle driver is obsolete and should not be used for new development.

1.1. Getting Started

See Quick Start python-oracledb Installation.

Runnable examples are in the GitHub samples directory. A tutorial Python and Oracle Database Tutorial: The New Wave of Scriptingis also available.

1.2. Architecture

Python-oracledb is a ‘Thin’ driver with an optional ‘Thick’ mode enabled by an application setting.

1.2.1. python-oracledb Thin Mode Architecture

By default, python-oracledb allows connecting directly to Oracle Database 12.1 or later. This Thin mode does not need Oracle Client libraries.

architecture of the python-oracledb driver in Thin mode

Fig. 1.1 Architecture of the python-oracledb driver in Thin mode

The figure shows the architecture of python-oracledb. Users interact with a Python application, for example by making web requests. The application program makes calls to python-oracledb functions. The connection from python-oracledb Thin mode to the Oracle Database is established directly. The database can be on the same machine as Python, or it can be remote.

The Oracle Net behavior can optionally be configured by using atnsnames.ora file and with application settings. See Optional Oracle Net Configuration Files.

1.2.2. python-oracledb Thick Mode Architecture

Python-oracledb is said to be in ‘Thick’ mode when it links with Oracle Client libraries. An application script runtime option enables this mode by loading the libraries, see Enabling python-oracledb Thick mode. This gives you some additional functionality. Depending on the version of the Oracle Client libraries, this mode of python-oracledb can connect to Oracle Database 9.2 or later.

architecture of the python-oracledb driver in Thick mode

Fig. 1.2 Architecture of the python-oracledb driver in Thick mode

The figure shows the architecture of the python-oracledb Thick mode. Users interact with a Python application, for example by making web requests. The application program makes calls to python-oracledb functions. Internally, python-oracledb dynamically loads Oracle Client libraries. Connections from python-oracledb Thick mode to Oracle Database are established using the Oracle Client libraries. The database can be on the same machine as Python, or it can be remote.

To use python-oracledb Thick mode, the Oracle Client libraries must be installed separately, see Installing python-oracledb. The libraries can be from an installation of Oracle Instant Client, from a full Oracle Client installation (such as installed by Oracle’s GUI installer), or even from an Oracle Database installation (if Python is running on the same machine as the database). Oracle’s standard client-server version interoperability allows connection to both older and newer databases from different Oracle Client library versions.

Some behaviors of the Oracle Client libraries can optionally be configured with an oraaccess.xml file, for example to enable auto-tuning of a statement cache. See Optional Oracle Client Configuration File.

The Oracle Net behavior can optionally be configured with files such astnsnames.ora and sqlnet.ora, for example to enable network encryption. See Optional Oracle Net Configuration Files.

Oracle environment variables that are set before python-oracledb first creates a database connection may affect python-oracledb Thick mode behavior. SeeOracle Environment Variables for python-oracledb.

1.3. Feature Highlights of python-oracledb

The python-oracledb feature highlights are:

See Appendix A: Oracle Database Features Supported by python-oracledb for more information.