Ensuring Consistent Data in FaunaDB: How to Use Multi‑Document ACID Transactions with FQL

Why You Need a Transaction in FaunaDB

Imagine you’re building a user onboarding flow. You need to create a users document and, at the same time, seed a settings document with default values. If the first write succeeds but the second fails, you’re left with an orphaned user record. Relying on application‑level locks is brittle and hard to maintain.

FaunaDB solves this with native multi‑document ACID transactions. A transaction bundles several read and write operations into a single, atomic unit. Either all operations commit, or none do. This guarantees consistency without extra code in your application.

How FaunaDB Transactions Work

Transactions are expressed in FQL using the Transaction function. Inside the function you can perform any read or write operation. FaunaDB automatically retries the transaction on transient conflicts (e.g., concurrent updates) but will abort if the transaction exceeds certain limits.

• Scope: A transaction runs against a single database instance.
• Atomicity: All operations inside the transaction either commit or roll back.
• Repeatable Reads: The transaction sees a consistent snapshot at the start of its execution.
• Automatic Retries: On transient conflicts, FaunaDB retries the transaction up to a configurable limit (default 5 times).
• Limits:
  • Maximum execution time: 30 seconds.
  • Maximum transaction log size: 10 MB.

When to Use a Transaction

Use a transaction when you have interdependent writes that must stay in sync. Typical scenarios include:

• Creating a user profile and initializing related settings.
• Transferring funds between two accounts in a banking app.
• Updating a parent document and all its child documents in a single logical change.

Avoid wrapping long‑running logic or heavy computations inside a transaction, as this increases latency and risks hitting the 30‑second limit.

Concrete Worked Example

Below is a minimal FQL snippet that creates a user and a default settings document atomically. Run it in the FaunaDB shell or via your client SDK.

// Replace <YOUR-ROLE> with a role that has write access to both collections

Transaction(
  // The transaction body is a function that receives a transaction context
  fn (txn) => {
    // 1. Create the user profile
    const user = Create(
      Collection('users'),
      {
        data: {
          email: '[contact removed]',
          name: 'Alice',
          createdAt: Now()
        }
      }
    );

    // 2. Create default settings linked to the user
    const settings = Create(
      Collection('settings'),
      {
        data: {
          userRef: Ref('users', user.id),
          theme: 'light',
          notifications: true
        }
      }
    );

    // 3. Return both refs for confirmation
    Return({ user, settings });
  }
)

Explanation of key parts:

• Transaction starts the atomic block.
• fn (txn) => { … } is the transaction function; txn can be used for advanced patterns but is optional.
• Both Create calls happen inside the transaction. If either fails (e.g., the settings collection does not exist), the entire transaction rolls back.
• The Return statement lets you inspect the created documents immediately after commit.

After running the transaction, you can verify the result with two simple queries:

// Fetch the user by email
Let(
  { user: Get(Match(Index('users_by_email'), '[contact removed]')) },
  { user }
)

// Fetch the linked settings
Let(
  { user: Get(Match(Index('users_by_email'), '[contact removed]')) },
  {
    settings: Get(Select('ref', Get(Match(Index('settings_by_user'), user.id))))
  }
)

If the transaction had failed, both queries would return no results.

Trade‑offs and Limitations

• Latency: Transactions serialize operations, so the round‑trip time can be higher than individual writes. Keep the transaction body lean.
• Timeout: A transaction that runs longer than 30 seconds is aborted. Avoid loops or heavy computations inside the transaction.
• Log Size: Operations that collectively exceed 10 MB in the transaction log abort the transaction. Large bulk imports should be split into smaller batches or performed outside a transaction.
• Retry Behavior: Automatic retries can lead to duplicate work if your code isn’t idempotent. Design your transaction logic to be safe for retries (e.g., use Match to check for existing documents before creating).

Actionable Checklist

1. Identify write operations that must stay in sync.
2. Confirm that all involved collections and indices exist.
3. Write a concise FQL transaction block that performs the necessary creates/updates.
4. Test the transaction in the FaunaDB shell, intentionally causing a failure to see the rollback.
5. Monitor latency and ensure the transaction stays well below the 30‑second limit.
6. In production, wrap the FQL call in your client SDK and handle retry‑errors gracefully.

By following these steps, you can leverage FaunaDB’s built‑in ACID guarantees to keep your data consistent and avoid complex application‑level locking.