The leading edge of scripting languages and Oracle Database brought to you by the Data Access Development team

Python cx_Oracle 8.2 allows connection pool reconfiguration at runtime

Christopher Jones
Senior Principal Product Manager

cx_Oracle logo


cx_Oracle 8.2, the extremely popular Oracle Database interface for Python, is now production on PyPI.

cx_Oracle is an open source package for the Python Database API specification with many additions to support advanced Oracle Database features.

This release introduces useful changes, many around connection handling. For all changes see the release notes.


  • Added a new pool function reconfigure() to allow options such as the maximum pool size to be changed without pausing the application. This can be useful for applications that must remain running, but where the user load has changed (or will change), such as during a peak shopping period.

  • Added a connection pool creation option ping_interval. This specifies the time interval that a pooled connection must have been idle in the connection pool before pool.acquire() initiates an internal round-trip connection check prior to returning that connection back to the app. The ping happens if the connection about to be returned has been idle in the pool for the specified time - in previous cx_Oracle releases a fixed interval of 60 seconds was used. The ping checks that the firewall didn't drop the connection, that a DBA hasn't killed the session thinking it was unused, etc. A different connection is returned from acquire() if necessary. The same configurable ping interval feature is available in Oracle APIs for other languages, so this change just brings cx_Oracle in line. You probably won't ever need to change the default value, but if you need to, then now you can.

  • When creating connection pools, threaded mode is now always enabled. This is necessary for the underlying session pool technology used by cx_Oracle.

  • Connections and connection pools can now set the statement cache size at time of creation. This lets you more easily tune applications.

  • Improved dead connection detection handling. As well as tweaking cx_Oracle to improve where and when dead connections are checked for, now if an Oracle Database error indicates that a connection is no longer usable, the error DPI-1080: connection was closed by ORA-%d is returned to the app. The "%d" will be the Oracle error that caused the connection to be closed. Using the connection after this will give DPI-1010: not connected. The DPI-1080 message is also returned for Connection.call_timeout errors that result in an unusable connection.

  • A few SODA enhancements were made, notably the ability for pooled connections to use a metadata cache. This much requested change can significantly improve performance when repeatedly opening collections.

  • Added a parameter bypass_decode to Cursor.var() to bypass the decode step when converting data from Oracle Database into Python strings. This option should only be used for troubleshooting and correcting invalid data. Many thanks to Darko Djolovic for the initial GitHub PR for this feature. I love PR creators who write documentation.

  • You may notice that a number of function parameter names were 'changed'. Of course the old names still work. The changes were due to a desire for better compliance with the PEP 8 style guide to give your Python code a more consistent look.

    We are also nudging people to use UTF-8 encodings. In some future release, when we make UTF-8 the only Oracle client character set supported, cx_Oracle will be able to make use of more efficient Python code paths.

Installing or Upgrading cx_Oracle

You can install or upgrade cx_Oracle by running:

python -m pip install cx_Oracle --upgrade

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

cx_Oracle References

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

Installation instructions: cx-oracle.readthedocs.io/en/latest/installation.html

Documentation: cx-oracle.readthedocs.io/en/latest/index.html

Release Notes: cx-oracle.readthedocs.io/en/latest/release_notes.html

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

Facebook group: www.facebook.com/groups/oraclescripting/

Questions: github.com/oracle/python-cx_Oracle/issues

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.