The python-oracledb 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.

Synchronous and concurrent asyncio coding styles are supported.

Getting Started

Installation

See python-oracledb Installation for detailed instructions.

Dependencies

  • Python versions 3.7 through 3.12.

    Pre-built packages on PyPI are available for Python 3.7 and 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 23. See Enabling python-oracledb Thick mode.

  • Oracle Database

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

    Thick mode: Connects to Oracle Database 9.2, 10, 11.2, 12, 18, 21 and 23, 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 19 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.7 and higher. (Python-oracledb 1 can be used with Python 3.6).

  • Support for synchronous and concurrent asyncio coding styles.

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

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

  • 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 data type 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 in-band and FAN notifications, Application Continuity, Transparent Application Continuity and Transaction Guard support.

Not all features are available in both Thin and Thick modes. 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.