apply method

int apply(
  1. Transaction transaction, {
  2. bool savepoint = false,
})

Inserts, deletes, and updates database rows in a batch.

This method writes the mapping table edits to the database. These edits must have been previously accumulated in a Transaction object and must be passed as the transaction argument. If savepoint is true, the edits of the transaction are written but are not committed.

If savepoint is false, which is the default behavior, the edits of the transaction are written and are committed within a single SQLite transaction together with all previously written but uncommitted edits, if any, made by recent calls to apply with savepoint set to true.

If an Exception is thrown during the writing of an edit of the transaction, then all edits of the transaction are rolled back and the exception is rethrown. However, previously written but uncommitted edits, if any, made by recent calls to apply with savepoint set to true, are preserved via the SQLite savepoint mechanism and may still be committed later by a successful non-savepoint apply method call.

If an Exception or other Object is thrown from this method, then the API status of this SQLite instance should be verified via its isApiReady property. A false value signals that due to a severe problem, possibly at the OS level (such as a full disk), the API of the instance cannot be used and the instance should be deactivated.

Written but uncommitted savepoint edits can only be committed by a non-savepoint apply; calling deactivate discards uncommitted edits.

The method returns the number of edits of the transaction that were actually written and were not ignored by the database (see also applied). The database may ignore an edit if it deletes or updates a non-existent row, or inserts a row with a key that is already used by an existing row. The transaction object is not modified by this method.

Changing the kind of a row is not supported and results in an Exception being thrown and the transaction being rolled back; however, it is possible to delete a row and insert a new one with the updated kind.

If calling apply results in edits written to the mapping table, then the corresponding FTS indexes are synchronized automatically.

Implementation

int apply(Transaction transaction, {bool savepoint = false}) {
  _applied = null;
  checkActive();
  checkApiReady();
  int count = 0;
  try {
    for (var entry in transaction._entries)
      count += switch (entry) {
        _TxUpdate _ => update(entry.key, entry.value) ? 1 : 0,
        _TxDelete _ => delete(entry.key) ? 1 : 0,
        _TxInsert _ => insert(entry.key, entry.value) ? 1 : 0,
      };
  } on Exception {
    try {
      rollbackToSavepoint();
    } catch (x, st) {
      log.severe("SQLite.apply: rollbackToSavepoint failed", x, st);
    }
    rethrow;
  } catch (_) {
    _apiStatus = _ApiStatus.failed;
    rethrow;
  }
  if (savepoint)
    createSavepoint(count);
  else
    commitTransaction(count);
  return count;
}