Timeout Parameters

The following timeout parameters are available since ruby-oci8 2.2.2.

  • tcp_connect_timeout
  • connect_timeout
  • send_timeout
  • recv_timeout

For example:

OCI8.properties[:tcp_connect_timeout] = 10
OCI8.properties[:connect_timeout] = 15
OCI8.properties[:send_timeout] = 60
OCI8.properties[:recv_timeout] = 60

These parameters are applied only to TCP/IP connections.

The first two parameters tcp_connect_timeout and connect_timeout are applied only to connect descriptors using Easy Connect Naming Method. If you use a net service name, you should set TRANSPORT_CONNECT_TIMEOUT and/or CONNECT_TIMEOUT in the address descriptor in tnsnames.ora instead of these parameters. If you use easy connect naming method without any of port, service_name, server and instance_name, you need to use //host to distinguish it from a net service name.

The next two parameters send_timeout and recv_timeout are available on Oracle 11g client or upper. Use these parameters to prevent a ruby process from being blocked by poor quality network. Otherwise, the ruby process may be blocked until TCP keepalive time (2 hours).

See Hanging After a Long Period of Inactivity for TCP keepalive time.


tcp_connect_timeout is equivalent to TCP.CONNECT_TIMEOUT in the client-side sqlnet.ora and TRANSPORT_CONNECT_TIMEOUT in the address descriptor. See description about TCP.CONNECT_TIMEOUT and TRANSPORT_CONNECT_TIMEOUT.


connect_timeout is equivalent to SQLNET.OUTBOUND_CONNECT_TIMEOUT in the client-side sqlnet.ora and CONNECT_TIMEOUT in the address description. See description about SQLNET.OUTBOUND_CONNECT_TIMEOUT and CONNECT_TIMEOUT.

Note: this parameter isn't equivalent to login timeout. It needs the following three steps to establish a database connection.

  1. Establish a TCP/IP connection.
  2. Establish an Oracle Net connection on the TCP/IP connection.
  3. Authenticate and authorize the database user.

tcp_connect_timeout sets the timeout of the first step. connect_timeout sets the total timeout of the first and the second steps. There is no timeout parameter to limit the maximum time of all three steps.

Use send_timeout and recv_timeout in case that a TCP/IP connection stalls in the third step.


send_timeout is equivalent to SQLNET.SEND_TIMEOUT in the client-side sqlnet.ora. See description about SQLNET.SEND_TIMEOUT.

Note that the connection becomes unusable on timeout.

See also OCI8#send_timeout=.


recv_timeout is equivalent to SQLNET.RECV_TIMEOUT in the client-side sqlnet.ora. See description about SQLNET.RECV_TIMEOUT.

Note that the connection becomes unusable on timeout.

See also OCI8#recv_timeout=.

Note: This parameter must be larger than the longest SQL execution time in your applications.