📄 tanstack/db/latest/docs/reference/interfaces/Transaction

File: Transaction.md | Updated: 11/15/2025

Source: https://tanstack.com/db/latest/docs/reference/interfaces/Transaction



TanStack

DB v0v0

Search...

+ K

Auto

Log In

TanStack StartRC

Docs Examples GitHub Contributors

TanStack Router

Docs Examples GitHub Contributors

TanStack Query

Docs Examples GitHub Contributors

TanStack Table

Docs Examples Github Contributors

TanStack Formnew

Docs Examples Github Contributors

TanStack DBbeta

Docs Github Contributors

TanStack Virtual

Docs Examples Github Contributors

TanStack Paceralpha

Docs Examples Github Contributors

TanStack Storealpha

Docs Examples Github Contributors

TanStack Devtoolsalpha

Docs Github Contributors

More Libraries

Maintainers Partners Support Learn StatsBETA Discord Merch Blog GitHub Ethos Brand Guide

Documentation

Framework

React logo

React

Version

Latest

Search...

+ K

Menu

Getting Started

Guides

Collections

Frameworks

Community

API Reference

Framework

React logo

React

Version

Latest

Menu

Getting Started

Guides

Collections

Frameworks

Community

API Reference

On this page

Transaction

Copy Markdown

Interface: Transaction<T>
=========================

Defined in: packages/db/src/transactions.ts:208

Type Parameters
--------------- ### T

T extends object = Record<string, unknown>

Properties
---------- ### autoCommit

ts

autoCommit: boolean;


autoCommit: boolean;

Defined in: packages/db/src/transactions.ts:214

### createdAt

ts

createdAt: Date;


createdAt: Date;

Defined in: packages/db/src/transactions.ts:215

### error?

ts

optional error: object;


optional error: object;

Defined in: packages/db/src/transactions.ts:218

#### error

ts

error: Error;


error: Error;

#### message

ts

message: string;


message: string;

### id

ts

id: string;


id: string;

Defined in: packages/db/src/transactions.ts:209

### isPersisted

ts

isPersisted: Deferred<Transaction<T>>;


isPersisted: Deferred<Transaction<T>>;

Defined in: packages/db/src/transactions.ts:213

### metadata

ts

metadata: Record<string, unknown>;


metadata: Record<string, unknown>;

Defined in: packages/db/src/transactions.ts:217

### mutationFn

ts

mutationFn: MutationFn<T>;


mutationFn: MutationFn<T>;

Defined in: packages/db/src/transactions.ts:211

### mutations

ts

mutations: PendingMutation<T, OperationType, Collection<T, any, any, any, any>>[];


mutations: PendingMutation<T, OperationType, Collection<T, any, any, any, any>>[];

Defined in: packages/db/src/transactions.ts:212

### sequenceNumber

ts

sequenceNumber: number;


sequenceNumber: number;

Defined in: packages/db/src/transactions.ts:216

### state

ts

state: TransactionState;


state: TransactionState;

Defined in: packages/db/src/transactions.ts:210

Methods
------- ### applyMutations()

ts

applyMutations(mutations): void;


applyMutations(mutations): void;

Defined in: packages/db/src/transactions.ts:327

Apply new mutations to this transaction, intelligently merging with existing mutations

When mutations operate on the same item (same globalKey), they are merged according to the following rules:

  • insert + update → insert (merge changes, keep empty original)
  • insert + delete → removed (mutations cancel each other out)
  • update + delete → delete (delete dominates)
  • update + update → update (union changes, keep first original)
  • same type → replace with latest

This merging reduces over-the-wire churn and keeps the optimistic local view aligned with user intent.

#### Parameters ##### mutations

PendingMutation <any, OperationType , Collection <any, any, any, any, any>>[]

Array of new mutations to apply

#### Returns

void

### commit()

ts

commit(): Promise<Transaction<T>>;


commit(): Promise<Transaction<T>>;

Defined in: packages/db/src/transactions.ts:472

Commit the transaction and execute the mutation function

#### Returns

Promise<Transaction<T>>

Promise that resolves to this transaction when complete

#### Examples

ts

// Manual commit (when autoCommit is false)
const tx = createTransaction({
  autoCommit: false,
  mutationFn: async ({ transaction }) => {
    await api.saveChanges(transaction.mutations)
  }
})

tx.mutate(() => {
  collection.insert({ id: "1", text: "Buy milk" })
})

await tx.commit() // Manually commit


// Manual commit (when autoCommit is false)
const tx = createTransaction({
  autoCommit: false,
  mutationFn: async ({ transaction }) => {
    await api.saveChanges(transaction.mutations)
  }
})

tx.mutate(() => {
  collection.insert({ id: "1", text: "Buy milk" })
})

await tx.commit() // Manually commit

ts

// Handle commit errors
try {
  const tx = createTransaction({
    mutationFn: async () => { throw new Error("API failed") }
  })

  tx.mutate(() => {
    collection.insert({ id: "1", text: "Item" })
  })

  await tx.commit()
} catch (error) {
  console.log('Commit failed, transaction rolled back:', error)
}


// Handle commit errors
try {
  const tx = createTransaction({
    mutationFn: async () => { throw new Error("API failed") }
  })

  tx.mutate(() => {
    collection.insert({ id: "1", text: "Item" })
  })

  await tx.commit()
} catch (error) {
  console.log('Commit failed, transaction rolled back:', error)
}

ts

// Check transaction state after commit
await tx.commit()
console.log(tx.state) // "completed" or "failed"


// Check transaction state after commit
await tx.commit()
console.log(tx.state) // "completed" or "failed"

### compareCreatedAt()

ts

compareCreatedAt(other): number;


compareCreatedAt(other): number;

Defined in: packages/db/src/transactions.ts:526

Compare two transactions by their createdAt time and sequence number in order to sort them in the order they were created.

#### Parameters ##### other

Transaction<any>

The other transaction to compare to

#### Returns

number

-1 if this transaction was created before the other, 1 if it was created after, 0 if they were created at the same time

### mutate()

ts

mutate(callback): Transaction<T>;


mutate(callback): Transaction<T>;

Defined in: packages/db/src/transactions.ts:287

Execute collection operations within this transaction

#### Parameters ##### callback

() => void

Function containing collection operations to group together. If the callback returns a Promise, the transaction context will remain active until the promise settles, allowing optimistic writes after await boundaries.

#### Returns

Transaction<T>

This transaction for chaining

#### Examples

ts

// Group multiple operations
const tx = createTransaction({ mutationFn: async () => {
  // Send to API
}})

tx.mutate(() => {
  collection.insert({ id: "1", text: "Buy milk" })
  collection.update("2", draft => { draft.completed = true })
  collection.delete("3")
})

await tx.isPersisted.promise


// Group multiple operations
const tx = createTransaction({ mutationFn: async () => {
  // Send to API
}})

tx.mutate(() => {
  collection.insert({ id: "1", text: "Buy milk" })
  collection.update("2", draft => { draft.completed = true })
  collection.delete("3")
})

await tx.isPersisted.promise

ts

// Handle mutate errors
try {
  tx.mutate(() => {
    collection.insert({ id: "invalid" }) // This might throw
  })
} catch (error) {
  console.log('Mutation failed:', error)
}


// Handle mutate errors
try {
  tx.mutate(() => {
    collection.insert({ id: "invalid" }) // This might throw
  })
} catch (error) {
  console.log('Mutation failed:', error)
}

ts

// Manual commit control
const tx = createTransaction({ autoCommit: false, mutationFn: async () => {} })

tx.mutate(() => {
  collection.insert({ id: "1", text: "Item" })
})

// Commit later when ready
await tx.commit()


// Manual commit control
const tx = createTransaction({ autoCommit: false, mutationFn: async () => {} })

tx.mutate(() => {
  collection.insert({ id: "1", text: "Item" })
})

// Commit later when ready
await tx.commit()

### rollback()

ts

rollback(config?): Transaction<T>;


rollback(config?): Transaction<T>;

Defined in: packages/db/src/transactions.ts:389

Rollback the transaction and any conflicting transactions

#### Parameters ##### config?

Configuration for rollback behavior

###### isSecondaryRollback?

boolean

#### Returns

Transaction<T>

This transaction for chaining

#### Examples

ts

// Manual rollback
const tx = createTransaction({ mutationFn: async () => {
  // Send to API
}})

tx.mutate(() => {
  collection.insert({ id: "1", text: "Buy milk" })
})

// Rollback if needed
if (shouldCancel) {
  tx.rollback()
}


// Manual rollback
const tx = createTransaction({ mutationFn: async () => {
  // Send to API
}})

tx.mutate(() => {
  collection.insert({ id: "1", text: "Buy milk" })
})

// Rollback if needed
if (shouldCancel) {
  tx.rollback()
}

ts

// Handle rollback cascade (automatic)
const tx1 = createTransaction({ mutationFn: async () => {} })
const tx2 = createTransaction({ mutationFn: async () => {} })

tx1.mutate(() => collection.update("1", draft => { draft.value = "A" }))
tx2.mutate(() => collection.update("1", draft => { draft.value = "B" })) // Same item

tx1.rollback() // This will also rollback tx2 due to conflict


// Handle rollback cascade (automatic)
const tx1 = createTransaction({ mutationFn: async () => {} })
const tx2 = createTransaction({ mutationFn: async () => {} })

tx1.mutate(() => collection.update("1", draft => { draft.value = "A" }))
tx2.mutate(() => collection.update("1", draft => { draft.value = "B" })) // Same item

tx1.rollback() // This will also rollback tx2 due to conflict

ts

// Handle rollback in error scenarios
try {
  await tx.isPersisted.promise
} catch (error) {
  console.log('Transaction was rolled back:', error)
  // Transaction automatically rolled back on mutation function failure
}


// Handle rollback in error scenarios
try {
  await tx.isPersisted.promise
} catch (error) {
  console.log('Transaction was rolled back:', error)
  // Transaction automatically rolled back on mutation function failure
}

### setState()

ts

setState(newState): void;


setState(newState): void;

Defined in: packages/db/src/transactions.ts:238

#### Parameters ##### newState

TransactionState

#### Returns

void

### touchCollection()

ts

touchCollection(): void;


touchCollection(): void;

Defined in: packages/db/src/transactions.ts:417

#### Returns

void

Edit on GitHub

Home

Partners Become a Partner

Code RabbitCode Rabbit CloudflareCloudflare AG GridAG Grid NetlifyNetlify NeonNeon WorkOSWorkOS ClerkClerk ConvexConvex ElectricElectric SentrySentry PrismaPrisma StrapiStrapi UnkeyUnkey

scarf analytics