Welcome to python-oracledb’s documentation
The python-oracledb driver is an open source Python module that enables access to Oracle Database. Python-oracledb is the new name for the cx_Oracle driver.
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
- 3.1. Enabling python-oracledb Thick mode
- 3.2. Explicitly Enabling python-oracledb Thin Mode
- 3.3. Optional Oracle Configuration Files
- 3.4. Oracle Environment Variables for python-oracledb Thick Mode
- 3.5. Other python-oracledb Thick Mode Initialization
- 3.6. Migrating from python-oracledb Thick Mode to python-oracledb Thin Mode
- 4. Connecting to Oracle Database
- 4.1. Standalone Connections
- 4.2. Oracle Net Services Connection Strings
- 4.3. Using the ConnectParams Builder Class
- 4.4. Connection Hook Functions
- 4.5. LDAP Directory Naming
- 4.6. Connection Metadata and Application Contexts
- 4.7. Connection Pooling
- 4.7.1. Creating a Connection Pool
- 4.7.2. Using the Connection Pool Cache
- 4.7.3. Connection Pool Sizing
- 4.7.4. Pool Connection Health
- 4.7.5. Connection Pool Reconfiguration
- 4.7.6. Session Callbacks for Setting Pooled Connection State
- 4.7.7. Heterogeneous and Homogeneous Connection Pools
- 4.7.8. Using the PoolParams Builder Class
- 4.8. Database Resident Connection Pooling (DRCP)
- 4.9. Implicit Connection Pooling
- 4.10. Connecting Using Proxy Authentication
- 4.11. Connecting Using External Authentication
- 4.12. Token-Based Authentication
- 4.13. Privileged Connections
- 4.14. Securely Encrypting Network Traffic to Oracle Database
- 4.15. Resetting Passwords
- 4.16. Connecting to Oracle Cloud Autonomous Databases
- 4.17. Connecting Through a Firewall via a Proxy
- 4.18. Connecting using Multiple Wallets
- 4.19. Connecting to Oracle Globally Distributed Database
- 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. Fetching Data in Parallel
- 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. Reducing the SQL Version Count
- 7.13. Changing Bind Data Types using an Input Type Handler
- 7.14. Binding Multiple Values to a SQL WHERE IN Clause
- 7.15. 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
Binary()
clientversion()
connect()
connect_async()
ConnectParams()
create_pipeline()
create_pool()
create_pool_async()
Cursor()
Date()
DateFromTicks()
enable_thin_mode()
get_pool()
init_oracle_client()
is_thin_mode()
makedsn()
PoolParams()
register_protocol()
Time()
TimeFromTicks()
Timestamp()
TimestampFromTicks()
- 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
- 1.1. Oracledb Methods
- 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_identifier_length
Connection.max_open_cursors
Connection.module
Connection.outputtypehandler
Connection.proxy_user
Connection.sdu
Connection.serial_num
Connection.service_name
Connection.session_id
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.driver_name
ConnectParams.edition
ConnectParams.events
ConnectParams.expire_time
ConnectParams.externalauth
ConnectParams.host
ConnectParams.https_proxy
ConnectParams.https_proxy_port
ConnectParams.machine
ConnectParams.matchanytag
ConnectParams.mode
ConnectParams.osuser
ConnectParams.pool_boundary
ConnectParams.port
ConnectParams.program
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.terminal
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_identifier_length
AsyncConnection.max_open_cursors
AsyncConnection.module
AsyncConnection.outputtypehandler
AsyncConnection.sdu
AsyncConnection.serial_num
AsyncConnection.service_name
AsyncConnection.session_id
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