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.8, 3.9, 3.10, 3.11, 3.12 and 3.13 against Oracle Database 23ai, 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. LDAP Directory Naming
- 4.5. Connection Hook Functions
- 4.6. Connection Pooling
- 4.7. Database Resident Connection Pooling (DRCP)
- 4.8. Implicit Connection Pooling
- 4.9. Connecting Using Proxy Authentication
- 4.10. Connecting Using External Authentication
- 4.11. Token-Based Authentication
- 4.12. Privileged Connections
- 4.13. Securely Encrypting Network Traffic to Oracle Database
- 4.14. Resetting Passwords
- 4.15. Connecting to Oracle Cloud Autonomous Databases
- 4.16. Connecting using Multiple Wallets
- 4.17. 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. Using VECTOR Data
- 15. Working with Simple Oracle Document Access (SODA)
- 16. Using Oracle Advanced Queuing (AQ)
- 17. Working with Continuous Query Notification (CQN)
- 18. Using Two-Phase Commits (TPC)
- 19. Starting and Stopping Oracle Database
- 20. Using High Availability with python-oracledb
- 21. Character Sets and Globalization
- 22. Concurrent Programming with asyncio and Pipelining
- 23. Catching Exceptions
- 24. Tracing python-oracledb
- 25. Troubleshooting Errors
- 26. Appendix A: Oracle Database Features Supported by python-oracledb
- 27. Appendix B: Differences between python-oracledb Thin and Thick Modes
- 27.1. Connection Handling Differences between Thin and Thick Modes
- 27.2. Connection Pooling Differences between Thin and Thick Modes
- 27.3. Supported Database Data Types in Thin and Thick Modes
- 27.4. Query Metadata in Thin and Thick Modes
- 27.5. Implicit Results in Thin and Thick Modes
- 27.6. Statement Caching in Thin and Thick Modes
- 27.7. Error Handling in Thin and Thick Modes
- 27.8. Globalization in Thin and Thick Modes
- 27.9. Tracing in Thin and Thick Modes
- 28. Appendix C: The python-oracledb and cx_Oracle Drivers
- 28.1. Differences between the python-oracledb and cx_Oracle Drivers
- 28.1.1. Mode differences from cx_Oracle
- 28.1.2. Oracle Client Library Loading Differences from cx_Oracle
- 28.1.3. Connection Differences from cx_Oracle
- 28.1.4. Pooling Differences from cx_Oracle
- 28.1.5. Cursor Object Differences from cx_Oracle
- 28.1.6. Fetching IS JSON Column Differences from cx_Oracle
- 28.1.7. Advanced Queuing (AQ) Differences from cx_Oracle
- 28.1.8. Error Handling Differences from cx_Oracle
- 28.2. Upgrading from cx_Oracle 8.3 to python-oracledb
- 28.1. Differences between the python-oracledb and cx_Oracle Drivers
API Manual
- 1. API: python-oracledb Module
- 1.1. Oracledb Methods
- 1.2. Oracledb IntervalYM Class
- 1.3. Oracledb JsonId Class
- 1.4. Oracledb __future__ Object
- 1.5. Oracledb Constants
- 1.5.1. General
- 1.5.2. Advanced Queuing: Delivery Modes
- 1.5.3. Advanced Queuing: Dequeue Modes
- 1.5.4. Advanced Queuing: Dequeue Navigation Modes
- 1.5.5. Advanced Queuing: Dequeue Visibility Modes
- 1.5.6. Advanced Queuing: Dequeue Wait Modes
- 1.5.7. Advanced Queuing: Enqueue Visibility Modes
- 1.5.8. Advanced Queuing: Message States
- 1.5.9. Advanced Queuing: Other
- 1.5.10. Connection Authorization Modes
- 1.5.11. Pipeline Operation Types
- 1.5.12. Database Shutdown Modes
- 1.5.13. Event Types
- 1.5.14. Operation Codes
- 1.5.15. Connection Pool Get Modes
- 1.5.16. Connection Pool Purity Constants
- 1.5.17. Subscription Grouping Classes
- 1.5.18. Subscription Grouping Types
- 1.5.19. Subscription Namespaces
- 1.5.20. Subscription Protocols
- 1.5.21. Subscription Quality of Service
- 1.5.22. DB API Types
- 1.5.23. Database Types
- 1.5.24. Database Type Synonyms
- 1.5.25. Other Types
- 1.5.26. Two-Phase Commit (TPC) Constants
- 1.5.27. Vector Format Constants
- 1.6. Oracledb Exceptions
- 1.7. 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.action
Connection.autocommit
Connection.call_timeout
Connection.client_identifier
Connection.clientinfo
Connection.current_schema
Connection.db_domain
Connection.db_name
Connection.dbop
Connection.dsn
Connection.econtext_id
Connection.edition
Connection.external_name
Connection.handle
Connection.inputtypehandler
Connection.instance_name
Connection.internal_name
Connection.ltxid
Connection.max_open_cursors
Connection.module
Connection.outputtypehandler
Connection.proxy_user
Connection.sdu
Connection.service_name
Connection.stmtcachesize
Connection.tag
Connection.thin
Connection.transaction_in_progress
Connection.username
Connection.version
Connection.warning
- 3.1. Connection Methods
- 4. API: ConnectParams Objects
- 4.1. ConnectParams Methods
- 4.2. ConnectParams Attributes
ConnectParams.appcontext
ConnectParams.cclass
ConnectParams.config_dir
ConnectParams.connection_id_prefix
ConnectParams.debug_jdwp
ConnectParams.disable_oob
ConnectParams.edition
ConnectParams.events
ConnectParams.expire_time
ConnectParams.externalauth
ConnectParams.host
ConnectParams.https_proxy
ConnectParams.https_proxy_port
ConnectParams.matchanytag
ConnectParams.mode
ConnectParams.pool_boundary
ConnectParams.port
ConnectParams.protocol
ConnectParams.proxy_user
ConnectParams.purity
ConnectParams.retry_count
ConnectParams.retry_delay
ConnectParams.sdu
ConnectParams.server_type
ConnectParams.service_name
ConnectParams.shardingkey
ConnectParams.sid
ConnectParams.ssl_context
ConnectParams.ssl_server_cert_dn
ConnectParams.ssl_server_dn_match
ConnectParams.ssl_version
ConnectParams.stmtcachesize
ConnectParams.supershardingkey
ConnectParams.tag
ConnectParams.tcp_connect_timeout
ConnectParams.use_tcp_fast_open
ConnectParams.user
ConnectParams.wallet_location
- 5. API: ConnectionPool Objects
- 5.1. ConnectionPool Methods
- 5.2. ConnectionPool Attributes
ConnectionPool.busy
ConnectionPool.dsn
ConnectionPool.getmode
ConnectionPool.homogeneous
ConnectionPool.increment
ConnectionPool.max
ConnectionPool.max_lifetime_session
ConnectionPool.max_sessions_per_shard
ConnectionPool.min
ConnectionPool.name
ConnectionPool.opened
ConnectionPool.ping_interval
ConnectionPool.soda_metadata_cache
ConnectionPool.stmtcachesize
ConnectionPool.thin
ConnectionPool.timeout
ConnectionPool.username
ConnectionPool.wait_timeout
- 6. API: PoolParams Objects
- 6.1. PoolParams Methods
- 6.2. PoolParams Attributes
PoolParams.connectiontype
PoolParams.getmode
PoolParams.homogeneous
PoolParams.increment
PoolParams.min
PoolParams.max
PoolParams.max_lifetime_session
PoolParams.max_sessions_per_shard
PoolParams.ping_interval
PoolParams.ping_timeout
PoolParams.session_callback
PoolParams.soda_metadata_cache
PoolParams.timeout
PoolParams.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
- 8.1. FetchInfo Attributes
FetchInfo.annotations
FetchInfo.display_size
FetchInfo.domain_name
FetchInfo.domain_schema
FetchInfo.internal_size
FetchInfo.is_json
FetchInfo.is_oson
FetchInfo.name
FetchInfo.null_ok
FetchInfo.precision
FetchInfo.scale
FetchInfo.type
FetchInfo.type_code
FetchInfo.vector_dimensions
FetchInfo.vector_format
- 8.1. FetchInfo Attributes
- 9. API: Variable Objects
- 10. API: Subscription Objects
- 10.1. Subscription Methods
- 10.2. Subscription Attributes
Subscription.callback
Subscription.connection
Subscription.id
Subscription.ip_address
Subscription.name
Subscription.namespace
Subscription.operations
Subscription.port
Subscription.protocol
Subscription.qos
Subscription.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.attempts
MessageProperties.correlation
MessageProperties.delay
MessageProperties.deliverymode
MessageProperties.enqtime
MessageProperties.exceptionq
MessageProperties.expiration
MessageProperties.msgid
MessageProperties.payload
MessageProperties.priority
MessageProperties.state
MessageProperties.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()
AsyncConnection.run_pipeline()
AsyncConnection.tpc_begin()
AsyncConnection.tpc_commit()
AsyncConnection.tpc_end()
AsyncConnection.tpc_forget()
AsyncConnection.tpc_prepare()
AsyncConnection.tpc_recover()
AsyncConnection.tpc_rollback()
- 15.2. AsyncConnection Attributes
AsyncConnection.action
AsyncConnection.autocommit
AsyncConnection.call_timeout
AsyncConnection.client_identifier
AsyncConnection.clientinfo
AsyncConnection.current_schema
AsyncConnection.db_domain
AsyncConnection.db_name
AsyncConnection.dbop
AsyncConnection.dsn
AsyncConnection.econtext_id
AsyncConnection.edition
AsyncConnection.external_name
AsyncConnection.inputtypehandler
AsyncConnection.instance_name
AsyncConnection.internal_name
AsyncConnection.ltxid
AsyncConnection.max_open_cursors
AsyncConnection.module
AsyncConnection.outputtypehandler
AsyncConnection.sdu
AsyncConnection.service_name
AsyncConnection.stmtcachesize
AsyncConnection.thin
AsyncConnection.transaction_in_progress
AsyncConnection.username
AsyncConnection.version
- 15.1. AsyncConnection Methods
- 16. API: AsyncConnectionPool Objects
- 16.1. AsyncConnectionPool Methods
- 16.2. AsyncConnectionPool Attributes
AsyncConnectionPool.busy
AsyncConnectionPool.dsn
AsyncConnectionPool.getmode
AsyncConnectionPool.homogeneous
AsyncConnectionPool.increment
AsyncConnectionPool.max
AsyncConnectionPool.max_lifetime_session
AsyncConnectionPool.max_sessions_per_shard
AsyncConnectionPool.min
AsyncConnectionPool.name
AsyncConnectionPool.opened
AsyncConnectionPool.ping_interval
AsyncConnectionPool.soda_metadata_cache
AsyncConnectionPool.stmtcachesize
AsyncConnectionPool.thin
AsyncConnectionPool.timeout
AsyncConnectionPool.username
AsyncConnectionPool.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. API: Pipeline Objects
- 20. Deprecated and Desupported Features