Welcome to python-oracledb’s documentation!
Python-oracledb is the new name for the Python cx_Oracle driver. The python-oracledb driver is an open source module that enables Python programs to access Oracle Database. It conforms to the Python Database API v2.0 Specification with a considerable number of additions and a couple of exclusions. Synchronous and concurrent coding styles are supported.
This module is currently tested with Python 3.7, 3.8, 3.9, 3.10, 3.11 and 3.12 against Oracle Database 23c, 21c, 19c, 18c, 12c, and 11gR2.
python-oracledb is distributed under an open-source license. Changes in python-oracledb releases can be found in the release notes.
You can use assistive technology products, such as screen readers, while you work with the python-oracledb documentation. You can also use the keyboard instead of the mouse.
User Guide
- 1. Introduction to the Python Driver for Oracle Database
- 2. Installing python-oracledb
- 2.1. Quick Start python-oracledb Installation
- 2.2. Supported Oracle Database Versions
- 2.3. Installation Requirements
- 2.4. Installing python-oracledb on Linux
- 2.5. Installing python-oracledb on Windows
- 2.6. Installing python-oracledb on macOS
- 2.7. Installing python-oracledb without Internet Access
- 2.8. Installing python-oracledb without the Cryptography Package
- 2.9. Installing from Source Code
- 3. Initializing python-oracledb
- 4. Connecting to Oracle Database
- 4.1. Standalone Connections
- 4.2. Connection Strings
- 4.3. Using the ConnectParams Builder Class
- 4.4. Connection Pooling
- 4.5. Database Resident Connection Pooling (DRCP)
- 4.6. Connecting Using Proxy Authentication
- 4.7. Connecting Using External Authentication
- 4.8. Token-Based Authentication
- 4.9. Privileged Connections
- 4.10. Securely Encrypting Network Traffic to Oracle Database
- 4.11. Resetting Passwords
- 4.12. Connecting to Oracle Cloud Autonomous Databases
- 4.13. Connecting using Multiple Wallets
- 4.14. Connecting to Sharded Databases
- 5. Executing SQL
- 5.1. SQL Queries
- 5.1.1. Fetch Methods
- 5.1.2. Closing Cursors
- 5.1.3. Query Column Metadata
- 5.1.4. Fetch Data Types
- 5.1.5. Changing Fetched Data
- 5.1.6. Fetched Number Precision
- 5.1.7. Scrollable Cursors
- 5.1.8. Fetching Oracle Database Objects and Collections
- 5.1.9. Limiting Rows
- 5.1.10. Client Result Cache
- 5.1.11. Fetching Raw Data
- 5.1.12. Querying Corrupt Data
- 5.2. INSERT and UPDATE Statements
- 5.1. SQL Queries
- 6. Executing PL/SQL
- 7. Using Bind Variables
- 7.1. Binding by Name or Position
- 7.2. Bind Direction
- 7.3. Binding Null Values
- 7.4. Binding ROWID Values
- 7.5. Binding UROWID Values
- 7.6. DML RETURNING Bind Variables
- 7.7. LOB Bind Variables
- 7.8. REF CURSOR Bind Variables
- 7.9. Binding PL/SQL Collections
- 7.10. Binding PL/SQL Records
- 7.11. Binding Spatial Data Types
- 7.12. Changing Bind Data Types using an Input Type Handler
- 7.13. Binding Multiple Values to a SQL WHERE IN Clause
- 7.14. Binding Column and Table Names
- 8. Executing Batch Statements and Bulk Loading
- 9. Managing Transactions
- 10. Tuning python-oracledb
- 11. Using CLOB and BLOB Data
- 12. Using JSON Data
- 13. Using XMLTYPE Data
- 14. Working with Simple Oracle Document Access (SODA)
- 15. Using Oracle Advanced Queuing (AQ)
- 16. Working with Continuous Query Notification (CQN)
- 17. Using Two-Phase Commits (TPC)
- 18. Starting and Stopping Oracle Database
- 19. Using High Availability with python-oracledb
- 20. Character Sets and Globalization
- 21. Concurrent Programming with asyncio
- 22. Catching Exceptions
- 23. Tracing python-oracledb
- 24. Troubleshooting Errors
- 25. Appendix A: Oracle Database Features Supported by python-oracledb
- 26. Appendix B: Differences between python-oracledb Thin and Thick Modes
- 26.1. Connection Handling Differences between Thin and Thick Modes
- 26.2. Connection Pooling Differences between Thin and Thick Modes
- 26.3. Supported Database Data Types in Thin and Thick Modes
- 26.4. Query Metadata in Thin and Thick Modes
- 26.5. Statement Caching in Thin and Thick Modes
- 26.6. Error Handling in Thin and Thick Modes
- 26.7. Globalization in Thin and Thick Modes
- 26.8. Tracing in Thin and Thick Modes
- 27. Appendix C: The python-oracledb and cx_Oracle Drivers
- 27.1. Differences between the python-oracledb and cx_Oracle Drivers
- 27.1.1. Mode differences from cx_Oracle
- 27.1.2. Oracle Client Library Loading Differences from cx_Oracle
- 27.1.3. Connection Differences from cx_Oracle
- 27.1.4. Pooling Differences from cx_Oracle
- 27.1.5. Cursor Object Differences from cx_Oracle
- 27.1.6. Advanced Queuing (AQ) Differences from cx_Oracle
- 27.1.7. Error Handling Differences from cx_Oracle
- 27.2. Upgrading from cx_Oracle 8.3 to python-oracledb
- 27.1. Differences between the python-oracledb and cx_Oracle Drivers
API Manual
- 1. API: python-oracledb Module
- 1.1. Oracledb Methods
- 1.2. Oracledb JsonId Class
- 1.3. Oracledb __future__ Object
- 1.4. Oracledb Constants
- 1.4.1. General
- 1.4.2. Advanced Queuing: Delivery Modes
- 1.4.3. Advanced Queuing: Dequeue Modes
- 1.4.4. Advanced Queuing: Dequeue Navigation Modes
- 1.4.5. Advanced Queuing: Dequeue Visibility Modes
- 1.4.6. Advanced Queuing: Dequeue Wait Modes
- 1.4.7. Advanced Queuing: Enqueue Visibility Modes
- 1.4.8. Advanced Queuing: Message States
- 1.4.9. Advanced Queuing: Other
- 1.4.10. Connection Authorization Modes
- 1.4.11. Database Shutdown Modes
- 1.4.12. Event Types
- 1.4.13. Operation Codes
- 1.4.14. Connection Pool Get Modes
- 1.4.15. Connection Pool Purity Constants
- 1.4.16. Subscription Grouping Classes
- 1.4.17. Subscription Grouping Types
- 1.4.18. Subscription Namespaces
- 1.4.19. Subscription Protocols
- 1.4.20. Subscription Quality of Service
- 1.4.21. DB API Types
- 1.4.22. Database Types
- 1.4.23. Database Type Synonyms
- 1.4.24. Other Types
- 1.4.25. Two-Phase Commit (TPC) Constants
- 1.5. Oracledb Exceptions
- 1.6. Oracledb _Error Objects
- 2. API: Defaults Object
- 3. API: Connection Objects
- 3.1. Connection Methods
Connection.__enter__()Connection.__exit__()Connection.begin()Connection.cancel()Connection.changepassword()Connection.close()Connection.commit()Connection.createlob()Connection.cursor()Connection.decode_oson()Connection.encode_oson()Connection.getSodaDatabase()Connection.gettype()Connection.is_healthy()Connection.msgproperties()Connection.ping()Connection.prepare()Connection.queue()Connection.rollback()Connection.shutdown()Connection.startup()Connection.subscribe()Connection.tpc_begin()Connection.tpc_commit()Connection.tpc_end()Connection.tpc_forget()Connection.tpc_prepare()Connection.tpc_recover()Connection.tpc_rollback()Connection.unsubscribe()Connection.xid()
- 3.2. Connection Attributes
Connection.actionConnection.autocommitConnection.call_timeoutConnection.client_identifierConnection.clientinfoConnection.current_schemaConnection.db_domainConnection.db_nameConnection.dbopConnection.dsnConnection.econtext_idConnection.editionConnection.external_nameConnection.handleConnection.inputtypehandlerConnection.instance_nameConnection.internal_nameConnection.ltxidConnection.max_open_cursorsConnection.moduleConnection.outputtypehandlerConnection.proxy_userConnection.sduConnection.service_nameConnection.stmtcachesizeConnection.tagConnection.thinConnection.transaction_in_progressConnection.usernameConnection.versionConnection.warning
- 3.1. Connection Methods
- 4. API: ConnectParams Objects
- 4.1. ConnectParams Methods
- 4.2. ConnectParams Attributes
ConnectParams.appcontextConnectParams.cclassConnectParams.config_dirConnectParams.connection_id_prefixConnectParams.debug_jdwpConnectParams.disable_oobConnectParams.editionConnectParams.eventsConnectParams.expire_timeConnectParams.externalauthConnectParams.hostConnectParams.https_proxyConnectParams.https_proxy_portConnectParams.matchanytagConnectParams.modeConnectParams.pool_boundaryConnectParams.portConnectParams.protocolConnectParams.proxy_userConnectParams.purityConnectParams.retry_countConnectParams.retry_delayConnectParams.sduConnectParams.server_typeConnectParams.service_nameConnectParams.shardingkeyConnectParams.sidConnectParams.ssl_contextConnectParams.ssl_server_cert_dnConnectParams.ssl_server_dn_matchConnectParams.stmtcachesizeConnectParams.supershardingkeyConnectParams.tagConnectParams.tcp_connect_timeoutConnectParams.use_tcp_fast_openConnectParams.userConnectParams.wallet_location
- 5. API: ConnectionPool Objects
- 5.1. ConnectionPool Methods
- 5.2. ConnectionPool Attributes
ConnectionPool.busyConnectionPool.dsnConnectionPool.getmodeConnectionPool.homogeneousConnectionPool.incrementConnectionPool.maxConnectionPool.max_lifetime_sessionConnectionPool.max_sessions_per_shardConnectionPool.minConnectionPool.nameConnectionPool.openedConnectionPool.ping_intervalConnectionPool.soda_metadata_cacheConnectionPool.stmtcachesizeConnectionPool.thinConnectionPool.timeoutConnectionPool.usernameConnectionPool.wait_timeout
- 6. API: PoolParams Objects
- 6.1. PoolParams Methods
- 6.2. PoolParams Attributes
PoolParams.connectiontypePoolParams.getmodePoolParams.homogeneousPoolParams.incrementPoolParams.minPoolParams.maxPoolParams.max_lifetime_sessionPoolParams.max_sessions_per_shardPoolParams.ping_intervalPoolParams.session_callbackPoolParams.soda_metadata_cachePoolParams.timeoutPoolParams.wait_timeout
- 7. API: Cursor Objects
- 7.1. Cursor Methods
Cursor.__enter__()Cursor.__exit__()Cursor.__iter__()Cursor.arrayvar()Cursor.bindnames()Cursor.callfunc()Cursor.callproc()Cursor.close()Cursor.execute()Cursor.executemany()Cursor.fetchall()Cursor.fetchmany()Cursor.fetchone()Cursor.getarraydmlrowcounts()Cursor.getbatcherrors()Cursor.getimplicitresults()Cursor.parse()Cursor.prepare()Cursor.scroll()Cursor.setinputsizes()Cursor.setoutputsize()Cursor.var()
- 7.2. Cursor Attributes
- 7.1. Cursor Methods
- 8. API: FetchInfo Objects
- 9. API: Variable Objects
- 10. API: Subscription Objects
- 10.1. Subscription Methods
- 10.2. Subscription Attributes
Subscription.callbackSubscription.connectionSubscription.idSubscription.ip_addressSubscription.nameSubscription.namespaceSubscription.operationsSubscription.portSubscription.protocolSubscription.qosSubscription.timeout- 10.2.1. Message Objects
- 10.2.2. MessageTable Objects
- 10.2.3. MessageRow Objects
- 10.2.4. MessageQuery Objects
- 11. API: LOB Objects
- 12. API: DbObjectType Objects
- 13. API: Advanced Queuing (AQ)
- 13.1. Queue Objects
- 13.2. Dequeue Options
- 13.3. Enqueue Options
- 13.4. Message Properties
MessageProperties.attemptsMessageProperties.correlationMessageProperties.delayMessageProperties.deliverymodeMessageProperties.enqtimeMessageProperties.exceptionqMessageProperties.expirationMessageProperties.msgidMessageProperties.payloadMessageProperties.priorityMessageProperties.stateMessageProperties.recipients
- 14. API: SODA
- 15. API: AsyncConnection Objects
- 15.1. AsyncConnection Methods
AsyncConnection.__aenter__()AsyncConnection.__aexit__()AsyncConnection.callfunc()AsyncConnection.callproc()AsyncConnection.cancel()AsyncConnection.changepassword()AsyncConnection.close()AsyncConnection.commit()AsyncConnection.createlob()AsyncConnection.cursor()AsyncConnection.decode_oson()AsyncConnection.encode_oson()AsyncConnection.execute()AsyncConnection.executemany()AsyncConnection.fetchall()AsyncConnection.fetchmany()AsyncConnection.fetchone()AsyncConnection.gettype()AsyncConnection.is_healthy()AsyncConnection.ping()AsyncConnection.rollback()
- 15.2. AsyncConnection Attributes
AsyncConnection.actionAsyncConnection.autocommitAsyncConnection.call_timeoutAsyncConnection.client_identifierAsyncConnection.clientinfoAsyncConnection.current_schemaAsyncConnection.db_domainAsyncConnection.db_nameAsyncConnection.dbopAsyncConnection.dsnAsyncConnection.econtext_idAsyncConnection.editionAsyncConnection.external_nameAsyncConnection.inputtypehandlerAsyncConnection.instance_nameAsyncConnection.internal_nameAsyncConnection.ltxidAsyncConnection.max_open_cursorsAsyncConnection.moduleAsyncConnection.outputtypehandlerAsyncConnection.sduAsyncConnection.service_nameAsyncConnection.stmtcachesizeAsyncConnection.thinAsyncConnection.transaction_in_progressAsyncConnection.usernameAsyncConnection.version
- 15.1. AsyncConnection Methods
- 16. API: AsyncConnectionPool Objects
- 16.1. AsyncConnectionPool Methods
- 16.2. AsyncConnectionPool Attributes
AsyncConnectionPool.busyAsyncConnectionPool.dsnAsyncConnectionPool.getmodeAsyncConnectionPool.homogeneousAsyncConnectionPool.incrementAsyncConnectionPool.maxAsyncConnectionPool.max_lifetime_sessionAsyncConnectionPool.max_sessions_per_shardAsyncConnectionPool.minAsyncConnectionPool.nameAsyncConnectionPool.openedAsyncConnectionPool.ping_intervalAsyncConnectionPool.soda_metadata_cacheAsyncConnectionPool.stmtcachesizeAsyncConnectionPool.thinAsyncConnectionPool.timeoutAsyncConnectionPool.usernameAsyncConnectionPool.wait_timeout
- 17. API: AsyncCursor Objects
- 17.1. AsyncCursor Methods
AsyncCursor.__aiter__()AsyncCursor.__enter__()AsyncCursor.__exit__()AsyncCursor.arrayvar()AsyncCursor.bindnames()AsyncCursor.callfunc()AsyncCursor.callproc()AsyncCursor.close()AsyncCursor.execute()AsyncCursor.executemany()AsyncCursor.fetchall()AsyncCursor.fetchmany()AsyncCursor.fetchone()AsyncCursor.getarraydmlrowcounts()AsyncCursor.getbatcherrors()AsyncCursor.getimplicitresults()AsyncCursor.parse()AsyncCursor.prepare()AsyncCursor.setinputsizes()AsyncCursor.setoutputsize()AsyncCursor.var()
- 17.2. AsyncCursor Attributes
- 17.1. AsyncCursor Methods
- 18. API: AsyncLOB Objects
- 19. Deprecated and Desupported Features