+
+ +
+

The python-oracledb driver for Oracle Database

+ +

+ + The python-oracledb driver is the widely used, + open-source Python programming + language extension module allowing Python programs to connect + directly to Oracle + Database with no extra libraries needed. The module is built with + Cython for safety and speed. It is lightweight and + high-performance. It is stable, well tested, and has comprehensive + documentation. The module is maintained by Oracle. + +

+ +

+ +

+ +

+ + 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. It is used by many Python frameworks, SQL generators, ORMs, + and libraries. + +

+ +

+ + Python-oracledb has a rich feature set which is easy to use. It gives + you control over SQL and PL/SQL statement execution; for working with + data frames; for fast data ingestion; for calling NoSQL-style + document APIs; for message queueing; for receiving database + notifications; and for starting and stopping the database. It also + has high availability and security features. Synchronous and + concurrent asyncio coding styles are supported. Database operations can + optionally be pipelined. + +

+ +

+ + Python-oracledb is the successor to the now obsolete cx_Oracle + driver. + +

+ +
+ +
+

Getting Started

+ + + +
+ +
+

Installation

+ +

See python-oracledb Installation for detailed instructions.

+ +
+ +
+ +

Dependencies

+ +
    + +
  • + +

    Python versions 3.9 through 3.14.

    + +

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

    + +

    Source code is also available.

    + +

    Previous versions of python-oracledb supported older Python versions.

    + +
  • + +
  • + +

    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 python-oracledb 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: Python-oracledb Thin mode connects + to Oracle Database 12, 18, 19, 21 and 23.

    + +

    Thick mode: Python-oracledb 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.

+ +
+ +
+

Resources

+ +

Some resources that cover python-oracledb topics are:

+ +

+ Blogs: + medium.com/@cjones-oracle, + medium.com/@sharad-chandran, + medium.com/@vignan.v, + medium.com/@veronica.dumitriu +

+ +

Videos: www.youtube.com/user/OracleAppDev

+ +
+
+

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.9 and higher. (Older versions of + python-oracledb can be used with Python versions back to Python 3.6).

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

  • + +
  • Support for fetching and inserting data frames for efficient use + with Python DataFrame libraries and formats such as PyArrow, NumPy, + Pandas, Polars, PyTorch, and Apache Parquet.

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

  • + +
  • Oracle Database Direct Path Loads.

  • + +
  • 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 features, including Sessionless + Transactions 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.

  • + +
  • Centralized Configuration Provider support.

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

+ +
+ +
+