packages/electron-db-sqlite-persistence
| Name | Last commit message | Last commit date |
|---|---|---|
| .. | ||
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)ElectronCollectionCoordinatorpersistedCollectionOptions(...)(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: falsetocreateElectronSQLitePersistenceto keep the full-shape recovery fallback. - Collection mode (
sync-presentvssync-absent) andschemaVersionare resolved per collection and forwarded across IPC automatically. - Without an
ElectronCollectionCoordinator, single-renderer mode usesSingleProcessCoordinator: it is always leader, but still routes complete transactions to the collection's resolved IPC adapter.