Welcome to python-oracledb’s documentation
The python-oracledb driver is an open source Python module that enables access to Oracle Database with no extra libraries needed. The module is built with Cython for safety and speed. It is lightweight and high-performance. It is stable, well tested, and has comprehensive documentation. The module is maintained by Oracle.
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
- 2.10. Using python-oracledb Containers
- 2.11. Installing Centralized Configuration Provider Modules for python-oracledb
- 2.12. Installing Cloud Native Authentication Modules for python-oracledb
- 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
- 3.5. Other python-oracledb Thick Mode Initialization
- 3.6. Migrating from python-oracledb Thick Mode to python-oracledb Thin Mode
- 3.7. Changing python-oracledb Default Settings
- 4. Connecting to Oracle Database
- 4.1. Standalone Connections
- 4.2. Oracle Net Services Connection Strings
- 4.2.1. Easy Connect Syntax for Connection Strings
- 4.2.2. Connect Descriptors
- 4.2.3. TNS Aliases for Connection Strings
- 4.2.4. LDAP URL Connection Strings
- 4.2.5. Centralized Configuration Provider URL Connection Strings
- 4.2.6. JDBC and Oracle SQL Developer Connection Strings
- 4.2.7. Oracle Net Connect Descriptor and Easy Connect Keywords
- 4.2.8. Python-oracledb Parameters Settable in Easy Connect Strings or Centralized Configuration Providers
- 4.3. Authenticating to Oracle Database
- 4.4. Centralized Configuration Providers
- 4.5. Using the ConnectParams Builder Class
- 4.6. Connection Hook Functions
- 4.7. LDAP Directory Naming
- 4.8. Connection Metadata and Application Contexts
- 4.9. Connection Pooling
- 4.9.1. Driver Connection Pooling
- 4.9.2. Using the Connection Pool Cache
- 4.9.3. Connection Pool Sizing
- 4.9.4. Pool Connection Health
- 4.9.5. Connection Pool Reconfiguration
- 4.9.6. Session Callbacks for Setting Pooled Connection State
- 4.9.7. Heterogeneous and Homogeneous Connection Pools
- 4.9.8. Using the PoolParams Builder Class
- 4.10. Database Resident Connection Pooling (DRCP)
- 4.11. Implicit Connection Pooling
- 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 Through a Firewall via a Proxy
- 4.17. Connecting using Multiple Wallets
- 4.18. Connecting to Oracle Globally Distributed Database
- 5. Authentication Options
- 6. Executing SQL
- 6.1. SQL Queries
- 6.1.1. Fetch Methods
- 6.1.2. Closing Cursors
- 6.1.3. Query Column Metadata
- 6.1.4. Fetch Data Types
- 6.1.5. Changing Fetched Data
- 6.1.6. Fetched Number Precision
- 6.1.7. Scrollable Cursors
- 6.1.8. Fetching Oracle Database Objects and Collections
- 6.1.9. Limiting Rows
- 6.1.10. Fetching Data in Parallel
- 6.1.11. Fetching Raw Data
- 6.1.12. Querying Corrupt Data
- 6.2. INSERT and UPDATE Statements
- 6.1. SQL Queries
- 7. Executing PL/SQL
- 8. Using Bind Variables
- 8.1. Binding by Name or Position
- 8.2. Duplicate Bind Variable Placeholders
- 8.3. Bind Direction
- 8.4. Binding Null Values
- 8.5. Binding ROWID Values
- 8.6. Binding UROWID Values
- 8.7. DML RETURNING Bind Variables
- 8.8. LOB Bind Variables
- 8.9. REF CURSOR Bind Variables
- 8.10. Binding PL/SQL Collections
- 8.11. Binding PL/SQL Records
- 8.12. Binding Spatial Data Types
- 8.13. Reducing the SQL Version Count
- 8.14. Changing Bind Data Types using an Input Type Handler
- 8.15. Binding Multiple Values to a SQL WHERE IN Clause
- 8.16. Binding Column and Table Names
- 9. Batch Statement and Bulk Copy Operations
- 10. Managing Transactions
- 11. Tuning python-oracledb
- 12. Using CLOB, BLOB, NCLOB, and BFILE Data
- 13. Using JSON Data
- 14. Using XMLTYPE Data
- 15. Using VECTOR Data
- 16. Working with Data Frames
- 17. Working with Simple Oracle Document Access (SODA)
- 18. Using Oracle Transactional Event Queues and Advanced Queuing
- 19. Working with Continuous Query Notification (CQN)
- 20. Using Two-Phase Commits (TPC)
- 21. Starting and Stopping Oracle Database
- 22. High Availability with python-oracledb
- 23. Concurrent Programming with asyncio and Pipelining
- 24. Character Sets and Globalization
- 25. Catching Exceptions
- 26. Tracing python-oracledb
- 27. Extending python-oracledb
- 28. Troubleshooting Errors
- 29. Appendix A: Oracle Database Features Supported by python-oracledb
- 30. Appendix B: Differences between python-oracledb Thin and Thick Modes
- 30.1. Connection Handling Differences between Thin and Thick Modes
- 30.2. Connection Pooling Differences between Thin and Thick Modes
- 30.3. Supported Database Data Types in Thin and Thick Modes
- 30.4. Query Metadata in Thin and Thick Modes
- 30.5. Implicit Results in Thin and Thick Modes
- 30.6. Statement Caching in Thin and Thick Modes
- 30.7. Duplicate SQL Bind Variable Placeholders in Thin and Thick Modes
- 30.8. Error Handling in Thin and Thick Modes
- 30.9. Globalization in Thin and Thick Modes
- 30.10. Tracing in Thin and Thick Modes
- 31. Appendix C: The python-oracledb and cx_Oracle Drivers
- 32. Appendix D: Python Frameworks, SQL Generators, and ORMs
API Manual
- 1. API: python-oracledb Module
- 1.1. Oracledb Methods
Binary()clientversion()connect()connect_async()create_pipeline()create_pool()create_pool_async()Date()DateFromTicks()enable_thin_mode()from_arrow()get_pool()init_oracle_client()is_thin_mode()makedsn()register_params_hook()register_password_type()register_protocol()Time()TimeFromTicks()Timestamp()TimestampFromTicks()unregister_params_hook()
- 1.2. Oracledb Attributes
- 1.3. Oracledb Constants
- 1.3.1. Advanced Queuing: Delivery Modes
- 1.3.2. Advanced Queuing: Dequeue Modes
- 1.3.3. Advanced Queuing: Dequeue Navigation Modes
- 1.3.4. Advanced Queuing: Dequeue Visibility Modes
- 1.3.5. Advanced Queuing: Dequeue Wait Modes
- 1.3.6. Advanced Queuing: Enqueue Visibility Modes
- 1.3.7. Advanced Queuing: Message States
- 1.3.8. Advanced Queuing: Other Constants
- 1.3.9. Connection Authorization Modes
- 1.3.10. Pipeline Operation Types
- 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. Two-Phase Commit (TPC) Constants
- 1.3.25. Vector Format Constants
- 1.4. Oracledb Exceptions
- 1.5. Oracledb _Error Objects
- 1.6. Oracledb __future__ Object
- 1.7. Oracledb Plugins
- 1.8. Oracledb IntervalYM Class
- 1.9. Oracledb JsonId Class
- 1.1. Oracledb Methods
- 2. API: Defaults Object
- 3. API: Connection Objects
- 3.1. Connection Class
- 3.2. Connection Methods
Connection.__enter__()Connection.__exit__()Connection.begin()Connection.begin_sessionless_transaction()Connection.cancel()Connection.changepassword()Connection.close()Connection.commit()Connection.createlob()Connection.cursor()Connection.decode_oson()Connection.direct_path_load()Connection.encode_oson()Connection.fetch_df_all()Connection.fetch_df_batches()Connection.getSodaDatabase()Connection.gettype()Connection.is_healthy()Connection.msgproperties()Connection.ping()Connection.prepare()Connection.queue()Connection.resume_sessionless_transaction()Connection.rollback()Connection.shutdown()Connection.startup()Connection.subscribe()Connection.suspend_sessionless_transaction()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.3. 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_identifier_lengthConnection.max_open_cursorsConnection.moduleConnection.outputtypehandlerConnection.proxy_userConnection.sduConnection.serial_numConnection.service_nameConnection.session_idConnection.stmtcachesizeConnection.tagConnection.thinConnection.transaction_in_progressConnection.usernameConnection.versionConnection.warning
- 4. API: ConnectParams Objects
- 4.1. ConnectParams Class
- 4.2. ConnectParams Methods
- 4.3. ConnectParams Attributes
ConnectParams.appcontextConnectParams.cclassConnectParams.config_dirConnectParams.connection_id_prefixConnectParams.debug_jdwpConnectParams.disable_oobConnectParams.driver_nameConnectParams.editionConnectParams.eventsConnectParams.expire_timeConnectParams.externalauthConnectParams.extra_auth_paramsConnectParams.hostConnectParams.https_proxyConnectParams.https_proxy_portConnectParams.instance_nameConnectParams.machineConnectParams.matchanytagConnectParams.modeConnectParams.osuserConnectParams.pool_boundaryConnectParams.pool_nameConnectParams.portConnectParams.programConnectParams.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.ssl_versionConnectParams.stmtcachesizeConnectParams.supershardingkeyConnectParams.tagConnectParams.tcp_connect_timeoutConnectParams.terminalConnectParams.use_sniConnectParams.thick_mode_dsn_passthroughConnectParams.use_tcp_fast_openConnectParams.userConnectParams.wallet_location
- 5. API: ConnectionPool Objects
- 5.1. ConnectionPool Class
- 5.2. ConnectionPool Methods
- 5.3. 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 Class
- 6.2. PoolParams Methods
- 6.3. PoolParams Attributes
PoolParams.connectiontypePoolParams.getmodePoolParams.homogeneousPoolParams.incrementPoolParams.minPoolParams.maxPoolParams.max_lifetime_sessionPoolParams.max_sessions_per_shardPoolParams.ping_intervalPoolParams.ping_timeoutPoolParams.session_callbackPoolParams.soda_metadata_cachePoolParams.timeoutPoolParams.wait_timeout
- 7. API: Cursor Objects
- 7.1. Cursor Class
- 7.2. 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.3. Cursor Attributes
- 8. API: DataFrame Objects
- 9. API: FetchInfo Objects
- 9.1. FetchInfo Class
- 9.2. FetchInfo Attributes
FetchInfo.annotationsFetchInfo.display_sizeFetchInfo.domain_nameFetchInfo.domain_schemaFetchInfo.internal_sizeFetchInfo.is_jsonFetchInfo.is_osonFetchInfo.nameFetchInfo.null_okFetchInfo.precisionFetchInfo.scaleFetchInfo.typeFetchInfo.type_codeFetchInfo.vector_dimensionsFetchInfo.vector_formatFetchInfo.vector_is_sparse
- 10. API: Variable Objects
- 11. API: Subscription Objects
- 12. API: LOB Objects
- 13. API: DbObjectType Objects
- 14. API: SparseVector Objects
- 15. API: Advanced Queuing (AQ)
- 16. API: SODA
- 17. API: AsyncConnection Objects
- 17.1. AsyncConnection Class
- 17.2. AsyncConnection Methods
AsyncConnection.__aenter__()AsyncConnection.__aexit__()AsyncConnection.begin_sessionless_transaction()AsyncConnection.callfunc()AsyncConnection.callproc()AsyncConnection.cancel()AsyncConnection.changepassword()AsyncConnection.close()AsyncConnection.commit()AsyncConnection.createlob()AsyncConnection.cursor()AsyncConnection.decode_oson()AsyncConnection.direct_path_load()AsyncConnection.encode_oson()AsyncConnection.execute()AsyncConnection.executemany()AsyncConnection.fetchall()AsyncConnection.fetch_df_all()AsyncConnection.fetch_df_batches()AsyncConnection.fetchmany()AsyncConnection.fetchone()AsyncConnection.gettype()AsyncConnection.is_healthy()AsyncConnection.msgproperties()AsyncConnection.ping()AsyncConnection.queue()AsyncConnection.resume_sessionless_transaction()AsyncConnection.rollback()AsyncConnection.run_pipeline()AsyncConnection.suspend_sessionless_transaction()AsyncConnection.tpc_begin()AsyncConnection.tpc_commit()AsyncConnection.tpc_end()AsyncConnection.tpc_forget()AsyncConnection.tpc_prepare()AsyncConnection.tpc_recover()AsyncConnection.tpc_rollback()AsyncConnection.xid()
- 17.3. 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_identifier_lengthAsyncConnection.max_open_cursorsAsyncConnection.moduleAsyncConnection.outputtypehandlerAsyncConnection.sduAsyncConnection.serial_numAsyncConnection.service_nameAsyncConnection.session_idAsyncConnection.stmtcachesizeAsyncConnection.thinAsyncConnection.transaction_in_progressAsyncConnection.usernameAsyncConnection.version
- 18. API: AsyncConnectionPool Objects
- 18.1. AsyncConnectionPool Class
- 18.2. AsyncConnectionPool Methods
- 18.3. 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
- 19. API: AsyncCursor Objects
- 19.1. AsyncCursor Class
- 19.2. AsyncCursor Methods
AsyncCursor.__aiter__()AsyncCursor.__aenter__()AsyncCursor.__aexit__()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.scroll()AsyncCursor.setoutputsize()AsyncCursor.var()
- 19.3. AsyncCursor Attributes
- 20. API: AsyncLOB Objects
- 21. API: Async Advanced Queuing (AQ)
- 22. API: Pipeline Objects
- 23. Deprecated and Desupported Features