Fixed retry count handling to work in cases where the listener is

running but the service is down; added new exception class
oracledb.ConnectionError in order to aid the handling of connection
errors during creation or use (where the connection is no longer usable
or could not be established). This addresses issue #3.

Author: anthony-tuininga

doc/src/release_notes.rst

@@ -16,6 +16,16 @@ oracledb 1.0.1 (TBD)
     (`issue 3 <https://github.com/oracle/python-oracledb/issues/3>`__).
 #)  Ensured the name of wrapped functions are the same as the function being
     wrapped in order to improve error messages that reference them.
+#)  Added exception class (oracledb.ConnectionError) as a subclass of
+    oracledb.DatabaseError in order to aid the handling of connection errors
+    during creation or use (where the connection is no longer usable or could
+    not be established).
+#)  Thin: fixed retry count handling to work in cases where the listener is
+    running but the service is down
+    (`issue 3 <https://github.com/oracle/python-oracledb/issues/3>`__).
+#)  Thin: if an OS error occurs during the creation of a connection to the
+    database, the error is wrapped by DPY-6005 as an instance of
+    oracledb.ConnectionError.
 
 
 oracledb 1.0.0 (May 2022)

src/oracledb/errors.py

@@ -68,7 +68,7 @@ def __init__(self, message: str=None, context: str=None,
                     args = re.search(pattern, message).groupdict()
                 else:
                     driver_error_num = driver_error_info
-                if driver_error_num == ERR_CONNECTION_CLOSED:
+                if driver_error_num in ERR_CONNECTION_ERROR_SET:
                     self.is_session_dead = True
                 driver_error = _get_error_text(driver_error_num, **args)
                 self.message = f"{driver_error}\n{self.message}"
@@ -99,7 +99,10 @@ def _raise_err(error_num: int, context_error_message: str=None,
     message = _get_error_text(error_num, **args)
     if context_error_message is not None:
         message = f"{message}\n{context_error_message}"
-    exc_type = ERR_EXCEPTION_TYPES[error_num // 1000]
+    if error_num in ERR_CONNECTION_ERROR_SET:
+        exc_type = exceptions.ConnectionError
+    else:
+        exc_type = ERR_EXCEPTION_TYPES[error_num // 1000]
     raise exc_type(_Error(message)) from cause
 
 
@@ -205,13 +208,15 @@ def _raise_from_string(exc_type: Exception, message: str) -> None:
 ERR_INTEGER_TOO_LARGE = 5002
 ERR_UNEXPECTED_NEGATIVE_INTEGER = 5003
 ERR_UNEXPECTED_DATA = 5004
+ERR_UNEXPECTED_REFUSE = 5005
 
 # error numbers that result in OperationalError
 ERR_LISTENER_REFUSED_CONNECTION = 6000
 ERR_INVALID_SERVICE_NAME = 6001
 ERR_INVALID_SERVER_CERT_DN = 6002
 ERR_INVALID_SID = 6003
 ERR_PROXY_FAILURE = 6004
+ERR_CONNECTION_FAILED = 6005
 
 # Oracle error number cross reference
 ERR_ORACLE_ERROR_XREF = {
@@ -234,6 +239,15 @@ def _raise_from_string(exc_type: Exception, message: str) -> None:
     1080: ERR_CONNECTION_CLOSED,
 }
 
+# dead connection errors
+ERR_CONNECTION_ERROR_SET = set([
+    ERR_CONNECTION_CLOSED,
+    ERR_CONNECTION_FAILED,
+    ERR_INVALID_SERVICE_NAME,
+    ERR_INVALID_SID,
+    ERR_LISTENER_REFUSED_CONNECTION
+])
+
 # error message exception types (multiples of 1000)
 ERR_EXCEPTION_TYPES = {
     1: exceptions.InterfaceError,
@@ -264,6 +278,8 @@ def _raise_from_string(exc_type: Exception, message: str) -> None:
     ERR_COLUMN_TRUNCATED:
             'column truncated to {col_value_len} {unit}. '
             'Untruncated was {actual_len}',
+    ERR_CONNECTION_FAILED:
+            'cannot connect to database. Connection failed with "{exception}"',
     ERR_CONTENT_INVALID_AFTER_NUMBER:
             'invalid number (content after number)',
     ERR_CURSOR_NOT_OPEN:
@@ -417,6 +433,9 @@ def _raise_from_string(exc_type: Exception, message: str) -> None:
     ERR_UNEXPECTED_NEGATIVE_INTEGER:
             'internal error: read a negative integer when expecting a '
             'positive integer',
+    ERR_UNEXPECTED_REFUSE:
+            'the listener refused the connection but an unexpected error '
+            'format was returned',
     ERR_UNSUPPORTED_INBAND_NOTIFICATION:
             'unsupported in-band notification with error number {err_num}',
     ERR_UNSUPPORTED_PYTHON_TYPE_FOR_VAR:

src/oracledb/exceptions.py

@@ -25,7 +25,10 @@
 #------------------------------------------------------------------------------
 # exceptions.py
 #
-# Contains the exception classes mandated by the Python Database API.
+# Contains the exception classes mandated by the Python Database API and one
+# additional one (ConnectionError) for aiding in the handling of connection
+# failures when the connection is being created or used (and the connection is
+# no longer usable).
 #------------------------------------------------------------------------------
 
 class Warning(Exception):
@@ -40,6 +43,10 @@ class DatabaseError(Error):
     pass
 
 
+class ConnectionError(DatabaseError):
+    pass
+
+
 class DataError(DatabaseError):
     pass
 

src/oracledb/impl/thin/connection.pyx

@@ -81,10 +81,12 @@ cdef class ThinConnImpl(BaseConnImpl):
             elif stmt._cursor_id != 0:
                 self._add_cursor_to_close(stmt)
 
-    cdef object _connect_with_description(self, Description description):
+    cdef object _connect_with_description(self, Description description,
+                                          ConnectParamsImpl params,
+                                          bint final_desc):
         cdef:
-            double timeout = description.tcp_connect_timeout
-            bint load_balance = description.load_balance, raise_exc
+            bint load_balance = description.load_balance
+            bint raise_exc = False
             list address_lists = description.address_lists
             uint32_t i, j, k, num_addresses, idx1, idx2
             uint32_t num_attempts = description.retry_count + 1
@@ -116,13 +118,19 @@ cdef class ThinConnImpl(BaseConnImpl):
                     else:
                         idx2 = k
                     address = address_list.addresses[idx2]
-                    raise_exc = i == num_attempts - 1
-                    sock = self._get_socket(address, timeout, raise_exc)
-                    if sock is None:
+                    if final_desc:
+                        raise_exc = i == num_attempts - 1
+                    redirect_params = self._connect_with_address(address,
+                                                                 description,
+                                                                 params,
+                                                                 raise_exc)
+                    if redirect_params is not None:
+                        return redirect_params
+                    if self._protocol._in_connect:
                         continue
                     address_list.lru_index = (idx1 + 1) % num_addresses
                     description.lru_index = (idx2 + 1) % num_lists
-                    return (sock, address)
+                    return
             time.sleep(description.retry_delay)
 
     cdef ConnectParamsImpl _connect_with_params(self,
@@ -137,36 +145,23 @@ cdef class ThinConnImpl(BaseConnImpl):
             list descriptions = description_list.descriptions
             ssize_t i, idx, num_descriptions = len(descriptions)
             Description description
-            Address address
-            tuple ret_tuple
+            bint final_desc = False
         for i in range(num_descriptions):
+            if i == num_descriptions - 1:
+                final_desc = True
             if description_list.load_balance:
                 idx = (i + description_list.lru_index) % num_descriptions
             else:
                 idx = i
             description = descriptions[idx]
-            ret_tuple = self._connect_with_description(description)
-            if ret_tuple is not None:
-                sock, address = ret_tuple
+            redirect_params = self._connect_with_description(description,
+                                                             params,
+                                                             final_desc)
+            if redirect_params is not None \
+                    or not self._protocol._in_connect:
                 description_list.lru_index = (idx + 1) % num_descriptions
                 break
-        if description.expire_time > 0:
-            sock.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
-            if hasattr(socket, "TCP_KEEPIDLE") \
-                    and hasattr(socket, "TCP_KEEPINTVL") \
-                    and hasattr(socket, "TCP_KEEPCNT"):
-                sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE,
-                                description.expire_time * 60)
-                sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPINTVL, 6)
-                sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPCNT, 10)
-        sock.settimeout(None)
-        if address.protocol == "tcps":
-            sock = get_ssl_socket(sock, params, description, address)
-        self._drcp_enabled = description.server_type == "pooled"
-        if self._cclass is None:
-            self._cclass = description.cclass
-        self._protocol = Protocol(sock)
-        return self._protocol._connect(self, params, description, address)
+        return redirect_params
 
     cdef Message _create_message(self, type typ):
         """
@@ -182,36 +177,71 @@ cdef class ThinConnImpl(BaseConnImpl):
         self._pool = None
         self._protocol._force_close()
 
-    cdef object _get_socket(self, object address,
-                            double tcp_connect_timeout,
-                            bint raise_exception):
+    cdef object _connect_with_address(self, Address address,
+                                      Description description,
+                                      ConnectParamsImpl params,
+                                      bint raise_exception):
         """
-        Get a socket on which to communicate using the provided parameters. If
-        a proxy is configured, a connection to the proxy is established and the
-        target host and port is forwarded to the proxy before the socket is
-        returned.
+        Creates a socket on which to communicate using the provided parameters.
+        If a proxy is configured, a connection to the proxy is established and
+        the target host and port is forwarded to the proxy. The socket is used
+        to establish a connection with the database. If a redirect is
+        required, the redirect parameters are returned.
         """
-        cdef bint use_proxy = (address.https_proxy is not None)
+        cdef:
+            bint use_proxy = (address.https_proxy is not None)
+            double timeout = description.tcp_connect_timeout
         if use_proxy:
             connect_info = (address.https_proxy, address.https_proxy_port)
         else:
             connect_info = (address.host, address.port)
         try:
-            sock = socket.create_connection(connect_info,
-                                            tcp_connect_timeout)
-        except (socket.gaierror, ConnectionRefusedError):
+            sock = socket.create_connection(connect_info, timeout)
+            if use_proxy:
+                data = f"CONNECT {address.host}:{address.port} HTTP/1.0\r\n\r\n"
+                sock.send(data.encode())
+                reply = sock.recv(1024)
+                match = re.search('HTTP/1.[01]\\s+(\\d+)\\s+', reply.decode())
+                if match is None or match.groups()[0] != '200':
+                    errors._raise_err(errors.ERR_PROXY_FAILURE,
+                                    response=reply.decode())
+            if description.expire_time > 0:
+                sock.setsockopt(socket.SOL_SOCKET, socket.SO_KEEPALIVE, 1)
+                if hasattr(socket, "TCP_KEEPIDLE") \
+                        and hasattr(socket, "TCP_KEEPINTVL") \
+                        and hasattr(socket, "TCP_KEEPCNT"):
+                    sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPIDLE,
+                                    description.expire_time * 60)
+                    sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPINTVL,
+                                    6)
+                    sock.setsockopt(socket.IPPROTO_TCP, socket.TCP_KEEPCNT,
+                                    10)
+            sock.settimeout(None)
+            if address.protocol == "tcps":
+                sock = get_ssl_socket(sock, params, description, address)
+            self._drcp_enabled = description.server_type == "pooled"
+            if self._cclass is None:
+                self._cclass = description.cclass
+            self._protocol = Protocol(sock)
+            redirect_params = self._protocol._connect_phase_one(self, params,
+                                                                description,
+                                                                address)
+            if redirect_params is not None:
+                return redirect_params
+        except exceptions.ConnectionError:
             if raise_exception:
                 raise
-            return None
-        if use_proxy:
-            data = f"CONNECT {address.host}:{address.port} HTTP/1.0\r\n\r\n"
-            sock.send(data.encode())
-            reply = sock.recv(1024)
-            match = re.search('HTTP/1.[01]\\s+(\\d+)\\s+', reply.decode())
-            if match is None or match.groups()[0] != '200':
-                errors._raise_err(errors.ERR_PROXY_FAILURE,
-                                  response=reply.decode())
-        return sock
+            return
+        except (socket.gaierror, ConnectionRefusedError) as e:
+            if raise_exception:
+                errors._raise_err(errors.ERR_CONNECTION_FAILED, cause=e,
+                                  exception=str(e))
+            return
+        except Exception as e:
+            errors._raise_err(errors.ERR_CONNECTION_FAILED, cause=e,
+                              exception=str(e))
+            return
+        self._protocol._connect_phase_two(self, description, params)
 
     cdef Statement _get_statement(self, str sql, bint cache_statement):
         """

src/oracledb/impl/thin/messages.pyx

@@ -1538,6 +1538,8 @@ cdef class ConnectMessage(Message):
                 if end_pos > 0:
                     error_code = response[pos + 5:end_pos]
                     error_code_int = int(error_code)
+            if error_code_int == 0:
+                errors._raise_err(errors.ERR_UNEXPECTED_REFUSE)
             if error_code_int == TNS_ERR_INVALID_SERVICE_NAME:
                 errors._raise_err(errors.ERR_INVALID_SERVICE_NAME,
                                   service_name=self.description.service_name,

src/oracledb/impl/thin/protocol.pyx

@@ -118,13 +118,18 @@ cdef class Protocol:
                     self._process_message(message)
                 self._final_close(self._write_buf)
 
-    cdef ConnectParamsImpl _connect(self, ThinConnImpl conn_impl,
-                                    ConnectParamsImpl params,
-                                    Description description, Address address):
+    cdef ConnectParamsImpl _connect_phase_one(self, ThinConnImpl conn_impl,
+                                              ConnectParamsImpl params,
+                                              Description description,
+                                              Address address):
+        """
+        Method for performing the required steps for establishing a connection
+        within the scope of a retry. If the listener refuses the connection, a
+        retry will be performed, if retry_count is set.
+        """
         cdef:
             ConnectMessage connect_message
-            object temp_sock, ssl_context
-            AuthMessage auth_message
+            object ssl_context
             uint8_t packet_type
             str connect_string
 
@@ -172,6 +177,16 @@ cdef class Protocol:
                     sock = ssl_context.wrap_socket(sock)
                     self.__set_socket(sock)
 
+    cdef int _connect_phase_two(self, ThinConnImpl conn_impl,
+                                Description description,
+                                ConnectParamsImpl params) except -1:
+        """"
+        Method for perfoming the required steps for establishing a connection
+        oustide the scope of a retry. If any of the steps in this method fail,
+        an exception will be raised.
+        """
+        cdef:
+            AuthMessage auth_message
         # check if the protocol version supported by the database is high
         # enough; if not, reject the connection immediately
         if self._caps.protocol_version < TNS_VERSION_MIN_ACCEPTED: