📄 tanstack/db/latest/docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig

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

Source: https://tanstack.com/db/latest/docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig

TanStack

DB v0v0

Search...

+ K

Auto

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

Getting Started

Guides

Collections

Frameworks

Community

Resources & Packages

core

API Reference

Framework

React logo

React

Version

Latest

Getting Started

Guides

Collections

Frameworks

Community

Resources & Packages

core

API Reference

On this page

Interface: ElectricCollectionConfig<T, TSchema>
Extends
Type Parameters
T
TSchema
Properties
onDelete()?
Parameters
params
Returns
Examples
onInsert()?
Parameters
params
Returns
Examples
onUpdate()?
Parameters
params
Returns
Examples
shapeOptions
syncMode?

ElectricCollectionConfig

Copy Markdown

Interface: ElectricCollectionConfig<T, TSchema>
===============================================

Defined in: packages/electric-db-collection/src/electric.ts:108

Configuration interface for Electric collection options

Extends
-------

Omit<BaseCollectionConfig<T, string | number, TSchema, UtilsRecord, any>, "onInsert" | "onUpdate" | "onDelete" | "syncMode">

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

T extends Row<unknown> = Row<unknown>

The type of items in the collection

### TSchema

TSchema extends StandardSchemaV1 = never

The schema type for validation

Properties
---------- ### onDelete()?

optional onDelete: (params) => Promise<MatchingStrategy>;


optional onDelete: (params) => Promise<MatchingStrategy>;

Defined in: packages/electric-db-collection/src/electric.ts:224

Optional asynchronous handler function called before a delete operation

#### Parameters ##### params

DeleteMutationFnParams<T>

Object containing transaction and collection information

#### Returns

Promise<MatchingStrategy>

Promise resolving to { txid, timeout? } or void

#### Examples

// Basic Electric delete handler with txid (recommended)
onDelete: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  const result = await api.todos.delete({
    id: mutation.original.id
  })
  return { txid: result.txid }
}


// Basic Electric delete handler with txid (recommended)
onDelete: async ({ transaction }) => {
  const mutation = transaction.mutations[0]
  const result = await api.todos.delete({
    id: mutation.original.id
  })
  return { txid: result.txid }
}

// Use awaitMatch utility for custom matching
onDelete: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.todos.delete({ id: mutation.original.id })
  await collection.utils.awaitMatch(
    (message) => isChangeMessage(message) &&
                 message.headers.operation === 'delete' &&
                 message.value.id === mutation.original.id
  )
}


// Use awaitMatch utility for custom matching
onDelete: async ({ transaction, collection }) => {
  const mutation = transaction.mutations[0]
  await api.todos.delete({ id: mutation.original.id })
  await collection.utils.awaitMatch(
    (message) => isChangeMessage(message) &&
                 message.headers.operation === 'delete' &&
                 message.value.id === mutation.original.id
  )
}

### onInsert()?

optional onInsert: (params) => Promise<MatchingStrategy>;


optional onInsert: (params) => Promise<MatchingStrategy>;

Defined in: packages/electric-db-collection/src/electric.ts:167

Optional asynchronous handler function called before an insert operation

#### Parameters ##### params

InsertMutationFnParams<T>

Object containing transaction and collection information

#### Returns

Promise<MatchingStrategy>

Promise resolving to { txid, timeout? } or void

#### Examples

// Basic Electric insert handler with txid (recommended)
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  const result = await api.todos.create({
    data: newItem
  })
  return { txid: result.txid }
}


// Basic Electric insert handler with txid (recommended)
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  const result = await api.todos.create({
    data: newItem
  })
  return { txid: result.txid }
}

// Insert handler with custom timeout
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  const result = await api.todos.create({
    data: newItem
  })
  return { txid: result.txid, timeout: 10000 } // Wait up to 10 seconds
}


// Insert handler with custom timeout
onInsert: async ({ transaction }) => {
  const newItem = transaction.mutations[0].modified
  const result = await api.todos.create({
    data: newItem
  })
  return { txid: result.txid, timeout: 10000 } // Wait up to 10 seconds
}

// Insert handler with multiple items - return array of txids
onInsert: async ({ transaction }) => {
  const items = transaction.mutations.map(m => m.modified)
  const results = await Promise.all(
    items.map(item => api.todos.create({ data: item }))
  )
  return { txid: results.map(r => r.txid) }
}


// Insert handler with multiple items - return array of txids
onInsert: async ({ transaction }) => {
  const items = transaction.mutations.map(m => m.modified)
  const results = await Promise.all(
    items.map(item => api.todos.create({ data: item }))
  )
  return { txid: results.map(r => r.txid) }
}

// Use awaitMatch utility for custom matching
onInsert: async ({ transaction, collection }) => {
  const newItem = transaction.mutations[0].modified
  await api.todos.create({ data: newItem })
  await collection.utils.awaitMatch(
    (message) => isChangeMessage(message) &&
                 message.headers.operation === 'insert' &&
                 message.value.name === newItem.name
  )
}


// Use awaitMatch utility for custom matching
onInsert: async ({ transaction, collection }) => {
  const newItem = transaction.mutations[0].modified
  await api.todos.create({ data: newItem })
  await collection.utils.awaitMatch(
    (message) => isChangeMessage(message) &&
                 message.headers.operation === 'insert' &&
                 message.value.name === newItem.name
  )
}

### onUpdate()?

optional onUpdate: (params) => Promise<MatchingStrategy>;


optional onUpdate: (params) => Promise<MatchingStrategy>;

Defined in: packages/electric-db-collection/src/electric.ts:196

Optional asynchronous handler function called before an update operation

#### Parameters ##### params

UpdateMutationFnParams<T>

Object containing transaction and collection information

#### Returns

Promise<MatchingStrategy>

Promise resolving to { txid, timeout? } or void

#### Examples

// Basic Electric update handler with txid (recommended)
onUpdate: async ({ transaction }) => {
  const { original, changes } = transaction.mutations[0]
  const result = await api.todos.update({
    where: { id: original.id },
    data: changes
  })
  return { txid: result.txid }
}


// Basic Electric update handler with txid (recommended)
onUpdate: async ({ transaction }) => {
  const { original, changes } = transaction.mutations[0]
  const result = await api.todos.update({
    where: { id: original.id },
    data: changes
  })
  return { txid: result.txid }
}

// Use awaitMatch utility for custom matching
onUpdate: async ({ transaction, collection }) => {
  const { original, changes } = transaction.mutations[0]
  await api.todos.update({ where: { id: original.id }, data: changes })
  await collection.utils.awaitMatch(
    (message) => isChangeMessage(message) &&
                 message.headers.operation === 'update' &&
                 message.value.id === original.id
  )
}


// Use awaitMatch utility for custom matching
onUpdate: async ({ transaction, collection }) => {
  const { original, changes } = transaction.mutations[0]
  await api.todos.update({ where: { id: original.id }, data: changes })
  await collection.utils.awaitMatch(
    (message) => isChangeMessage(message) &&
                 message.headers.operation === 'update' &&
                 message.value.id === original.id
  )
}

### shapeOptions

shapeOptions: ShapeStreamOptions<GetExtensions<T>>;


shapeOptions: ShapeStreamOptions<GetExtensions<T>>;

Defined in: packages/electric-db-collection/src/electric.ts:118

Configuration options for the ElectricSQL ShapeStream

### syncMode?

optional syncMode: ElectricSyncMode;


optional syncMode: ElectricSyncMode;

Defined in: packages/electric-db-collection/src/electric.ts:119

Edit on GitHub

Home

Partners Become a Partner

scarf analytics