python-oracledb 2.3 Has Been Released

python-oracledb 2.3, the extremely popular Oracle Database interface for Python, is now on PyPI.

Photo by Andrew Seaman on Unsplash

python-oracledb is the Python driver for Oracle Database and Oracle’s most popular open-source driver, a renamed upgrade of the cx_Oracle 8.3 driver.

To get started quickly, use samples/sample_container to create a container image containing the database and python-oracledb.

Main Changes in python-oracledb 2.3

Two-phase Commits Support

In distributed transaction processing involving altering data on multiple databases, the two-phase commit mechanism ensures that the entire transaction commits, or the entire transaction rolls back. The commitment of a distributed transaction is split in two distinct phases:

1. Prepare phase — during which each participat agrees or consents to commit their portion of the transaction.
2. Commit phase — all of the participants that indicated they needed to be committed are asked to either commit their prepared changes or roll them back.

python-oracledb Thin mode now supports two-phase commits. Functions tpc_begin() and tpc_end() support distributed transactions. Connection.tpc_begin() can be used to start a TPC transaction. The method Connection.tpc_prepare() can be used to prepare a global transaction for commit. The methods Connection.tpc_commit() and Connection.tpc_rollback() can be used to commit or rollback a transaction respectively.

Read more about the two-phase commits and check the sample code in Python.

Support for BFILE Data Type

In Thin mode, the driver now supports data type BFILE.

Support for Oracle Database 23ai BINARY Vector Format

In both Thin and Thick modes, python-oracledb 2.3 supports BINARY vector format.

Enhancements to pool APIs

To limit 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, ping_timeout parameter has been added to methods oracledb.create_pool() and oracledb.create_pool_async(). The default value of ping_timeoutis 5000 miliseconds. Prior to this change, Thick mode was using a fixed timeout of 5000 milliseconds and no explicit timeout was used in Thin mode.

Improved Connections to the Oracle Database

Connection requests to the Oracle Database will not be additionally delayed by internal network ping to the database due to improvements made to the connection pool mode oracledb.POOL_GETMODE_TIMEDWAIT, which honors the wait_timeout value.

New Enumerations to Replace integer Constants

In order to provide a more useful repr() and improve type safety new enumerations are now replacing integer constants for connection authorization modes, connection pool get modes, connection pool purity constants and vector format constants.

Other notable changes implemented in the 2.3 release:

• 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.
• Parameter ssl_version has been added 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”
• Optional compilation arguments were added when building python-oracledb. To change the compilation arguments, use variable PYO_COMPILE_ARGS before building. For example, to build stripped binaries on Linux, first set:

export PYO_COMPILE_ARGS='-g0'

• Improved detection of the signature used by output type handlers.
• Smaller binaries for Linux. Read more about this on Christopher Jones’s blogpost.

See the python-oracledb Release Notes for more improvements and bug fixes.

Installing or Upgrading python-oracledb

You can install or upgrade python-oracledb by running:

python -m pip install oracledb --upgrade

The pip options--proxy and --user may be useful in some environments. See python-oracledb Installation for details.

python-oracledb References

Home page: oracle.github.io/python-oracledb/index.html

Installation instructions: python-oracledb.readthedocs.io/en/latest/installation.html

Documentation: python-oracledb.readthedocs.io/en/latest/index.html

Release Notes: python-oracledb.readthedocs.io/en/latest/release_notes.html

Discussions: github.com/oracle/python-oracledb/discussions

Issues: github.com/oracle/python-oracledb/issues

Source Code Repository: github.com/oracle/python-oracledb