1. Introduction to the Python Driver for Oracle Database

The python-oracledb driver is a Python extension module that enables access to Oracle Database. It has comprehensive functionality supporting the Python Database API v2.0 Specification with a considerable number of additions and a couple of exclusions.

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.

Python-oracledb is typically installed from Python’s package repository PyPI using pip. See Installing python-oracledb for more information.

1.1. Architecture

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

1.1.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.

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 a tnsnames.ora file and with application settings. See Optional Oracle Net Configuration Files.

1.1.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.

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 as tnsnames.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. See Oracle Environment Variables for python-oracledb Thick Mode.

1.2. Feature Highlights of python-oracledb

The python-oracledb feature highlights are:

• Easy installation from PyPI

• Support for multiple Oracle Database versions

• Supports the Python Database API v2.0 Specification with a considerable number of additions and a couple of exclusions. * Works with common frameworks and ORMs

• Execution of SQL and PL/SQL statements

• Extensive Oracle data type support, including JSON, large objects (CLOB and BLOB) and binding of SQL objects

• Connection management, including connection pooling

• Oracle Database High Availability features

• Full use of Oracle Network Service infrastructure, including encrypted network traffic

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

1.3. Getting Started

See Quick Start python-oracledb Installation.

1.4. Examples and Tutorial

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