setClientIdentifier method

Future<void> setClientIdentifier(
  1. String clientId
)

Set client identifier for end-to-end application tracing.

Sets a client identifier that appears in V$SESSION and can be used for monitoring, auditing, and resource management. Typically identifies the end user of the application.

Parameters:

  • clientId: Client identifier string (e.g., username, email, session ID)

Example - User Tracking:

// Set client identifier when user logs in
await connection.setClientIdentifier('user@example.com');

// Now DBAs can see which user is running queries:
// SELECT client_identifier, sql_text FROM v$session WHERE ...

Example - Session Monitoring:

final sessionId = uuid.v4();
await connection.setClientIdentifier(sessionId);

// Execute operations
await connection.query('SELECT ...');

// DBA can track this specific session

Use Cases:

  • Identify end users in pooled connection environments
  • Track application sessions across connection pool reuse
  • Enable fine-grained auditing by user
  • Resource management and limits per client

See also:

  • setModule to set the application module name
  • setAction to set the current action within a module

Implementation

Future<void> setClientIdentifier(String clientId) async {
  _ensureConnected();

  final (clientIdNative, clientIdLen) = StringUtils.toNativeUtf8WithLength(clientId, _memoryManager);

  final result = _dpiOracle.dpiConn_setClientIdentifier(
    _connectionPtr.value,
    clientIdNative,
    clientIdLen,
  );

  if (result == DPI_FAILURE) {
    throw OracleConnectionException('Failed to set client identifier');
  }
}