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.
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.
See python-oracledb Installation for detailed instructions.
Python versions 3.6 through 3.12.
Pre-built packages on PyPI are available for Windows Python 3.7 or later, for macOS Python 3.7 or later, and for Linux Python 3.6 or 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.
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.
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.
See the test suite.
Easily installed from PyPI. No additional install is required - you just need an available Oracle Database.
Support for Python 3.6 and higher.
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).
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.
Some features above are only available in Thick mode. 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.
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.