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.

Connections between python-oracledb and Oracle Database are used for executing SQL and PL/SQL, for calling SODA NoSQL-style APIs, for receiving database notifications and messages, and for starting and stopping the database.

Synchronous and concurrent asyncio coding styles are supported. Database operations can optionally be pipelined.

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

Installation

See python-oracledb Installation for detailed instructions.

Dependencies

  • Python versions 3.8 through 3.13.

    Pre-built packages are available on PyPI and other repositories.

    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: An optional mode enabled by loading Oracle Client libraries at runtime. This adds some advanced Oracle Database functionality. You can install Oracle Client 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 or other repositories. No additional install is required - you just need an available Oracle Database.

  • Support for Python 3.8 and higher. (Older versions of python-oracledb can be used with Python 3.6 or 3.7).

  • Support for synchronous and concurrent asyncio coding styles.

  • Connects to Oracle Database 9.2, 10, 11.2, 12, 18, 19, 21 and 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 VECTOR, JSON and large object support (CLOB and BLOB).

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

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

  • Scrollable cursors. Go back and forth through your query results.

  • Oracle Database 23ai statement pipelining. Keep the database busy processing statements.

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

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

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

  • 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). Optimize Oracle Database resource usage for distributed applications.

  • Implicit Connection Pooling.

  • Privileged Connections.

  • External Authentication.

  • Token Authentication.

  • Oracle Database startup and shutdown.

  • Oracle Globally Distributed Database (formerly called 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.