This skill builds on db-core and db-core/collection-setup. Read those first.

SQLite Persistence#

TanStack DB persistence adds a durable SQLite-backed layer to any collection. Data survives page reloads, app restarts, and offline periods. The server remains authoritative for synced collections -- persistence provides a local cache that hydrates instantly.

Choosing a Platform Package#

All platform packages re-export persistedCollectionOptions from the core.

Local-Only Persistence (No Server)#

For purely local data with no sync backend:

import { createCollection } from '@tanstack/react-db'
import {
  createBrowserWASQLitePersistence,
  openBrowserWASQLiteOPFSDatabase,
  persistedCollectionOptions,
} from '@tanstack/browser-db-sqlite-persistence'

const database = await openBrowserWASQLiteOPFSDatabase({
  databaseName: 'my-app.sqlite',
})

const persistence = createBrowserWASQLitePersistence({
  database,
})

const draftsCollection = createCollection(
  persistedCollectionOptions<Draft, string>({
    id: 'drafts',
    getKey: (d) => d.id,
    persistence,
    schemaVersion: 1,
  }),
)

Local-only collections provide collection.utils.acceptMutations() for applying mutations directly.

Synced Persistence (Wrapping an Adapter)#

Spread an existing adapter's options into persistedCollectionOptions to add persistence on top of sync:

import { createCollection } from '@tanstack/react-db'
import { electricCollectionOptions } from '@tanstack/electric-db-collection'
import {
  createReactNativeSQLitePersistence,
  persistedCollectionOptions,
} from '@tanstack/react-native-db-sqlite-persistence'

const persistence = createReactNativeSQLitePersistence({ database })

const todosCollection = createCollection(
  persistedCollectionOptions({
    ...electricCollectionOptions({
      id: 'todos',
      shapeOptions: { url: '/api/electric/todos' },
      getKey: (item: { id: string }) => item.id,
    }),
    persistence,
    schemaVersion: 1,
  }),
)

This works with any adapter: electricCollectionOptions, queryCollectionOptions, powerSyncCollectionOptions, etc. The persistedCollectionOptions wrapper intercepts the sync layer to persist data as it flows through.

Multi-Tab / Multi-Process Coordination#

Coordinators handle leader election and cross-instance communication so only one tab/process owns the database writer.

Every coordinator must implement requestApplyCommittedTx(collectionId, tx). The method routes a complete committed transaction to the collection's supported writer, including truncate, rows, row metadata, collection metadata, and stream position. This is a required contract, not an optional capability. Do not feature-detect it, fall back to row-only mutation routing, or bypass the coordinator after source publication. Untyped custom coordinators that omit the method fail during collection configuration.

SingleProcessCoordinator has no election or cross-process communication, but it is not a no-op persistence owner. It registers the resolved adapter for each collection and applies complete committed transactions through that adapter.

Browser persistence uses single-process semantics by default. That is correct when the app runs in one tab at a time or each tab has its own database. Pass a BrowserCollectionCoordinator only when multiple tabs share one OPFS database.

Browser example:

import { BrowserCollectionCoordinator } from '@tanstack/browser-db-sqlite-persistence'

const coordinator = new BrowserCollectionCoordinator({
  dbName: 'my-app',
})

// Pass to persistence
const persistence = createBrowserWASQLitePersistence({ database, coordinator })

// Cleanup on shutdown
coordinator.dispose()

Electron requires setup in both processes:

// Main process
import { exposeElectronSQLitePersistence } from '@tanstack/electron-db-sqlite-persistence'
import { app, ipcMain } from 'electron'

const disposeIpc = exposeElectronSQLitePersistence({ persistence, ipcMain })
app.on('before-quit', () => {
  disposeIpc()
})

// Renderer process
import {
  createElectronSQLitePersistence,
  ElectronCollectionCoordinator,
} from '@tanstack/electron-db-sqlite-persistence'

const coordinator = new ElectronCollectionCoordinator({ dbName: 'my-app' })
const persistence = createElectronSQLitePersistence({
  ipcRenderer: window.electron.ipcRenderer,
  coordinator,
})

Electron persistence calls cross the renderer/main boundary through IPC. The ElectronCollectionCoordinator separately coordinates renderer instances with BroadcastChannel and Web Locks. It elects an owner per collection and routes the complete committed transaction through that collection's resolved renderer adapter to the main-process persistence owner.

Schema Versioning#

schemaVersion tracks the shape of persisted data. When the stored version doesn't match the code, the collection resets (drops and reloads from server for synced collections, or throws for local-only).

persistedCollectionOptions({
  // ...
  schemaVersion: 2, // bump when you change the data shape
})

There is no custom migration function -- a version mismatch triggers a full reset. For synced collections this is safe because the server re-supplies the data.

Applied Transaction Log Pruning#

The SQLite applied_tx log is a replay cache, not permanent history. Browser, Capacitor, Cloudflare Durable Objects, Expo, Node, React Native, and Tauri wrappers prune it inside write transactions by default, per collection:

• appliedTxPruneMaxRows: 1_000
• appliedTxPruneMaxAgeSeconds: 86_400 (24 hours)

Set either option to 0 to disable that limit, or raise it to retain a longer replay window:

const persistence = createNodeSQLitePersistence({
  database,
  appliedTxPruneMaxRows: 5_000,
  appliedTxPruneMaxAgeSeconds: 0,
})

If a follower asks to recover from a point older than the retained log, it falls back to a full reload. Pruning does not itself shrink the SQLite file; use SQLite vacuum settings or separate maintenance when disk reclamation matters. The defaults are exported as DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS and DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS.

Raw createSQLiteCorePersistenceAdapter calls do not inject these defaults. Electron uses whichever persistence adapter the main process supplies.

Key Options#

Common Mistakes#

CRITICAL Using local-only persistence without an id#

Wrong:

persistedCollectionOptions({
  getKey: (d) => d.id,
  persistence,
  // missing id — generates random UUID each session, data won't persist across reloads
})

Correct:

persistedCollectionOptions({
  id: 'drafts',
  getKey: (d) => d.id,
  persistence,
})

Without an explicit id, the code generates a random UUID each session, so persisted data is silently abandoned on every reload. Local-only persisted collections must always provide an id. Synced collections derive it from the adapter config.

HIGH Sharing one browser database across tabs without a coordinator#

Wrong:

const persistence = createBrowserWASQLitePersistence({ database })
// Unsafe if multiple tabs share this database

Correct:

const coordinator = new BrowserCollectionCoordinator({ dbName: 'my-app' })
const persistence = createBrowserWASQLitePersistence({ database, coordinator })

Without a coordinator, multiple browser tabs that share one OPFS database can write concurrently. Use BrowserCollectionCoordinator for that case. Do not add it to a single-tab app merely because the runtime is a browser.

HIGH Not bumping schemaVersion after changing data shape#

If you add, remove, or rename fields in your collection type but keep the same schemaVersion, the persisted SQLite data will have the old shape. For synced collections, bump the version to trigger a reset and re-sync.

MEDIUM Not disposing the coordinator on cleanup#

// On app shutdown or hot module reload
coordinator.dispose()
await database.close?.()

Failing to dispose leaks BroadcastChannel subscriptions and Web Lock handles.

See also: db-core/collection-setup/SKILL.md — for adapter selection and collection configuration.

See also: offline/SKILL.md — for offline transaction queueing (complements persistence).