ping method

Future<bool> ping()

Check if the database connection is still alive.

Sends a round-trip message to the database to verify connectivity. Use this to detect stale connections before executing important operations.

Returns: true if the connection is alive and responsive, false otherwise.

Example - Health Check:

if (!await connection.ping()) {
  print('Connection lost, reconnecting...');
  await connection.close();
  connection = await OracleConnection.connect(
    dpiOracle: dpiOracle,
    context: context,
    config: config,
  );
}

Example - Pre-Operation Validation:

Future<void> processData() async {
  // Validate connection before long operation
  if (!await connection.ping()) {
    throw Exception('Database connection unavailable');
  }

  // Proceed with processing
  await connection.executeUpdate('...');
}

Tip: In connection pools, ping is automatically called to validate connections before they are returned to clients.

See also:

Implementation

Future<bool> ping() async {
  if (!_isConnected || _disposed) {
    return false;
  }

  try {
    final result = _dpiOracle.dpiConn_ping(_connectionPtr.value);
    return result == DPI_SUCCESS;
  } catch (e) {
    // Log the error for debugging but return false to indicate ping failed
    MemoryManager.logWarning('Connection ping failed: $e');
    return false;
  }
}