The python-oracledb 1.3 driver for Oracle Database

The python-oracledb driver is a Python programming language extension module allowing Python programs to connect to Oracle Database. Python-oracledb is the new name for Oracle's popular cx_Oracle driver.

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.

Getting Started

• Quick Start: Developing Python Applications for Oracle Database: Instructions for Windows, macOS, and Linux for installing python-oracledb and connecting to an existing on-premise database.

• Quick Start: Developing Python Applications for Oracle Autonomous Database: Instructions for Windows, macOS, and Linux for installing python-oracledb and connecting to an existing Oracle Autonomous Database.

• Developing Python Applications for Oracle Database: a high-level quickstart from the python-oracledb documentation for the eager user.

• Getting Started with Python and Oracle Database: An introductory tutorial using Oracle's LiveLabs learning environoment

• Python and Oracle Database Tutorial: The New Wave of Scripting: similar to the LiveLab, but aimed at users who already have python-oracledb and a database installed.

• Samples: the sample programs from the GitHub repository.

Installation

See python-oracledb Installation for detailed instructions.

Dependencies

• Python versions 3.6 through 3.11.

  Pre-built packages on PyPI are available for Windows Python 3.7 or later, for macOS Python 3.7 or later, and for Linux Python 3.6 or later.

  Source code is also available.

• Oracle Client libraries are optional.

  Thin mode: By default, python-oracledb is a 'Thin' driver which connects directly to Oracle Database. This mode does not need Oracle Client libraries.

  Thick mode: Some advanced Oracle Database functionality is currently only available via Oracle Client libraries. You can install these libraries using the free Oracle Instant Client packages. Python-oracledb works with Oracle Client libraries 11.2 through 21c. See Enabling python-oracledb Thick mode.

• Oracle Database

  Thin mode: Connects to Oracle Database 12c, 18c, 19c and 21c.

  Thick mode: Connects to Oracle Database 11.2, 12c, 18c, and 21c, 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, it can connect to Oracle Database 11.2 or later.

Documentation

See the python-oracledb Documentation and Release Notes.

You can use assistive technology products, such as screen readers, while you work with the documentation. You can also use the keyboard instead of the mouse.

Help

Questions can be asked on GitHub Discussions. Identified issues can be raised as GitHub Issues.

Tests

See the test suite.

Contributing

See CONTRIBUTING.

Features

• Easily installed from PyPI. No additional install is required - you just need an available Oracle Database.

• Support for Python 3.6 and higher.

• Optional use of Oracle Client 11.2, 12, 18, 19 or 21 libraries for advanced Oracle Database functionality. Oracle's standard cross-version interoperability, allows easy upgrades and connectivity to different Oracle Database versions.

• Connects to Oracle Database 11.2, 12, 18, 19 or 21 on-premises or in the Cloud.

• SQL and PL/SQL Execution with significant optimizations including compressed fetch, pre-fetching, client and server result set caching, and statement caching with auto-tuning.

• Full use of Oracle Network Service infrastructure, including encrypted network traffic and security features.

• Extensive Oracle data type support, including large object support (CLOB and BLOB).

• Direct binding to SQL objects. One great use case is binding Python objects to Oracle Spatial SDO objects.

• JSON datatype support.

• SODA (Simple Oracle Document Access).

• Array operations for efficient INSERT, UPDATE and MERGE execution.

• Array row counts and batch error handling for array operations.

• Fetching of large result sets with easy tuning.

• REF CURSOR support.

• Support for scrollable cursors. Go back and forth through your query results.

• Fetch PL/SQL Implicit Results. Easily return query results from PL/SQL.

• Row Prefetching. Efficient use of the network.

• Client Result Caching. Improve performance of frequently executed look-up statements.

• Support for Advanced Queuing. Use database notifications to build micro-service applications.

• Continuous Query Notification (CQN). Get notified when data changes.

• Support for Edition Based Redefinition. Easily switch applications to use updated PL/SQL logic.

• Support for setting application context during the creation of a connection, making application metadata more accessible to the database, including in LOGON triggers.

• End-to-end monitoring and tracing.

• Transaction management and Two-phase Commits.

• Session Pooling, with tagging and session state fix-up callback.

• Database Resident Connection Pooling (DRCP).

• Privileged Connections.

• External Authentication.

• Token Authentication.

• Database startup and shutdown.

• Oracle Sharding connectivity.

• Oracle Database High Availability Features, such as FAN notifications, Application Continuity, and Transaction Guard support.

Some features above are only available in Thick mode. See the user documentation Oracle Database Features Supported by python-oracledb for more information.

Python DB API specification exclusions:

• The TIME data type is not supported by Oracle Database and is therefore not implemented.

• The method cursor.nextset() is not implemented because the specification assumes an implementation of cursors that does not fit well with Oracle Database's implementation of cursors and implicit results. See the method Cursor.getimplicitresults() for the Oracle replacement.

License

Python-oracledb license information is in LICENSE, THIRD_PARTY_LICENSES and NOTICE.