Skip to content
Source
Sign inSign up
TanStack/db

packages/electron-db-sqlite-persistence

README.md

@tanstack/electron-db-sqlite-persistence

Thin Electron bridge for TanStack DB SQLite persistence.

Start with the SQLite Persistence guide for Collection setup and lifecycle behavior.

Public API

  • exposeElectronSQLitePersistence(...) (main process)
  • createElectronSQLitePersistence(...) (renderer process)
  • ElectronCollectionCoordinator
  • persistedCollectionOptions(...) (re-exported from core)

Use @tanstack/electron-db-sqlite-persistence/main and @tanstack/electron-db-sqlite-persistence/renderer if you prefer explicit process-specific entrypoints.

Main process

import { ipcMain } from 'electron'
import { createNodeSQLitePersistence } from '@tanstack/node-db-sqlite-persistence'
import { exposeElectronSQLitePersistence } from '@tanstack/electron-db-sqlite-persistence/main'
import Database from 'better-sqlite3'

const database = new Database(`./tanstack-db.sqlite`)

const persistence = createNodeSQLitePersistence({
  database,
})

const dispose = exposeElectronSQLitePersistence({
  ipcMain,
  persistence,
})

// Call dispose() and database.close() during shutdown.

Renderer process

import { createCollection } from '@tanstack/db'
import { ipcRenderer } from 'electron'
import {
  createElectronSQLitePersistence,
  persistedCollectionOptions,
} from '@tanstack/electron-db-sqlite-persistence'

type Todo = {
  id: string
  title: string
  completed: boolean
}

const persistence = createElectronSQLitePersistence<Todo, string>({
  ipcRenderer,
})

export const todosCollection = createCollection(
  persistedCollectionOptions<Todo, string>({
    id: `todos`,
    getKey: (todo) => todo.id,
    persistence,
    schemaVersion: 1, // Per-collection schema version
  }),
)

Multi-renderer ownership

Pass an ElectronCollectionCoordinator when multiple renderers share the same database. Coordinators using the same dbName elect a writer independently for each collection.

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

const coordinator = new ElectronCollectionCoordinator({
  dbName: `tanstack-db`,
})

const persistence = createElectronSQLitePersistence({
  ipcRenderer,
  coordinator,
})

// On teardown:
// coordinator.dispose()

The persisted sync wrapper routes every source transaction with durable effects through the coordinator's required requestApplyCommittedTx(collectionId, tx) method. The elected renderer applies the complete PersistedTx through its resolved per-collection renderer adapter, which forwards it over IPC to the main-process persistence owner. Resolution remains specific to the collection id, mode, and schemaVersion.

Truncation, row changes, row metadata, collection metadata, and stream position stay in the same transaction. Electron does not feature-detect a partial route or fall back to row-only mutation RPC. A custom coordinator that omits requestApplyCommittedTx is rejected while the collection is configured, before its sync source can publish rows. An effect-free source commit neither publishes nor consumes a coordinator sequence.

If a mutating RPC loses its response, Electron coordination replays it only while the requester still knows the same non-null leader id and term. An unknown initial route or any leader/term change rejects the direct RPC with IndeterminateCommitError. For a source-backed persisted Collection, the sync wrapper can certify the original transaction ID through the replacement leader and the main-process SQLite adapter. Application-issued mutations still need caller reconciliation. Main and renderer must use matching persistence protocol v5 peers for this IPC operation. A main-process adapter used by an ElectronCollectionCoordinator must implement reserveLeadershipTerm so each election reserves a durable term before publishing a route. An adapter without that capability can still serve single-renderer persistence through SingleProcessCoordinator; a coordinated election rejects it before route publication.

Remote-subset requests use the same crash-only boundary. The coordinator projects a live LoadSubsetOptions input to the exported TransportedLoadSubsetOptions type before either local completion or renderer transport. Live signal and subscription fields do not cross the boundary. Unsupported nested values throw RemoteSubsetWireValueError with the exact value path before publication; Electron does not add codecs, coercion, or a fallback representation.

Electron uses the same explicit lease lifecycle as Browser coordination. The same request object reuses one acquisition identity, distinct equal objects remain independent, and release unloads the exact transported options once. Leadership loss unloads the retiring renderer's leases; still-live requester leases replay against the next leader. A second owner registration for one collection throws DuplicateRemoteSubsetOwnerError, and there is no adapter fallback for a missing owner. Remote follower transport/admission failures reject and retain demand for its normal retry without entering the follower's local owner lifecycle. Terminal release identities expire after the existing RPC dedupe horizon while delayed duplicates inside that horizon remain idempotent.

Notes

  • The renderer API mirrors other runtimes: one shared create...Persistence.
  • IPC protocol v6 forwards explicit eager or managed storage targets, on-demand cache claims, rotation, renewal, release, claim checks on SQLite reads and writes, exact transaction-ID reconciliation, and claim-scoped leadership-term reservation. Upgrade main and renderer together. If a custom main-process adapter does not implement these operations, pass managedCacheGenerations: false to createElectronSQLitePersistence to keep the full-shape recovery fallback.
  • Collection mode (sync-present vs sync-absent) and schemaVersion are resolved per collection and forwarded across IPC automatically.
  • Without an ElectronCollectionCoordinator, single-renderer mode uses SingleProcessCoordinator: it is always leader, but still routes complete transactions to the collection's resolved IPC adapter.