GeezerVison

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

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

• Quick Start python-oracledb Installation: 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.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 19 through 26. See Enabling python-oracledb Thick mode.

• Oracle Database

  Thin mode: Python-oracledb Thin mode connects to Oracle Database 12, 18, 19, 21 and 26.

  Thick mode: Python-oracledb Thick mode connects to Oracle Database 11.2, 12, 18, 21 and 26, 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 11.2, 12, 18, 19, 21 and 26 on-premises or in the Cloud.

• Optional use of Oracle Client 19, 21 or 26 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 AI Database 26ai 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.

• Support for Centralized Configuration Providers.

• Oracle Database startup and shutdown.

• Oracle Globally Distributed Database (formerly called Oracle Sharding) connectivity.

• Support for Oracle AI Database 26ai Deep Data Security.

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