How to use `Connection.ping()`

[truh]

1. What is the link to the documentation section that needs improving?

https://cx-oracle.readthedocs.io/en/latest/api_manual/connection.html?highlight=ping#Connection.ping

2. Describe the confusion

The function doesn't appear to have a return value? How can I use it to check if the connection is still alive? Is an exception raised it the connection is dead?

3. Suggest changes that would help

Please provide additional information about the return and raise value of the function.

Please provide a usage example.

[cjbj]

Yep, we should improve the doc.

Try this:

import cx_Oracle
import os
import platform

if platform.system() == "Darwin":
    cx_Oracle.init_oracle_client(lib_dir=os.environ.get("HOME")+"/Downloads/instantclient_19_8")

username = os.environ.get("PYTHON_USERNAME")
password = os.environ.get("PYTHON_PASSWORD")
connect_string = os.environ.get("PYTHON_CONNECTSTRING")

sql = """select unique 'alter system kill session '''||sid||','||serial#||'''' from v$session_connect_info where sid = sys_context('USERENV', 'SID')"""

connection = cx_Oracle.connect(user=username, password=password, dsn=connect_string)
killsql, = connection.cursor().execute(sql).fetchone()

systemconnection = cx_Oracle.connect(user='system', password='whatever', dsn=connect_string)
systemconnection.cursor().execute(killsql)

try:
    connection.ping()

except cx_Oracle.Error as e:
    error, = e.args
    print(error.message)

This gives me:

DPI-1080: connection was closed by ORA-28

[truh]

Thank you, that has been very helpful.

[cjbj]

I have updated the python-oracledb documentation to note that ping() throws an exception.