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.
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. Tracing python-oracledb
- 21. Character Sets and Globalization
- 22. Catching Exceptions
- 23. Troubleshooting Errors
- 24. Appendix A: Oracle Database Features Supported by python-oracledb
- 25. Appendix B: Differences between python-oracledb Thin and Thick Modes
- 25.1. Connection Handling Differences between Thin and Thick Modes
- 25.2. Connection Pooling Differences between Thin and Thick Modes
- 25.3. Supported Database Data Types in Thin and Thick Modes
- 25.4. Query Metadata in Thin and Thick Modes
- 25.5. Statement Caching in Thin and Thick Modes
- 25.6. Error Handling in Thin and Thick Modes
- 25.7. Globalization in Thin and Thick Modes
- 25.8. Tracing in Thin and Thick Modes
- 26. Appendix C: The python-oracledb and cx_Oracle Drivers
- 26.1. Differences between the python-oracledb and cx_Oracle Drivers
- 26.1.1. Mode differences from cx_Oracle
- 26.1.2. Oracle Client Library Loading Differences from cx_Oracle
- 26.1.3. Connection Differences from cx_Oracle
- 26.1.4. Pooling Differences from cx_Oracle
- 26.1.5. Cursor Object Differences from cx_Oracle
- 26.1.6. Advanced Queuing (AQ) Differences from cx_Oracle
- 26.1.7. Error Handling Differences from cx_Oracle
- 26.2. Upgrading from cx_Oracle 8.3 to python-oracledb
- 26.1. Differences between the python-oracledb and cx_Oracle Drivers
API Manual
- 1. API: python-oracledb Module
- 1.1. Oracledb Methods
- 1.2. Oracledb.__future__ Object
- 1.3. Oracledb Constants
- 1.3.1. General
- 1.3.2. Advanced Queuing: Delivery Modes
- 1.3.3. Advanced Queuing: Dequeue Modes
- 1.3.4. Advanced Queuing: Dequeue Navigation Modes
- 1.3.5. Advanced Queuing: Dequeue Visibility Modes
- 1.3.6. Advanced Queuing: Dequeue Wait Modes
- 1.3.7. Advanced Queuing: Enqueue Visibility Modes
- 1.3.8. Advanced Queuing: Message States
- 1.3.9. Advanced Queuing: Other
- 1.3.10. Connection Authorization Modes
- 1.3.11. Database Shutdown Modes
- 1.3.12. Event Types
- 1.3.13. Operation Codes
- 1.3.14. Connection Pool Get Modes
- 1.3.15. Connection Pool Purity Constants
- 1.3.16. Subscription Grouping Classes
- 1.3.17. Subscription Grouping Types
- 1.3.18. Subscription Namespaces
- 1.3.19. Subscription Protocols
- 1.3.20. Subscription Quality of Service
- 1.3.21. DB API Types
- 1.3.22. Database Types
- 1.3.23. Database Type Synonyms
- 1.3.24. Other Types
- 1.3.25. Two-Phase Commit (TPC) Constants
- 1.4. Oracledb Exceptions
- 1.5. 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.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.encoding
Connection.external_name
Connection.handle
Connection.inputtypehandler
Connection.instance_name
Connection.internal_name
Connection.ltxid
Connection.maxBytesPerCharacter
Connection.max_open_cursors
Connection.module
Connection.nencoding
Connection.outputtypehandler
Connection.proxy_user
Connection.service_name
Connection.stmtcachesize
Connection.tag
Connection.thin
Connection.tnsentry
Connection.transaction_in_progress
Connection.username
Connection.version
- 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.port
ConnectParams.protocol
ConnectParams.proxy_user
ConnectParams.purity
ConnectParams.retry_count
ConnectParams.retry_delay
ConnectParams.server_type
ConnectParams.service_name
ConnectParams.shardingkey
ConnectParams.sid
ConnectParams.ssl_context
ConnectParams.ssl_server_cert_dn
ConnectParams.ssl_server_dn_match
ConnectParams.stmtcachesize
ConnectParams.supershardingkey
ConnectParams.tag
ConnectParams.tcp_connect_timeout
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.tnsentry
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.session_callback
PoolParams.soda_metadata_cache
PoolParams.timeout
PoolParams.wait_timeout
- 7. API: Cursor Objects
- 7.1. Cursor Methods
Cursor.__enter__()
Cursor.__exit__()
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.__iter__()
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.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. Deprecations