query method

Future<({int? insertId, int? numAffectedRows, List rows})> query({
  1. required String sql,
  2. List? params,
})

Executes a SQL query against the database.

This method allows you to run any valid SQLite query including SELECT, INSERT, UPDATE, DELETE, and DDL statements. Parameters can be passed safely to prevent SQL injection attacks.

Parameters

  • sql: The SQL query to execute (required)
  • params: Optional list of parameters to bind to the query

Returns

A Future that resolves to a record containing:

  • insertId: The ID of the last inserted row (for INSERT queries)
  • numAffectedRows: The number of rows affected by the query
  • rows: The result rows as a list of dynamic objects

Throws

  • HttpException if there's a network error
  • CalljmpException if the user lacks permissions or the SQL is invalid

Examples

// SELECT query
final result = await calljmp.database.query(
  sql: 'SELECT * FROM users WHERE role = ?',
  params: ['admin'],
);

for (final row in result.rows) {
  print('User: ${row['name']} (${row['email']})');
}

// INSERT query
final insert = await calljmp.database.query(
  sql: 'INSERT INTO products (name, price) VALUES (?, ?)',
  params: ['Widget', 19.99],
);
print('Created product with ID: ${insert.insertId}');

// UPDATE query
final update = await calljmp.database.query(
  sql: 'UPDATE users SET last_login = ? WHERE id = ?',
  params: [DateTime.now().toIso8601String(), 123],
);
print('Updated ${update.numAffectedRows} users');

Implementation

Future<({int? insertId, int? numAffectedRows, List<dynamic> rows})> query({
  required String sql,
  List<dynamic>? params,
}) => http
    .request("${_config.serviceUrl}/database/query")
    .use(http.context(_config))
    .use(http.access())
    .post({"sql": sql, "params": params ?? []})
    .json(
      (json) => (
        insertId: json['insertId'] as int?,
        numAffectedRows: json['numAffectedRows'] as int?,
        rows: json['rows'] as List<dynamic>,
      ),
    );