oracledb

Thin Mode Changes 

Fixed bug when attempting to load boolean values using Direct Path Load ( issue 593 ).

Fixed bug when fetching NCHAR or NVARCHAR2 columns ( issue 595 ).

Fixed segfault when calling Connection.fetch_df_all() and Connection.fetch_df_batches() with data that is null by describe ( issue 597 ).

Fixed bug when acquiring a connection from a pool with a connection class different from the one associated with the pool when the pool is full.

Fixed bug where callers waiting on ConnectionPool.acquire() would wait indefinitely after the pool was forcibly closed.

Fixed bug where ConnectionPool.wait_timeout returned the value in seconds instead of milliseconds.

Fixed segfault when calling AsyncConnectionPool.release() with a connection that has already been returned to the pool.

Fixed bug when attempting to use a proxy user with token authentication .

Thick Mode Changes 

Fixed bug where TIMESTAMP WITH TIME ZONE column data was converted incorrectly to Arrow data frames ( issue 596 ).

Common Changes 

Fixed bug causing an exception to be raised when calling oracledb.is_simple_sql_name() or oracledb.is_qualified_sql_name() with an incorrectly quoted string.

Fixed bug causing precision and scale to be incorrect for timestamps and intervals found within a DbObject .

Thin Mode Changes 

Fixed bug causing a connection pool to grow beyond its maximum allowed connections after requests time out ( issue 581 ).

Fixed bug when executing certain ALTER PLUGGABLE DATABASE commands repeatedly ( issue 587 ).

Fixed bug when parsing a tnsnames.ora file containing an IFILE directive enclosed in quotes ( issue 589 ).

Fixed bug when specifying a value for the ORA_SDTZ environment variable as one of the keywords LOCAL or DBTIMEZONE .

Fixed bug when specifying wallet_location as the keyword SYSTEM (which is equivalent to not specifying a wallet location but using the system trust store instead).

Thick Mode Changes 

Fixed bug when a query containing a LOB column is repeated and the LOB column is transformed to a different value during the first query ( issue 584 ).

Common Changes 

Fixed bug fetching CLOB or BLOB columns with a check constraint mandating the storage of JSON data into a data frame ( issue 586 ).

1. Fixed bugs on 64-bit platforms that caused segmentation faults and bus errors in session pooling and determining the bind variables associated with a statement.

2. Modified test suite so that 64-bit platforms are tested properly.

3. Added missing commit statements in the test setup scripts. Thanks to Keith Lyon for pointing this out.

4. Fix setup.py for Cygwin environments. Thanks to Doug Henderson for providing the necessary fix.

5. Added support for compiling cx_Oracle without thread support. Thanks to Andre Reitz for pointing this out.

6. Added support for a new keyword parameter called threaded on connections and session pools. This parameter defaults to False and indicates whether threaded mode ought to be used. It replaces the module level attribute OPT_Threading although examining the attribute will be retained until the next release at least.

7. Added support for a new keyword parameter called twophase on connections. This parameter defaults to False and indicates whether support for two phase (distributed or global) transactions ought to be present. Note that support for distributed transactions is buggy when crossing major version boundaries (Oracle 8i to Oracle 9i for example).

8. Ensure that the rowcount attribute is set properly when an exception is raised during execution. Thanks to Gary Aviv for pointing out this problem and its solution.

Thin Mode Changes 

Added support for Oracle Deep Data Security .

Added support for Continuous Query Notification (CQN) and Oracle Advanced Queuing (AQ) notifications.

Fixed bug when using Direct Path Load with a single byte database character set ( issue 567 ).

Fixed bug when decoding/encoding strings found within database objects ( issue 371 ).

Fixed bug when an unexpected error is thrown during authentication when using authentication tokens ( issue 542 ).

Fixed bug writing boolean values to PL/SQL stored procedures and functions ( issue 568 ).

Added support for CLOBs that were originally created in Oracle Database 9i.

Thick Mode Changes 

Added support for creating a cursor object from an external Oracle Call Interface OCIStmt handle. The external handle should be wrapped in a PyCapsule named oci_stmt_handle . A new property Cursor.handle was also added to provide access to the internal OCIStmt handle in order to facilitate testing and to support external use, if required.

Methods Connection.fetch_df_all() and Connection.fetch_df_batches() now support an optional handle argument to pass an external OCIStmt handle wrapped in a PyCapsule named oci_stmt_handle .

Dropped support for Oracle Client libraries before 19c.

Common Changes 

Added save_secret() and get_secret() to store and retrieve secrets either globally or by using thread local storage.

Added enquote_literal() , enquote_name() , is_qualified_sql_name() and is_simple_sql_name() to assist developers in avoiding SQL injection when processing user input.

Added attribute ConnectParams.on_connect_callback which can be set to a callable that is invoked when a standalone connection is created or a connection is acquired from a connection pool.

Improved cloud native authentication plugins:

Added Session Token-based authentication support to the OCI Tokens plugin . ( issue 527 ).

Added Resource Principal authentication support to the OCI Tokens plugin .

Fixed bug when using multiple token authentication plugins. Note that an invalid auth_type parameter will no longer raise an exception but will simply be ignored.

Removed unnecessary validation calls in the OCI Tokens plugin .

Added support for inserting data frames containing binary views (format “vb”) and string views (format “vu”) ( issue 573 ).

Added support for comparing sparse vectors with other sparse vectors.

Added support for sparse vectors with no non-zero values.

Added support for compiling with the HP aCC compiler ( issue 556 ).

Fixed bug when inserting data frames that are views of other data frames ( issue 574 ).

Updated the Jupyter notebook samples to cover recent python-oracledb features.

Upgraded Arrow C Data (nanoarrow) API version to 0.8.0.

Thin Mode Changes 

Fixed bug which caused Connection.call_timeout to be reset to zero when a ping is internally executed by the pool before the connection is returned to the user ( issue 558 ).

Fixed bug when decoding PL/SQL booleans in Oracle Database 12.1 ( issue 565 ).

Fixed bug when a DbObject instance contains an attribute of type SYS.XMLTYPE .

Common Changes 

Fixed bug when getting the expiry time of authentication tokens ( issue 548 ).

Fixed bug when calling Cursor.executemany() with all of the values in at least one column being null followed by a second call where at least the first row also has a null value but some of the later values are not null ( issue 291 ).

Added support for ingesting Arrow arrays which only consist of null values ( issue 554 ).

Fixed regression with contents of Cursor.description when calling Cursor.parse() with a query that returns LOBs.

Eliminated memory leak when converting a third party data frame to one used internally by the driver ( issue 561 ).

Fixed bug causing hang when using asyncio and the database closes the connection before the connection is returned to the user.

Eliminated race condition in background thread/coroutine management for connection pools.

Adjusted code and tests to be capable of being run in environments other than CPython.

Thin Mode Changes 

Fixed bug when fetching a timestamp with nanosecond precision into a data frame ( issue 538 ).

Fixed bug when adding a call to a PL/SQL function which returns LOBs to a pipeline .

Fixed bug when using bind variables with scrollable cursors.

Fixed bug when setting SOURCE_ROUTE on the DESCRIPTION section of a full connect descriptor instead of the ADDRESS_LIST section.

Fixed bug that failed to handle the KeyboardInterrupt exception correctly when the application caught this exception and then tried to reuse the connection.

Thick Mode Changes 

Fixed segfault on some platforms when trying to execute queries returning vector columns ( ODPI-C dependency update).

Common Changes 

Fixed bug that caused ORA-03137: malformed TTC packet from client rejected exception to be raised when attempting to call Cursor.parse() on a scrollable cursor.

Error DPY-2069: requested schema has {num_schema_columns} columns defined but {num_fetched_columns} columns are being fetched is now raised when the number of elements in the requested_schema parameter to Connection.fetch_df_all() and Connection.fetch_df_batches() doesn’t match the number of columns being fetched. Previously this scenario would throw unhelpful execptions or cause a segfault under certain circumstances.

Error DPY-2068: scroll operation is not supported on a non-scrollable cursor is now raised when using Cursor.scroll() method on a non-scrollable cursor.

Thin Mode Changes 

Added support for Oracle Database’s Direct Path Load functionality which is very efficient for loading large datasets into a database. Data may be a list of sequences or a DataFrame object.

Fixed bug when setting values of type datetime.date on variables (such as created by Cursor.var() or implicitly by Cursor.setinputsizes() ) of types oracledb.DB_TYPE_TIMESTAMP , oracledb.DB_TYPE_TIMESTAMP_TZ and oracledb.DB_TYPE_TIMESTAMP_LTZ .

Fixed bug validating the database host during connection.

Fixed bug causing hang due to blocked task cancellation during asyncio loop shutdown.

Internal change: refactor encoding of Oracle data types.

Internal change: small performance improvement sending bytes on the network transport.

Thick Mode Changes 

Fixed bug with error wrapping which could result in garbage characters being introduced. Fixed potential bug when truncation could occur with very large error messages.

Executed statements are normalized by removing leading and trailing spaces before being sent to Oracle Database.

Common Changes 

Changes to data frame support:

Support for data frames is no longer considered a pre-release.

Added parameter requested_schema to Connection.fetch_df_all() and Connection.fetch_df_batches() to support type mapping when querying ( issue 494 ).

The Apache Arrow data type “large” variants that have 64-bit offsets are now used by default for strings and binary values in order to avoid the limits imposed by using 32-bit offsets. Use requested_schema if the smaller offset size is desired ( issue 536 ).

Added support for all of the signed and unsigned fixed width integer types when ingesting data frames supporting the Arrow PyCapsule interface. Previously only int64 was supported.

Added support for types date32 and date64 when ingesting data frames supporting the Arrow PyCapsule interface as requested ( issue 535 ).

Ingesting data frames with multiple chunks is now supported.

Error DPY-8002: Apach Arrow C Data structure overflow detected. A larger structure is needed. is now raised when an overflow is detected ( issue 536 ).

Fixed bug when fetching NCHAR and NVARCHAR2 column data.

Fixed bug when attempting to convert an integer that cannot be represented as a native C int value to an Arrow data frame ( issue 537 ).

Added a batch_size parameter to Cursor.executemany() and AsyncCursor.executemany() to let these methods operate on data in batches.

Added fetch_lobs and fetch_decimals parameters where applicable to the methods used for fetching rows or data frames from the database. Note that for the creation of pipeline operations, if these parameters are not specified then the values of oracledb.defaults.fetch_lobs and oracledb.defaults.fetch_decimals are now stored with the operation and used during pipeline execution ( issue 19 ).

Added optional dependencies [oci_config] , [azure_config] , [oci_auth] , and [azure_auth] to simplify installation of required packages for Centralized Configuration Provider support and Cloud Native Authentication support ( issue 512 ).

The x86_64 macOS and 32-bit Windows platforms are deprecated . They will be desupported in a future release before, or when, the cryptography package desupports them. See the cryptography deprecation announcement .

Connectivity and interoperability with Oracle Database and Oracle Client libraries older than version 19 is deprecated and will be removed in a future version of python-oracledb. Production use, and availability of database and client software, is detailed in Release Schedule of Current Database Releases .

Pin Cython to 3.1.x instead of 3.1.0 as requested ( issue 530 ).

Fixed bug when attempting to execute an empty statement ( issue 525 ).

Fixed bug when attempting to append an element to a DbObject which is not actually a collection.

API documentation is now generated from the source code.

The test suite now uses pytest .

Internal change: the value of module for all classes is now left untouched to avoid issues with inspect.getsource() but repr() now consistently shows the module as oracledb .

Internal change: typing_extensions is now a dependency.

Thin Mode Changes 

Error DPY-3001: session tagging is only supported in python-oracledb thick mode is now raised when attempting to use session tagging with a connection pool. Previously a NotImplementedError exception was raised instead.

Fixed bug in the calculation of attribute MessageProperties.deliverymode . Previously it was being set to the value of the attribute DeqOptions.deliverymode .

Fixed bug with detection of when a connection has been closed by the database without notification.

Fixed bug with execution of a PL/SQL block containing at least one output bind variable immediately following a query that returned multiple duplicate rows.

Fixed bug with connect strings containing SOURCE_ROUTE=YES where the second host is unresolvable by the host running python-oracledb.

Thick Mode Changes 

Fixed regression resulting in cursor leak ( issue 513 ).

Common Changes 

Pre-built binaries are now being created for Python 3.14. Note this Python version is currently in release candidate phase.

Added support for Oracle Database 23.6 Sessionless Transactions .

Changes to data frame support:

Added support for binding data frames to Cursor.executemany() and AsyncCursor.executemany() for fast data ingestion. See Inserting Data Frames .

Added internal support for the ArrowArrayStream PyCapsule interface to simplify DataFrame use.

Removed use of the DataFrame Interchange Protocol in python-oracledb DataFrame objects.

Removed the prefix “Oracle” from the data frame object names. They are now called DataFrame and ArrowArray .

Documentation on methods and attributes of the DataFrame and ArrowArray objects is now available when using IDE introspection.

Upgraded Arrow C Data (nanoarrow) API version to 0.7.0.

Ensured that the Python GIL is held when releasing references to ArrowArray objects when exported Arrow buffers are released by the consumer. This avoids a segfault seen in some circumstances.

Fixed bug when deciding Arrow datatype for numeric expressions. ( issue 510 )

Fixed bug when fetching numeric data that has no decimal point but the Arrow array has scale > 0.

Fixed bug when fetching dates that are in the year 2038 or later.

Fixed bug when fetching numeric data with precision that exceeds 38 as decimal data.

Fixed bug when fetching large amounts of data in one round-trip when using asyncio with Oracle Database 21c and earlier.

Note the data frame support in python-oracledb 3.3 is a pre-release, and may change in a future version.

Internal change: migrated build configuration completely to pyproject.toml, which allows for optional dependencies for the test suite on the numpy, pandas and pyarrow modules.

Thin Mode Changes 

Added support for recipient lists in Oracle Advanced Queuing.

Emulate support for Queue.deqmany() with JSON payloads when using Oracle Database 21c by internally calling Queue.deqone() as many times as needed.

Pooled connections that are no longer needed are now closed normally if possible instead of simply having the socket disconnected ( issue 393 ).

Fixed bug when a connection pool internally makes an attempt to ping a closed connection ( issue 482 ).

Fixed bug when connecting with asyncio using the parameter https_proxy .

Fixed bug when fetching LOBs with asyncio from Oracle Database 21c and earlier ( issue 500 ).

Fixed regression when connecting where only the host specified by the https_proxy parameter can successfully perform name resolution.

Fixed bug resulting in explicit request boundaries to aid planned database maintenance not being sent when using connection pools with asyncio.

Fixed bug populating MessageProperties.deliverymode after dequeue, which is set using DeqOptions.deliverymode .

Fixed bug resulting in TypeError when using DeqOptions.correlation for buffered delivery mode.

Fixed bug when fetching multiple consecutive null values into a data frame .

Fixed bug using Oracle Advanced Queuing when attempting to dequeue using an invalid DeqOptions.msgid .

Fixed bug resulting in an exception when Cursor.executemany() is called with SQL containing bind variables and an empty parameter set ( issue 508 ).

Thick Mode Changes 

Fixed a bug resulting in error DPI-1046: parameter value cannot be a NULL pointer when the attributes DeqOptions.condition , DeqOptions.consumername , DeqOptions.correlation , DeqOptions.msgid , DeqOptions.transformation , EnqOptions.transformation , MessageProperties.correlation , or MessageProperties.exceptionq are set to None .

Fixed a bug resulting in a ValueError exception when getting attribute MessageProperties.enqtime if the value is not available or None .

Fixed a memory leak when enqueuing to JSON queues with Oracle Advanced Queuing .

Common Changes 

Added Instance Principal authentication support when using OCI Cloud Native Authentication .

Improvements to data frame support:

Added support for VECTOR columns when fetching data frames.

Fixed date handling to match PyArrow’s and avoid localization issues ( issue 499 ).

Fixed bug on Windows when fetching dates prior to 1970 and after 2038 ( issue 483 ).

Added support for the NCHAR, NVARCHAR and NCLOB data types ( issue 505 ).

Added parameter pool_name to connection and pool creation methods to support Oracle Database 23.4 multi-pool Database Resident Connection Pooling (DRCP) .

GitHub Action workflow updates:

Use GitHub Arm Linux runner for builds. Supplied by wojiushixiaobai ( PR 496 ).

Allow the GitHub build action to build a user-chosen subset of packages.

Fix bug with GitHub build action merge artifacts step ( issue 495 ).

Error DPY-2064: parameter 'max' should be greater than or equal to parameter 'min' is now raised when a call to oracledb.create_pool() , oracledb.create_pool_async() or oracledb.PoolParams() is made with parameter max less than the parameter min . Previously python-oracledb Thin mode did not raise an error and python-oracledb Thick mode raised the exception ORA-24413: Invalid number of sessions specified .

Improved the test suite and documentation.

Thin Mode Changes 

Fixed bug with Connection.is_healthy() after a session is killed, such as by a DBA running ALTER SYSTEM KILL SESSION. Previously, in some databases, it could incorrectly return True , while in other cases it could hang.

Common Changes 

Added support for using the Cython 3.1 release ( issue 493 ).

Improvements to data frame fetching with Connection.fetch_df_all() and Connection.fetch_df_batches() :

Added support for converting an OracleDataFrame object to a foreign data frame object more than once ( issue 470 ).

Fixed a bug resulting in a segfault when attempting to use an output type handler while fetching data frames ( issue 486 ).

Fixed memory corruption in data frame queries ( issue 489 ).

Fixed parsing of the connection string in the Azure App Centralized Configuration Provider .

Miscellaneous grammar and spelling fixes by John Bampton ( PR 479 ).

Thin Mode Changes 

Added support for scrollable cursors .

Improved support for Oracle Advanced Queuing :

Added support for JSON payloads

Added support for bulk enqueuing and dequeuing

Added support for using AQ with asyncio

Improved error message when the cryptography package cannot be imported ( issue 455 ).

Fixed decoding of nested PL/SQL records ( issue 456 ).

Fixed wildcard matching of domains in Subject Alternative Names ( issue 462 ).

Fixed bug when binding a temporary LOB IN/OUT to a PL/SQL procedure ( issue 468 ).

Fixed bug when an error is reported by the server in the middle of a response to a client request ( issue 472 ).

Fixed bug when connecting to an AC-enabled service ( issue 476 ).

Fixed bug when using temporary LOBs with implicit pooling.

Fixed bug when fetching nested cursors.

Thick Mode Changes 

Fixed bug resulting in a segfault when unable to load the Oracle Client libraries ( ODPI-C dependency update).

Fixed bug which resulted in error ORA-24328: illegal attribute value when calling Connection.gettype() with Oracle Client 11.2 libraries ( ODPI-C dependency update).

Improved error message when getting Connection.max_open_cursors when using Oracle Client 11.2 libraries ( ODPI-C dependency update).

Improved error message when attempting to work with sparse vectors using Oracle Client 23.6 (or earlier) libraries ( ODPI-C dependency update).

Common Changes 

Dropped support for Python 3.8.

Improvements to data frame fetching with Connection.fetch_df_all() and Connection.fetch_df_batches() :

Added support for CLOB, BLOB, and RAW data types

Fixed support for BOOLEAN data type

Fixed bug when NUMBER data is fetched that does not have a precision or scale specified and oracledb.defaults.fetch_decimals is set to True .

More efficient processing when a significant amount of data is duplicated from one row to the next

Avoid memory allocation/free cycles for decimal data

Eliminated memory leak if OracleDataFrame is not converted to an external data frame

Eliminated small memory leak with production of each data frame

Made the Azure App Centralized Configuration Provider connection string suffix “.azconfig.io” optional.

Fixed bug when binding a variable that was previously bound as an output variable in a DML RETURNING statement.

Fixed bug when multiple rows containing LOBs and DbObjects are returned in a DML RETURNING statement.

An error message that links to documentation on setting up a protocol hook function is now returned by default for LDAP and LDAPS URL connection strings in python-oracledb Thin mode, or when oracledb.defaults.thick_mode_dsn_passthrough is False .

Error DPY-2062: payload cannot be enqueued since it does not match the payload type supported by the queue is now raised when the payload of a message being enqueued is not supported by the queue. Previously, python-oracledb Thick mode raised the error DPI-1071: payload type in message properties must match the payload type of the queue and Thin mode raised an internal error.

Improved the test suite and documentation.

Thin Mode Changes 

Added Oracle Advanced Queuing support for single enqueue and dequeue of RAW and Oracle object payload types.

Added namespace package oracledb.plugins for plugins that can be used to extend the capability of python-oracledb.

Added support for property ConnectionPool.max_lifetime_session ( issue 410 ).

Added parameter ConnectParams.use_sni to specify that the TLS SNI extension should be used to reduce the number of TLS negotiations that are needed to connect to the database.

Added parameter ConnectParams.instance_name to specify the instance name to use when connecting to the database. Added support for setting the instance name in Easy Connect strings .

Added support for Transaction Guard by adding support to get the values of Connection.ltxid and oracledb._Error.isrecoverable .

Improved support for planned database maintenance by internally sending explicit request boundaries when using python-oracledb connection pools.

Perform TLS server matching in python-oracledb instead of the Python SSL library to allow alternate names to be checked ( issue 415 ).

Host names are now resolved to IP addresses in python-oracledb instead of the Python libraries. Address list load balancing and failover settings will be used when establishing connections.

The thread that closes connection pools on interpreter shutdown is now only started when the first pool is created and not at module import ( issue 426 ).

Support for Pipelining is no longer considered a pre-release.

Fixed hang when attempting to use pipelining against a database that doesn’t support the end of response flag.

Fixed hang when using asyncio and a connection is unexpectedly closed by the database.

Fixed bug when using asyncio and calling a stored procedure with data that exceeds 32767 bytes in length ( issue 441 ).

Fixed bug when attempting to fetch a database object stored in a LOB. The fetch will still fail but with an unsupported error exception instead of a hang.

Error DPY-6002: The distinguished name (DN) on the server certificate does not match the expected value: "{expected_dn}" now shows the expected value.

Error DPY-6006: The name on the server certificate does not match the expected value: "{expected_name}" is now raised when neither the common name (CN) nor any of the subject alternative names (SANs) found on the server certificate match the host name used to connect to the database.

The text of error DPY-4022: invalid value for DRCP purity {purity} changed to DPY-4022: invalid value for enumeration {name}: {value} .

Error DPY-3001: bequeath is only supported in python-oracledb thick mode is now raised when attempting to connect to the database without a connect string.

Error DPY-3001: Native Network Encryption and Data Integrity is only supported in python-oracledb thick mode is now the secondary error message returned when Oracle Net NNE or checksumming is required by the database. Previously, the error DPY-4011: the database or network closed the connection was raised.

Optimization: the connect descriptor sent to the database does not include the RETRY_DELAY parameter unless the RETRY_COUNT parameter is also specified.

Internal change: improve low-level encoding and decoding routines.

Internal change: send buffer length for bind variables without unneeded adjustment.

Thick Mode Changes 

At successful completion of a call to oracledb.init_oracle_client() , the value of oracledb.defaults.config_dir may get set by python-oracledb in some cases. For example it might be set to the configuration directory that is relative to the loaded Oracle Client libraries.

Connect string parsing and tnsnames.ora file handling can be configured with the new parameter oracledb.defaults.thick_mode_dsn_passthrough which can be helpful for application portability. When it is False , python-oracledb Thick mode behaves similarly to Thin mode.

Fixed bug that caused oracledb._Error.isrecoverable to always be False .

Common Changes 

Added new methods Connection.fetch_df_all() , Connection.fetch_df_batches() , AsyncConnection.fetch_df_all() , and AsyncConnection.fetch_df_batches() to fetch data as OracleDataFrame objects that expose an Apache Arrow PyCapsule interface for efficient data exchange with external libraries. See Working with Data Frames .

Added support for Oracle Database 23.7 SPARSE vectors .

Added support for naming and caching connection pools during creation, and retrieving them later from the python-oracledb pool cache with oracledb.get_pool() .

Added Centralized Configuration Provider support for Oracle Cloud Infrastructure Object Storage, Microsoft Azure App Configuration, and file-based configurations.

Added oracledb.register_password_type() to allow users to register a function that will be called when a password is supplied as a dictionary containing the key “type”.

Added cloud native authentication support through the integration of Oracle Cloud Infrastructure (OCI) SDK and Azure SDK.

Added parameter extra_auth_params to oracledb.connect() , oracledb.connect_async() , oracledb.create_pool() , and oracledb.create_pool_async() which is used to specify the configuration parameters required for cloud native authentication.

Added oracledb.register_params_hook() and oracledb.unregister_params_hook() which allow users to register or unregister a function that manipulates the parameters used for creating pools or standalone connections. See oci_tokens and azure_tokens plugins which make use of this functionality.

Added attributes DbObjectAttr.precision , DbObjectAttr.scale , and DbObjectAttr.max_size that provide additional metadata about database object attributes .

The attribute oracledb.defaults.config_dir is now set to $ORACLE_HOME/network/admin if the environment variable ORACLE_HOME is set and TNS_ADMIN is not set.

All connect strings are parsed by the driver if the new parameter thick_mode_dsn_passthrough is set to True . Previously, only Thin mode parsed all connect strings and Thick mode passed the connect string unchanged to the Oracle Client library to parse. Parameters unrecognized by the driver in Easy Connect strings are now ignored. Parameters unrecognized by the driver in the DESCRIPTION , CONNECT_DATA and SECURITY sections of a full connect descriptor are passed through unchanged. All other parameters in other sections of a full connect descriptor that are unrecognized by the driver are ignored.

Fixed bug where some DbObject attributes for database objects defined using ANSI names (including FLOAT and REAL) may have shown as integers.

All Oracle errors that result in the connection no longer being usable will be raised as DPY-4011: the database or network closed the connection with the underlying reason being included in the error message.

Fix typing issue with oracledb.connect() , oracledb.connect_async() , oracledb.create_pool() and oracledb.create_pool_async() ( issue 438 ).

Fix typing issues with setters for oracledb.defaults.fetch_lobs and oracledb.defaults.fetch_decimals ( issue 458 ).

Error DPY-2053: python-oracledb thin mode cannot be used because thick mode has already been enabled is now raised when attempting to use asyncio in Thick mode ( issue 448 ).

Error DPY-2056: registered handler for protocol "{protocol}" failed for arg "{arg}" is now raised when an exception occurs when calling the registered handler for a protocol.

Added a sample Dockerfile that can be used to create a container for developing and deploying python-oracledb applications.

Internal change: improve handling of metadata.

Internal build tool change: bumped minimum Cython version to 3.0.10 to avoid bug in earlier versions.

Improved test suite and documentation.

Thin Mode Changes 

Fixed bug when table recreation changes the data type of a column from oracledb.DB_TYPE_LONG or oracledb.DB_TYPE_LONG_RAW to a different compatible type ( issue 424 ).

If the database states that an out-of-band break check should not take place during connect (by setting the DISABLE_OOB_AUTO parameter to TRUE), python-oracledb no longer attempts to do so ( issue 419 ).

All exceptions subclassed from OSError now cause connection retry attempts, subject to the connection retry_count and retry_delay parameters ( issue 420 ).

Thick Mode Changes 

Fixed bug calculating property Connection.max_identifier_length when using Oracle Client libraries 12.1, or older. The returned value may now be None when the size cannot be reliably determined by python-oracledb, which occurs when using Oracle Client libraries 12.1 (or older) to connect to Oracle Database 12.2, or later. ( ODPI-C dependency update).

Fixed bug resulting in a segfault when using external authentication ( issue 425 ).

Common Changes 

Fixed bug when fetching empty data from CLOB or BLOB columns marked with the IS JSON constraint ( issue 429 ).

Thin Mode Changes 

Added attributes Connection.session_id and Connection.serial_num that provide information about the session identifier and session serial number associated with a connection.

Added attributes oracledb.defaults.driver_name , oracledb.defaults.machine , oracledb.defaults.osuser , oracledb.defaults.program , and oracledb.defaults.terminal to set information about the driver name, machine name, operating system user, program name, and terminal name respectively. The driver_name , machine , osuser , program , and terminal parameters were also added to oracledb.connect() , oracledb.connect_async() , oracledb.create_pool() , and oracledb.create_pool_async() ( issue 343 ).

Added oracledb.register_protocol() to allow users to register a function that will be called when a particular protocol is detected in a connection string.

Added oracledb.enable_thin_mode() as a means of enabling python-oracledb Thin mode without waiting for an initial connection to be successfully established. Since python-oracledb defaults to Thin mode, this method is mostly useful for applications with multiple threads concurrently creating connections to databases when the application starts ( issue 408 ).

Added attribute PipelineOpResult.warning to provide information about any warning that was encountered during the execution of a pipeline operation.

Added attribute PipelineOpResult.columns to provide information about any query column metadata returned from a pipeline operation.

Added support for setting the edition when connecting to Oracle Database.

Added support for Application Contexts, i.e. the appcontext parameter is supported when connecting.

Fixed bug causing some pooled connections to be permanently marked as busy and unavailable for reuse ( issue 392 ).

Fixed bug with error handling when calling Connection.gettype() for a type that exists but on which the user has insufficient privileges to view ( issue 397 ).

Fixed bug when calling ConnectParams.parse_dsn_with_credentials() with an Easy Connect string containing a protocol.

Fixed bug when calling Cursor.parse() with autocommit enabled.

Fixed bug when parsing a tnsnames.ora files file with a connect descriptor containing an embedded comment.

Fixed bug when calling AsyncConnection.run_pipeline() with a DML RETURNING statement that results in an error.

Fixed error message when a SQL statement is parsed containing a q-string without a closing quote.

Fixed bug affecting Python interpreter shut down using connection pooling in SQLAlchemy. Pooled connection shutdown now occurs separately from pool destruction.

Thick Mode Changes 

Use locale.getencoding() with Python 3.11 and higher to determine the encoding to use for the config_dir and lib_dir parameters to oracledb.init_oracle_client() . Bytes are also accepted in which case they will be used as is without any encoding ( issue 255 ).

Fixed bug preventing subscriptions from invoking the callbacks associated with them ( issue 409 ).

Fixed bug affecting Application Continuity when older Oracle Client libraries are used ( ODPI-C dependency update).

Common Changes 

Added support for returning the maximum identifier length allowed by the database using the new property Connection.max_identifier_length ( issue 395 ).

Improved type hints for cursors ( issue 391 ).

Improved error message when attempting to access attributes on a connection before a connection has been established or a connection pool before it has been created ( issue 385 ).

The variables saved with Cursor.setinputsizes() are now forgotten when an exception is raised ( issue 411 ).

Fixed bug when calling ConnectParams.set() with a value of None for the connectiontype and session_callback parameters. Previously, any values set earlier would be improperly cleared and now they are retained ( issue 404 ).

Improved test suite and documentation.

Thin Mode Changes 

Fixed bug when detecting in-band notification warnings while the connection is being created or actively used ( issue 383 ).

Thin Mode Changes 

Added support for Oracle Database 23.4 statement pipelining .

Fixed bug resulting in a segfault when a closed cursor is bound as a REF CURSOR ( issue 368 ).

Fixed bug resulting in an inability to connect to Oracle Database version 23 instances which have fast authentication disabled.

Fixed error message when idle time is exceeded by a connection. The error DPY-4033: the database closed the connection because the connection's idle time has been exceeded is now raised when this situation is detected.

Reworked connection string parser:

Fixed parsing an Easy Connect string starting with “ // ” ( issue 352 ).

Fixed parsing an Easy Connect string with multiple hosts (a comma for multiple addresses and a semicolon for multiple address lists).

Fixed parsing an Easy Connect string with a static IPv6 address.

Improved error when a connect descriptor parameter like DESCRIPTION or ADDRESS incorrectly contains a simple value instead of nested values.

Reworked tnsnames.ora file parser to handle multiple aliases found on separate lines ( issue 362 ).

Thick Mode Changes 

Variables containing cursors, LOBs or DbObject values now return the same instances when calling Var.getvalue() , matching Thin mode behavior. Previously, new instances were created for each call in Thick mode.

Common Changes 

Added support for Python 3.13 and dropped support for Python 3.7.

Attribute ConnectionPool.getmode is now one of the values of the enumeration connection pool get modes in order to be consistent with the other uses of this attribute.

Error DPY-3027: binding a cursor from a different connection is not supported is now raised when attempting to bind a cursor created on a different connection. Previously, the attempt may have succeeded or may have failed with a number of different unexpected exceptions.

Error DPY-1006: cursor is not open is now raised consistently when attempting to bind a closed cursor. Previously, Thin mode would result in a segfault and Thick mode would result in unusual errors.

Thin Mode Changes 

Added support for two-phase commits .

Added support for columns of type BFILE.

When calling ConnectionPool.acquire() or AsyncConnectionPool.acquire() , the connection pool mode oracledb.POOL_GETMODE_TIMEDWAIT now always honors the wait_timeout value and the connection request will not additionally be delayed by any internal network ping to the database ( issue 330 ).

Fixed bug when calling oracledb.connect_async() multiple times concurrently ( issue 353 ).

Fixed bug in fetching dates with years less than 0 ( issue 345 ).

Thick Mode Changes 

Eliminated memory leak when dequeing messages with JSON payloads ( issue 346 ).

An exception is now avoided if an error message is not correctly UTF-8 encoded by the database.

Common Changes 

Added support for Oracle Database 23.5 BINARY vector format .

Replaced integer constants for connection authorization modes , connection pool get modes , connection pool purity constants and vector format constants with enumerations in order to provide a more useful repr() and improve type safety, among other things.

The default value of the tcp_connect_timeout parameter was changed from 60 seconds to 20 seconds. The default value of the retry_delay parameter was changed from 0 seconds to 1 second.

Added parameter ssl_version to oracledb.connect() oracledb.connect_async() , oracledb.create_pool() , and oracledb.create_pool_async() methods in order to specify which TLS version to use when establishing connections with the protocol “tcps”.

Added parameter ping_timeout to methods oracledb.create_pool() and oracledb.create_pool_async() with a default value of 5000 milliseconds. This limits the amount of time that a call to acquire() will wait for a connection to respond to any internal ping to the database before the connection is considered unusable and a different connection is returned to the application. Previously, a fixed timeout of 5000 milliseconds was used in Thick mode and no explicit timeout was used in Thin mode.

Added support for maintainers to specify optional compilation arguments when building python-oracledb. A new environment variable PYO_COMPILE_ARGS can be set before building .

Improved detection of the signature used by output type handlers, in particular those that that make use of call() .

Python wheel package binaries for Linux on PyPI are now stripped to reduce their size.

Error DPY-2049: invalid flags for tpc_begin() is now raised when invalid flags are passed to Connection.tpc_begin() . Previously, TypeError or ORA-24759: invalid transaction start flags was raised instead.

Error DPY-2050: invalid flags for tpc_end() is now raised when invalid flags are passed to Connection.tpc_end() . Previously, TypeError or DPI-1002: invalid OCI handle was raised instead.

Error DPY-3025: operation is not supported on BFILE LOBs is now raised when operations are attempted on BFILE LOBs that are not permitted. Previously, ORA-22275: invalid LOB locator specified was raised instead.

Error DPY-3026: operation is only supported on BFILE LOBs is now raised when operations are attempted on LOBs that are only supported by BFILE LOBs. Previously, DPI-1002: invalid OCI handle was raised instead.

Error DPY-4005: timed out waiting for the connection pool to return a connection is now raised consistently when using get mode oracledb.POOL_GETMODE_TIMEDWAIT and the timeout expires. Previously asyncio.TimeoutError was being raised when using asyncio and ORA-24457: OCISessionGet() could not find a free session in the specified timeout period was being raised in Thick mode.

If both the sid and service_name parameters are specified to oracledb.makedsn() , now only the service_name parameter is used and the sid parameter is ignored.

Fixed bug in ConnectParams.set() where parameters found in a connect string (like host and service_name ) would be ignored.

Fixed bug in Connection.tpc_recover() where the returned items were not of the type returned by Connection.xid() as documented.

Internal changes to ensure that no circular imports occur.

Thin Mode Changes 

Fixed bug when a DbObject instance contains an attribute of type SYS.XMLTYPE ( issue 336 ).

Fixed bug when fetching LOBs after an exception has been raised ( issue 338 ).

Fixed bug when a connect descriptor is used that doesn’t define any addresses ( issue 339 ).

Fixed bug in statement cache when the maximum number of cursors is unknown due to the database not being open.

Fixed bug in handling redirect data with small SDU sizes.

Fixed bug with TLS renegotiation under some circumstances.

Adjusted handling of internal break/reset mechanism in order to avoid potential hangs in some configurations under some circumstances.

Thin Mode Changes 

Fixed bug in handling invisible columns with object type names containing %ROWTYPE ( issue 325 ).

Fixed bug that would cause pooled connections to be marked checked out but be unavailable for use permanently ( issue 221 ).

Fixed bug that would cause an internal error to be raised when attempting to close a connection that has been forcibly closed by the database.

Internal change: further efforts to tighten code looking for the end of a database request made to Oracle Database version 23.

Common Changes 

Added support for Oracle Database 23.4 columns of type VECTOR .

Added support for columns of type INTERVAL YEAR TO MONTH which can be represented in Python by instances of the new oracledb.IntervalYM class ( issue 310 ).

Added support for processing tnsnames.ora files containing IFILE directives ( issue 311 ).

Added support for getting a list of the network service names found in a tnsnames.ora file by adding the method ConnectParams.get_network_service_names() ( issue 313 ).

Added support for iterating over DbObject instances that are collections ( issue 314 ).

Error ORA-24545: invalid value of POOL_BOUNDARY specified in connect string is now raised consistently for both Thick and Thin modes. Previously, Thin mode was raising the error DPY-4030: invalid DRCP pool boundary {boundary} .

Thin Mode Changes 

Fixed bug that prevented error ORA-01403: no data found from being raised when executing a PL/SQL block ( issue 321 ).

Common Changes 

Fixed the internal regular expression used for parsing Easy Connect strings to avoid errors with connection string arguments containing the / character.

Thin Mode Changes 

Fixed bug when calling gettype() with an object type name containing %ROWTYPE ( issue 304 ).

Error DPY-2048: the bind variable placeholder ":{name}" cannot be used both before and after the RETURNING clause in a DML RETURNING statement is now raised when the same bind variable placeholder name is used both before and after the RETURNING clause in a DML RETURNING statement . Previously, various internal errors were raised.

Restored the error message raised when attempting to connect to Oracle Database 11g.

Internal change: tightened up code looking for the end of a database request.

Network packet output is now immediately flushed in order to avoid losing output due to buffering when multiple threads are running.

Thin Mode Changes 

Oracle Database version 23 feature support:

Added support for implicit connection pooling with DRCP and PRCP , enabled by the new pool_boundary parameter to oracledb.connect() , oracledb.connect_async() , oracledb.create_pool() and oracledb.create_pool_async() .

Improved the performance of connection creation by reducing the number of round trips required for all connections.

Added support for TCP Fast Open for applications connecting from within the OCI Cloud network to Oracle Autonomous Database Serverless (ADB-S), enabled by the new use_tcp_fast_open parameter to oracledb.connect() , oracledb.connect_async() , oracledb.create_pool() and oracledb.create_pool_async() .

asyncio changes:

Support for asyncio is no longer considered a pre-release.

Internal change to improve handling of packets.

Fixed bug when using DRCP .

Fixed bug in processing metadata that spans multiple network packets.

Fixed bug when connecting to a database using listener redirects ( issue 285 ).

Added support for Easy Connect strings found in tnsnames.ora files.

Added support for writing UTF-8 encoded bytes to CLOB and NCLOB values and writing strings to BLOB values in order to be consistent with what is done for string variables.

User-defined errors raised by the database no longer display an error help portal URL.

Fixed potential cursor issues when using Database Resident Connection Pooling (DRCP) .

Fixed regression when using IAM token authentication ( issue 288 ).

Fixed bug connecting to databases that are only mounted and not opened ( issue 294 ).

Fixed bug in identifying bind variables in SQL statements containing a single line comment at the end of the statement.

Fixed bug in determining the list of attributes for PL/SQL collections.

Fixed bug in calculating the Connection.thin attribute.

Fixed type declaration for the connectiontype parameter to oracledb.create_pool_async() and the return value of AsyncConnectionPool.acquire() .

Thick Mode Changes 

Added support for internal use of JSON in SODA with Oracle Client version 23. This allows for seamless transfer of extended data types.

Fixed bug when calling SodaDocument.getContent() for SODA documents that do not contain JSON.

Corrected support for Oracle Sharding.

Errors DPY-4011: the database or network closed the connection and DPY-4024: call timeout of {timeout} ms exceeded now retain the original error message raised by the Oracle Client library.

Common Changes 

Added a boolean property FetchInfo.is_oson which is set when a column has the check constraint IS JSON FORMAT OSON enabled.

Added methods Connection.decode_oson() and Connection.encode_oson() to support fetching and inserting into columns which have the check constraint IS JSON FORMAT OSON enabled.

Added class oracledb.JsonId to represent JSON ID values returned by SODA in Oracle Database 23.4 and later in the _id attribute of documents stored in native collections.

Added support for columns of type VECTOR usable with a limited availability release of Oracle Database version 23.

Errors raised when calling Cursor.executemany() with PL/SQL now have the oracledb._Error.offset attribute populated with the last iteration that succeeded ( issue 283 ).

A number of performance improvements were made.

Error DPY-2045: arraysize must be an integer greater than zero is now raised when an invalid value is used for the attribute Cursor.arraysize . Previously, a variety of errors ( TypeError , OverflowError or ORA-03147: missing mandatory TTC field ) were raised.

Error DPY-2016: variable array size of %d is too small (should be at least %d) is now raised when Cursor.executemany() is called with an integer number of iterations that is too large for the existing bind variables. Previously, python-oracledb Thin mode raised IndexError and python-oracledb Thick mode raised DPI-1018: array size of %d is too small .

Error DPY-1001: not connected to database is now raised when an attempt is made to perform an operation on a LOB using a closed connection. Previously, python-oracledb Thin mode raised an AttributeError exception and python-oracledb Thick mode raised DPI-1040: LOB was already closed .

Fixed bug in ConnectParams.get_connect_string() when a value for the connection parameter purity has been specified.

Fixed bug in ConnectParams.set() that would clear the ssl_context , appcontext , shardingkey and supershardingkey parameters if they were not included in the parameters. This also affected calls to oracledb.connect() and oracledb.create_pool() that made use of the DSN with credentials format.

The error DPY-2047: LOB amount must be greater than zero is now raised when the amount parameter in LOB.read() is set to zero or negative.

Fixed bug in the calculation of Cursor.rowcount under some circumstances.

Connection parameters that are strings now treat an empty string in the same way as the value None .

Thin Mode Changes 

Added support for using alternative event loop implementations such as uvloop with asyncio ( issue 276 ).

Added support for the asynchronous context manager protocol on the AsyncCursor class as a convenience.

Fixed regression when connecting to a database using listener redirects with either a connection pool or using asyncio ( issue 275 ).

Fixed bug when an intermittent hang occurs on some versions of Oracle Database while using asyncio and the database raises an error and output variables are present ( issue 278 ).

Fixed bug when fetch variables contain output converters and a query is re-executed ( issue 271 ).

Corrected typing declaration for oracledb.connect_async() .

Internal change to ensure that connection pools are closed gracefully when the main thread terminates.

Internal change to slightly improve performance of LOB reads and writes.

Common Changes 

Fixed regression which prevented a null value from being set on DbObject attributes or used as elements of collections ( issue 273 ).

Fixed regression from cx_Oracle which ignored the value of the encoding_errors parameter when creating variables by calling the method Cursor.var() ( issue 279 ).

Bumped minimum requirement of Cython to 3.0.

Thin Mode Changes 

Added support for concurrent programming with asyncio ( issue 6 ).

Added parameter ConnectParams.sdu for configuring the Session Data Unit (SDU) size for sizing internal buffers used for tuning communication with the database. The connection property Connection.sdu was also added.

Added parameter ConnectParams.ssl_context to modify the SSL context used when connecting via TLS ( issue 259 ).

Added support for an Oracle Database version 23 JSON feature allowing fieldnames with more than 255 UTF-8 encoded bytes.

Added support for the FAILOVER clause in full connect descriptors.

Fixed bug in detecting the current time zone ( issue 257 ).

Fixed bug in handling database response in certain unusual circumstances.

Fixed bug in handling exceptions raised during connection establishment.

Fixed bug in identifying bind variables in SQL statements containing multiple line comments with multiple asterisks before the closing slash.

A more meaningful error is raised when the wrong type of data is passed to LOB.write() .

Internal change to support an Oracle Database version 23 JSON feature improving JSON storage usage.

Internal change to ensure that all connections in a pool have been closed gracefully before the pool is closed.

Internal changes to improve handling of the network protocol between python-oracledb and Oracle Database.

Internal changes to improve handling of multiple address and description lists in full connect descriptors.

Thick Mode Changes 

Fixed bug in return value of SodaOperation.replaceOne() .

Common Changes 

Dropped support for Python 3.6.

Desupported a number of parameters and attributes that were previously deprecated. See desupport notices for details.

Added property Cursor.warning for database warnings (such as PL/SQL compilation warnings) generated by calls to Cursor.execute() or Cursor.executemany() .

Added property Connection.warning for warnings (such as the password being in the grace period) generated during connection.

Added properties that provide information about the database: Connection.db_domain , Connection.db_name , Connection.max_open_cursors , Connection.service_name and Connection.transaction_in_progress .

Added property Connection.proxy_user to show the name of the user which was used as a proxy when connecting ( issue 250 ).

Added properties FetchInfo.domain_schema , FetchInfo.domain_name and FetchInfo.annotations for the SQL domain and annotations associated with columns that are being fetched. SQL domains and annotations require Oracle Database version 23, or later. If using python-oracledb Thick mode, Oracle Client version 23, or later, is also required.

Added parameter data to Connection.createlob() to allow data to be written at LOB creation time.

Added type DB_TYPE_XMLTYPE to represent data of type SYS.XMLTYPE in the database. Previously the value of FetchInfo.type_code for data of this type was DB_TYPE_LONG in Thick mode and DB_TYPE_OBJECT in Thin mode.

Attribute and element values of Oracle Object instances that contain strings or bytes now have their maximum size constraints checked. Errors DPY-2043 (attributes) and DPY-2044 (element values) are now raised when constraints are violated.

Attribute and element values of Oracle Object instances that are numbers are now returned as integers if the precision and scale allow for it. This is the same way that numbers are fetched from the database ( issue 99 ).

Errors that have entries in the troubleshooting documentation now have links to that documentation shown in the message text.

Fixed bug with binding boolean values with Oracle Database version 23 ( issue 263 ).

Fixed bug with getting unknown attributes from Oracle Object instances.

Error DPY-4029: errors in array DML exceed 65535 is now raised when the number of batch errors exceeds 65535 when calling Cursor.executemany() with the parameter batcherrors set to the value True . Note that in Thick mode this error is not raised unless the number of batch errors is a multiple of 65536; instead, the number of batch errors returned is modulo 65536 ( issue 262 ).

Black is now used to format Python code and ruff to lint Python code.

Thick Changes 

Fixed bug resulting in a segfault on some platforms when using two-phase commit.

Common Changes 

Pre-built binaries are now being created for Python 3.12 ( issue 237 ).

Thin Mode Changes 

Improved statement bind variable placeholder parser performance, handle statements which use the Alternative Quoting Mechanism (‘Q’ strings), and fix some issues identifying bind variable placeholders in embedded quotes and in JSON syntax.

Thick Changes 

Fixed error checking when getting or setting the connection pool parameters ping_interval and soda_metadata_cache .

Common Changes 

Fixed bug when calling Cursor.execute() or Cursor.executemany() with missing bind data after calling Cursor.setinputsizes() with at least one of the values supplied as None ( issue 217 ).

SQL statement parsing now raises DPY-2041: missing ending quote (') in string or DPY-2042: missing ending quote (") in identifier for statements with the noted invalid syntax. Previously, Thick mode gave ORA-1756 or ORA-1740 , respectively, while Thin mode did not throw an error.

Added missing “>” to repr() of SodaDatabase Class .

Thin Mode Changes 

Added support for an Oracle Database version 23 feature that can improve the performance of connection creation by reducing the number of round trips required to create the second and subsequent connections to the same database.

Added support for shrinking the connection pool back to the specified minimum size when the pool is idle for ConnectionPool.timeout seconds.

Added support for growing the connection pool back to the minimum number of connections after connections are killed or otherwise made unusable.

A default connection class is now generated when DRCP is used with a connection pool and no connection class was specified when the pool was created. The default connection class will be of the form DPY: followed by a 16-byte unique identifier converted to base64 encoding.

Changed internal connection feature negotiation for more accurate Oracle Database version 23 support.

Added support for sending a generated connection identifier to the database used for tracing. An application specific prefix is prepended to this value if specified via a new connection_id_prefix parameter when creating standalone connections or connection pools.

Added URL to the Oracle Database Error Help Portal in Oracle Database error messages similar to when Thick mode uses Oracle Client version 23.

Added support for the ORA_SDTZ environment variable used to set the session time zone used by the database.

Fixed bug when a dynamically sized connection pool is created with an increment of zero and the pool needs to grow.

Fixed bug affecting connection reuse when connections were acquired from the connection pool with a cclass different to the one used to create the pool.

Fixed bug when a connection is discarded from the connection pool during ConnectionPool.acquire() and the ping check fails due to the connection being dead.

Fixed bug when an output type handler is used and the value of Cursor.prefetchrows exceeds Cursor.arraysize ( issue 173 ).

Fixed bug when an Application Continuity replay context is returned during connection to the database ( issue 176 ).

Fixed bug when socket is not closed immediately upon failure to establish a connection to the database ( issue 211 ).

Thick Mode Changes 

Added function SodaCollection.listIndexes() for getting the indexes on a SODA collection.

Added support for specifying if documents should be locked when fetched from SODA collections. A new non-terminal method lock() was added which requires Oracle Client 21.3 or higher (or Oracle Client 19 from 19.11).

Relaxed restriction for end-to-end tracing string connection attributes. These values can now be set to the value None which will be treated the same as an empty string.

Fixed bug when using external authentication with an Easy Connect connection string.

Fixed memory leak when accessing objects embedded within other objects.

Common Changes 

Use of Python 3.6 and 3.7 is deprecated and support for them will be removed in a future release. A warning is issued when these versions are used but otherwise they will continue to function as usual. The warning can be suppressed by importing warnings and adding a call like warnings.filterwarnings(action='ignore', module="oracledb") before importing oracledb .

Added support for the Variable.outconverter being called when a null value is fetched from the database and the new parameter convert_nulls to the method Cursor.var() is passed the value True ( issue 107 ).

Replaced fixed 7-tuple for the cursor metadata found in Cursor.description with a class which provides additional information such as the database object type and whether the column contains JSON data.

Changed the signature for output type handlers to handler(cursor, metadata) where the metadata parameter is a FetchInfo object containing the same information found in Cursor.description . The original signature for output type handlers is deprecated and will be removed in a future version.

Added support for fetching VARCHAR2 and LOB columns which contain JSON (and have the “IS JSON” check constraint enabled) in the same way as columns of type JSON (which requires Oracle Database 21c or higher) are fetched. In Thick mode this requires Oracle Client 19c or higher. The attribute oracledb.future.old_json_col_as_obj must be set to the value True for this behavior to occur. In version 2.0 this will become the normal behavior and setting this attribute will no longer be needed.

Added new property Connection.instance_name which provides the Oracle Database instance name associated with the connection. This is the same value as the SQL expression sys_context('userenv', 'instance_name') .

Added support for relational queries on the underlying tables of SODA collections created in Oracle Database version 23 if they contain JSON documents with embedded OIDs.

Automatically retry a query if the error ORA-00932: inconsistent data types is raised (which can occur if a table or view is recreated with a data type that is incompatible with the column’s previous data type).

The repr() value of the DbObject class now shows the string “DbObject” instead of the string “Object” for consistency with the name of the class and the other repr() values for DbObjectType and DbObjectAttr.

Fixed bug when binding sequences other than lists and tuples ( issue 205 ).

Added support for using the Cython 3.0 release ( issue 204 ).

Improved test suite and documentation.

Thin Mode Changes 

Fixed bug using Cursor.arraysize for tuning data fetches from REF CURSORS.

Fixed bug connecting to databases with older 11g password verifiers ( issue 189 ).

Fixed bugs in the implementation of the statement cache.

Fixed bug which caused a cursor leak if an error was thrown while processing the execution of a query.

Eliminated unneeded round trip when using token authentication to connect to the database.

Fixed bug which could cause a redirect loop with improperly configured listener redirects.

Fixed bug when executing PL/SQL with a large number of binds.

Fixed bug when using DRCP with Oracle Database version 23

Thick Mode Changes 

Fixed bug when using external authentication with a Net Service Name connection string ( issue 178 ).

Fixed bug when using external authentication with an Easy Connect connection string.

Common Changes 

When fetching rows from REF CURSORS, the cursor’s prefetchrows attribute is now ignored. Use Cursor.arraysize for tuning these fetches. This change allows consistency between Thin and Thick modes.

Thin Mode Changes 

Improved performance of regular expressions used for parsing SQL ( issue 172 ).

Fixed bug with Oracle Database version 23 when SQL is executed after first being parsed.

Fixed bug when ConnectionPool.timeout is not None when creating a connection pool ( issue 166 ).

Fixed bug when a query is re-executed after an underlying table is dropped and recreated, and the query select list contains LOBs or JSON data.

Fixed bug when warning message such as for impending password expiry is encountered during connect ( issue 171 ).

Common Changes 

Improved test suite and samples.

Thin Mode Changes 

Added direct support for the Oracle Database 21c JSON data type, removing the need to use an output type handler.

Added implementation for ConnectionPool.timeout to allow pools to shrink to min connections.

Added check to prevent adding too many elements to bounded database collections.

Removed internally set fixed size for database collections. Collections of any size supported by the database can now be created.

Added support for connecting to databases that accept passwords longer than 30 UTF-8 encoded bytes.

Detect the time zone on the OS and set the session timezone using this value to be consistent with Thick mode ( issue 144 ).

Improved BOOLEAN handling.

Error DPY-6005: cannot connect to database is now raised for all failures to connect to the database and the phrase cannot connect to database is removed from all other error messages (since this can be confusing when these errors are raised from ConnectParams.parse_connect_string() ).

Fixed bug when calling Cursor.executemany() with PL/SQL when the size of the bound data increases on subsequent calls ( issue 132 ).

Fixed bug when binding data of type TIMESTAMP WITH TIME ZONE but with zero fractional seconds.

Fixed bug with incorrect values of Cursor.rowcount when fetching data ( issue 147 ).

Fixed bug with SQL containing multibyte characters with certain database character sets ( issue 133 ).

Fixed bug with ordering of binds in SQL when the database version is 12.1 ( issue 135 ).

Fixed bug with ordering of binds in PL/SQL when the bind variable may potentially exceed the 32767 byte limit but the actual value bound does not ( issue 146 ).

Fixed bug connecting to an IPv6 address with IAM tokens.

Fixed bug determining RETURNING binds in a SQL statement when RETURNING and INTO keywords are not separated by whitespace, but are separated by parentheses.

The exception DPY-3022: named time zones are not supported in thin mode is now raised when attempting to fetch data of type TIMESTAMP WITH TIME ZONE when the time zone associated with the data is a named time zone. Previously invalid data was returned ( disc 131 ).

Internal implementation changes:

Added internal support for prefetching the LOB size and chunk size, thereby eliminating a round-trip when calling LOB.size() and LOB.getchunksize() .

Made the pool implementation LIFO to improve locality, reduce the number of times any session callback must be invoked, and allow connections to be timed out.

Removed packet for negotiating network services which are not supported in Thin mode.

Removed unneeded packet for changing the password of the connected user.

Thick Mode Changes 

Raise a more meaningful error when an unsupported type in a JSON value is detected.

Added support for the “signed int”, “signed long” and “decimal128” scalar types in JSON (generally only seen when converting from MongoDB).

Defer raising an exception when calling Connection.gettype() for a type containing an attribute or element with an unsupported data type until the first attempt to reference the attribute or element with the unsupported data type.

Fixed bug when attempting to create bequeath connections when the DSN contains credentials.

Common Changes 

Improved type annotations.

Added method ConnectParams.parse_dsn_with_credentials() for parsing a DSN that contains credentials.

Error DPY-2038: element at index {index} does not exist is now raised whenever an element in a database collection is missing. Previously, Thick mode raised DPI-1024: element at index {index} does not exist and Thin mode raised KeyError or IndexError .

Error DPY-2039: given index {index} must be in the range of {min_index} to {max_index} is now raised whenever an element in a database collection is set outside the bounds of the collection. Previously, Thick mode raised OCI-22165: given index [{index}] must be in the range of [{min_index}] to [{max_index}] and Thin mode raised IndexError .

Error DPY-2040: parameters "batcherrors" and "arraydmlrowcounts" may only be true when used with insert, update, delete and merge statements is now raised when either of the parameters batcherrors and arraydmlrowcounts is set to the value True when calling Cursor.executemany() . Previously, Thick mode raised DPI-1063: modes DPI_MODE_EXEC_BATCH_ERRORS and DPI_MODE_EXEC_ARRAY_DML_ROWCOUNTS can only be used with insert, update, delete and merge statements and Thin mode raised ORA-03137: malformed TTC packet from client rejected ( issue 128 ).

Internal changes to ensure that errors taking place while raising exceptions are handled more gracefully.

Thin Mode Changes 

Any exception raised while finding the operating system user for database logging is now ignored ( issue 112 ).

Fixed bug when binding OUT a NULL boolean value. ( issue 119 ).

Fixed bug when getting a record type based on a table (%ROWTYPE) ( issue 123 ).

Fixed bug when using a select * from table query and columns are added to the table ( issue 125 ).

Thick Mode Changes 

Fixed bug when attempting to create bequeath connections to a local database ( issue 114 ).

Common Changes 

Fixed bug when attempting to populate an array variable with too many elements.

Thin Mode Changes 

Fixed bug determining RETURNING binds in a SQL statement when RETURNING and INTO keywords are not separated by spaces, but are separated by other whitespace characters ( issue 104 ).

Fixed bug determining bind variables when found between two comment blocks ( issue 105 ).

Thick Mode Changes 

Fixed bug creating a homogeneous connection pool with a proxy user ( issue 101 ).

Fixed bug closing a SODA document cursor explicitly (instead of simply allowing it to be closed automatically when it goes out of scope).

Fixed bug when calling Subscription.registerquery() with bind values.

Fixed bug that caused Message.dbname to always be the value None .

Common Changes 

Corrected repr() of connections to include the actual class name instead of a hard-coded oracledb .

Thin Mode Changes 

Added support for binding and fetching data of type DB_TYPE_OBJECT . Note that some of the error codes and messages have changed as a result: DPY errors are raised instead of ones specific to ODPI-C and OCI ( issue 43 ).

Added support for fetching SYS.XMLTYPE data as strings. Note that unlike in Thick mode, fetching longer values does not require using XMLTYPE.GETCLOBVAL() .

Added support for using a wallet for one-way TLS connections, rather than requiring OS recognition of certificates ( issue 65 ).

Added support for connecting to CMAN using (SOURCE_ROUTE=YES) in the connect string ( issue 81 ).

Fixed bug when fetching nested cursors with more columns than the parent cursor.

Fixed bug preventing a cursor from being reused after it was bound as a REF CURSOR to a PL/SQL block that closes it.

Fixed bug preventing binding OUT data of type DB_TYPE_UROWID that exceeds 3950 bytes in length.

Fixed bug preventing correct parsing of connect descriptors with both ADDRESS and ADDRESS_LIST components at the same level.

The complete connect string is now sent to the server instead of just the actual components being used. This is important for some configurations.

Fixed bug resulting in an internal protocol error when handling database responses.

Fixed bug when calling Cursor.executemany() with the batcherrors parameter set to True multiple times with each call resulting in at least one batch error.

Thick Mode Changes 

Connections acquired from a homogeneous pool now show the username and dsn to which they are connected in their repr().

Common Changes 

Added support for Python 3.11.

Added attribute DbObjectType.package_name which contains the name of the package if the type is a PL/SQL type (otherwise, it will be None ).

Added sample for loading data from a CSV file.

Improved test suite and documentation.

Thin Mode Changes 

Fixed bug that prevented binding data of types DB_TYPE_ROWID and DB_TYPE_UROWID .

Fixed bug that caused Connection.is_healthy() to return True after a connection has been killed.

Internally, before a connection is returned from a pool, perform additional checks in order to avoid returning a dead connection from the pool.

Thick Mode Changes 

Fixed bug returning metadata of SODA documents inserted into a collection using SodaCollection.saveAndGet() .

Common Changes 

Fixed type checking errors ( issue 52 ).

Enhanced type checking ( issue 54 ), ( issue 60 ).

The mode of python-oracledb is now fixed only after a call to oracledb.init_oracle_client() , oracledb.connect() or oracledb.create_pool() has completed successfully ( issue 44 ).

Improved test suite and documentation.

Thin Mode Changes 

Added support for getting the LOB chunk size ( issue 14 ).

The error DPY-2030: LOB offset must be greater than zero is now raised when the offset parameter to LOB.read() is zero or negative ( issue 13 ).

Internally, before a connection is returned from a pool, check for control packets from the server (which may inform the client that the connection needs to be closed and a new one established).

Internally make use of the TCP_NODELAY socket option to remove delays in socket reads.

Fixed bug when calling Cursor.parse() multiple times with the same SQL statement.

Fixed bug that prevented connecting to Oracle Database 12.1.0.1.

Fixed bug that prevented the database error message from being returned when connecting to a database that the listener configuration file states exists but actually doesn’t ( issue 51 ).

The error DPY-3016: python-oracledb thin mode cannot be used because the cryptography package is not installed is now raised when the cryptography package is not installed, instead of an ImportError. This allows platforms that are not capable of building the cryptography package to still use Thick mode.

Fixed bug that prevented the full_code attribute from being populated on the errors returned by Cursor.getbatcherrors() .

Thick Mode Changes 

Added support for getting the message id of the AQ message which generated a notification.

Added support for enqueuing and dequeing AQ messages as JSON.

Added the ability to use externalauth as a connection parameter for standalone connections in addition to creating pools. For standalone connections, this parameter is optional.

Common Changes 

Added support for Azure Active Directory OAuth 2.0 and Oracle Cloud Infrastructure Identity and Access Management (IAM) token authentication via the new parameter access_token to oracledb.connect() and oracledb.create_pool() .

Added method oracledb.is_thin_mode() to support determining whether the driver is using Thin mode or not ( issue 16 ).

Improved samples and documentation.

Thin Mode Changes 

The error DPY-3015: password verifier type is not supported by python-oracledb in thin mode is now raised when the database sends a password challenge with a verifier type that is not recognized, instead of ORA-01017: invalid username/password ( issue 26 ).

Fixed bug with handling of redirect data returned by some SCAN listeners ( issue 39 ).

Fixed bug with re-execution of SQL that requires a define, such as occurs when setting oracledb.defaults.fetch_lobs to the value False ( issue 41 ).

Fixed bug that prevented cursors from implicit results sets from being closed.

Common Changes 

Fixed bug with the deferral of type assignment when creating variables for Cursor.executemany() ( issue 35 ).

Thin Mode Changes 

Connecting to a database with national character set UTF8 is now supported; an error is now raised only when the first attempt to use NCHAR, NVARCHAR2 or NCLOB data is made ( issue 16 ).

Fixed a bug when calling cursor.executemany() with a PL/SQL statement and a single row of data ( issue 30 ).

When using the connection parameter https_proxy while using protocol tcp , a more meaningful exception is now raised: DPY-2029: https_proxy requires use of the tcps protocol .

Fixed a bug that caused TLS renegotiation to be skipped in some configurations, thereby causing the connection to fail to be established ( https://github.com/oracle/python-oracledb/discussions/34 ).

Thick Mode Changes 

Fixed the ability to use external authentication with connection pools.

Common Changes 

The compiler flag -arch x86_64 no longer needs to be explicitly specified when building from source code on macOS (Intel x86) without Universal Python binaries.

Binary packages have been added for the Linux ARM 64-bit platform.

Improved samples and documentation.

Thin Mode Changes 

Added support for multiple aliases in one entry in tnsnames.ora ( issue 3 ).

Fixed connection retry count handling to work in cases where the database listener is running but the service is down ( issue 3 ).

Return the same value for TIMESTAMP WITH TIME ZONE columns as Thick mode ( issue 7 ).

Fixed order in which bind data is sent to the server when LONG and non-LONG column data is interspersed ( issue 12 ).

If an error occurs during the creation of a connection to the database, the error is wrapped by DPY-6005 (so that it can be caught with an exception handler on class oracledb.DatabaseError).

Ensured that errors occurring during fetch are detected consistently.

Fixed issue when fetching null values in implicit results.

Small performance optimization when sending column metadata.

Thick Mode Changes 

Fixed the ability to create bequeath connections to a local database.

Fixed issue fetching NCLOB columns with oracledb.defaults.fetch_lobs = False .

Common Changes 

Fixed issue where unconstrained numbers containing integer values would be fetched as floats when oracledb.defaults.fetch_lobs = False . ( issue 15 ).

Ensured connection error messages contain the function name instead of wrapped() .

Improved samples, including adding a Dockerfile that starts a container with a running database and the samples.

A binary package has been added for Python 3.7 on macOS (Intel x86).

Improved documentation.

Renamed cx_Oracle to python-oracledb. See Upgrading from cx_Oracle 8.3 to python-oracledb .

Python-oracledb is a ‘Thin’ driver by default that connects directly to Oracle Database. Optional use of Oracle Client libraries enables a ‘Thick’ mode with some additional functionality. Both modes support the Python Database API v2.0 Specification.

Added a Connection.thin attribute which shows whether the connection was established in python-oracledb Thin mode or Thick mode.

Creating connections or connection pools now requires keyword parameters be passed. This brings python-oracledb into compliance with the Python Database API specification PEP 249.

Threaded mode is now always enabled for standalone connections (Thick mode).

The function oracledb.init_oracle_client() must now always be called to load Oracle Client libraries, which enables Thick mode.

Allow oracledb.init_oracle_client() to be called multiple times in each process as long as the same parameters are used each time.

Improved some connection and binding error messages (Thin mode only).

Added oracledb.defaults containing attributes that can be used to adjust the default behavior of the python-oracledb driver. In particular oracledb.defaults.fetch_lobs obsoletes the need for a LOB type handler .

Added a ConnectParams Class which provides the ability to define connection parameters in one place.

Added a PoolParams Class which provides the ability to define pool parameters in one place.

Added a ConnectionPool Class which is equivalent to the SessionPool class previously used in cx_Oracle. The new oracledb.create_pool() function is now the preferred method for creating connection pools.

Changed the default oracledb.create_pool() getmode parameter value to POOL_GETMODE_WAIT to remove potential transient errors when calling ConnectionPool.acquire() during pool growth.

Connection pools in python-oracledb Thin mode support all connection mode privileges .

Added new Two-phase commit functionality.

Added Connection.is_healthy() to do a local check of a connection’s health.

Added a boolean parameter cache_statement to Cursor.prepare() , giving applications control over statement caching.

Made improvements to statement cache invalidation (Thin mode only)

Added a MessageProperties.recipient attribute to support recipient lists in Oracle Advanced Queuing .

Added a full_code attribute to the Error object giving the top-level error prefix and the error number.

Added a DB_TYPE_LONG_NVARCHAR constant.