+
+ +
+

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

+ +
+ + + +
+

Installation

+ +

See python-oracledb Installation for detailed instructions.

+ +
+ +
+ +

Dependencies

+ +
    + +
  • + +

    Python versions 3.6 through 3.10.

    + +

    Pre-built packages on PyPI vary with + Python version support on each operating system.

    + +
    • + +
  • + +

    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.

    • + +

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

    • + +

  • Database Resident Connection Pooling (DRCP).

    • + +

  • Privileged Connections.

    • + +

  • External Authentication.

    • + +

  • Database startup and shutdown.

    • + +

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

+ +

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.

+ +
+ +
+