insertReturning method

Future<Row> insertReturning(
  1. Insertable<Row> entity, {
  2. UpsertClause<Row, RS>? onConflict,
})

Inserts a row into the table and returns it.

Depending on how the statement is configured, it's possible that an insert does not actually insert a row (e.g. if a DoNothing clause has been added as an upsertClause). In this case, this method throws a StateError. In cases where that's possible, consider using insertReturningOrNull or runReturning instead.

Implementation

Future<Row> insertReturning(
  Insertable<Row> entity, {
  UpsertClause<Row, RS>? onConflict,
}) async {
  source = null;
  final row = await insertReturningOrNull(entity, onConflict: onConflict);

  if (row == null) {
    throw StateError(
      'The insert statement did not insert any rows that '
      'could be returned. Please use insertReturningOrNull() when using a '
      '`DoUpdate` clause with `where`.',
    );
  }

  return row;
}