Transactions: Atomic Reads, Writes, and Rollback in Cindel

Transactions group database work into one consistent operation. Use readTxn when several reads must share a stable snapshot, and writeTxn when a set of writes must either all succeed or all be discarded together. Single calls such as a lone put or delete don’t need an explicit transaction — reach for one only when a workflow involves more than one database step that must stay consistent.

Single put and delete calls are already atomic on their own. You only need an explicit transaction when multiple operations must commit or roll back as a unit.

Read Transactions

readTxn runs a callback inside a consistent read snapshot. Every query inside the callback sees the same database state — even if other writes land between them.

final summary = await db.readTxn(() async {
  final open = await db.todos
      .filter()
      .completedEqualTo(false)
      .count();

  final done = await db.todos
      .filter()
      .completedEqualTo(true)
      .count();

  return (open: open, done: done);
});

Do not attempt any writes inside readTxn. Calling put, delete, or any other write operation inside a read transaction throws a CindelTransactionError.

await db.readTxn(() async {
  await db.todos.put(todo); // Throws CindelTransactionError.
});

Write Transactions

writeTxn runs writes atomically. If every operation in the callback completes without throwing, the transaction commits. If the callback throws for any reason, Cindel rolls the entire transaction back — no partial writes are ever persisted.

// Simple write transaction — persist a single object alongside an audit event.
await db.writeTxn(() async {
  await db.todos.put(todo);
  await db.auditEvents.put(event);
});

Use a write transaction whenever a set of changes must commit as one logical unit:

// Persist an order and all its line items together.
await db.writeTxn(() async {
  await db.orders.put(order);
  await db.orderLines.putAll(lines);
});

You can also read inside a writeTxn when a write depends on existing data:

await db.writeTxn(() async {
  final todo = await db.todos.get(todoId);
  if (todo == null) {
    throw StateError('Todo not found.');
  }

  todo.completed = true;
  await db.todos.put(todo);
});

Rollback Behavior

When the writeTxn callback throws, Cindel rolls the transaction back automatically. Rolled-back writes are never committed to storage, and watcher notifications for those writes are never emitted. The error is returned to the caller so you can retry, show an error, or abandon the operation.

try {
  await db.writeTxn(() async {
    await db.todos.put(todo);
    throw StateError('Something went wrong.');
  });
} catch (e) {
  // The put was rolled back. Handle the error here.
}

Multi-Step Example: Checkout

The following checkout example shows a read-then-write pattern inside a single writeTxn. The stock check and the inventory deduction belong to the same business operation. If stock is insufficient, the callback throws and nothing is committed.

await db.writeTxn(() async {
  final product = await db.products.get(productId);

  if (product == null || product.stock < quantity) {
    throw StateError('Not enough stock.');
  }

  await db.products.put(
    product.copyWith(stock: product.stock - quantity),
  );

  await db.orders.put(order);
  await db.orderLines.putAll(lines);
});

Common Mistakes

Writing inside readTxn → CindelTransactionError

readTxn is for reads only. Any write call inside a read transaction throws CindelTransactionError immediately.

// ❌ Wrong — will throw.
await db.readTxn(() async {
  await db.todos.put(todo);
});

// ✅ Correct — use writeTxn for writes.
await db.writeTxn(() async {
  await db.todos.put(todo);
});

Nesting explicit transactions → rejected

Cindel rejects nested explicit transactions. If you open a writeTxn inside another writeTxn, the inner call is rejected.

// ❌ Wrong — nested transaction is rejected.
await db.writeTxn(() async {
  await db.writeTxn(() async {
    await db.todos.put(todo);
  });
});

Keep transaction boundaries at the outermost caller level. Helper methods should perform reads and writes without opening their own transactions, leaving that responsibility to the code that calls them.

Swallowing errors inside a transaction → rollback won't fire

Rollback depends on the callback throwing. If you catch an error inside the callback and don’t rethrow it, Cindel treats the callback as successful and commits whatever ran before the catch.

// ❌ Wrong — error is swallowed; partial writes may commit.
await db.writeTxn(() async {
  try {
    await db.todos.put(todo);
    throw StateError('Invalid follow-up step.');
  } catch (_) {
    // Silently ignoring the error — Cindel sees a clean return.
  }
});

// ✅ Correct — rethrow so the transaction rolls back.
await db.writeTxn(() async {
  try {
    await db.todos.put(todo);
    throw StateError('Invalid follow-up step.');
  } catch (_) {
    rethrow;
  }
});

Doing unrelated work inside a transaction → keep them DB-scoped

Transactions hold a database lock for their duration. Waiting on network calls, showing UI prompts, or running any long-running non-database work inside a transaction callback blocks other database operations and increases the risk of contention.Prepare all inputs before entering the transaction, then perform only the database reads and writes that must be atomic inside the callback.

// ❌ Wrong — network call inside the transaction.
await db.writeTxn(() async {
  final data = await fetchFromServer(); // Don't do this.
  await db.todos.put(Todo.fromJson(data));
});

// ✅ Correct — fetch first, then write.
final data = await fetchFromServer();
await db.writeTxn(() async {
  await db.todos.put(Todo.fromJson(data));
});

Get Started

Data Modeling

Querying Data

Core Features

Platforms

Reference

Transactions: Atomic Reads, Writes, and Rollback in Cindel

Read Transactions

Write Transactions

Rollback Behavior

Multi-Step Example: Checkout

Common Mistakes

​Read Transactions

​Write Transactions

​Rollback Behavior

​Multi-Step Example: Checkout

​Common Mistakes

Read Transactions

Write Transactions

Rollback Behavior

Multi-Step Example: Checkout

Common Mistakes