execute method

Execute a SQL statement and return a statement object for iteration.

Use this method when you need fine-grained control over result fetching or when working with large result sets that should be streamed.

Parameters:

• sql: The SQL statement to execute (SELECT, INSERT, UPDATE, DELETE, etc.)
• params: Optional list of bind parameters (positional binding)

Returns: An OracleStatement object that can be used to fetch results or get metadata. Important: You must call OracleStatement.close when done to free resources.

Example - Streaming Results:

final stmt = await connection.execute(
  'SELECT id, name FROM employees WHERE dept_id = :1',
  params: [departmentId],
);

try {
  await for (final row in stmt.rows()) {
    print('${row['id']}: ${row['name']}');
  }
} finally {
  await stmt.close();  // Always close!
}

Example - Getting Metadata:

final stmt = await connection.execute('SELECT * FROM employees');
final columns = await stmt.getColumnInfo();
for (final col in columns) {
  print('Column: ${col.name}, Type: ${col.oracleType}');
}
await stmt.close();

Tip: For simple queries where you want all results at once, use query instead - it automatically handles cleanup.

See also:

• query for simpler result fetching
• executeUpdate for DML operations