Open History to see the last commit
1# @tanstack/node-db-sqlite-persistence
2
3Thin Node SQLite persistence for TanStack DB.
4
5## Public API
6
7- `createNodeSQLitePersistence(...)`
8- `persistedCollectionOptions(...)` (re-exported from core)
9
10## Quick start
11
12```ts
13import { createCollection } from '@tanstack/db'
14import {
15 createNodeSQLitePersistence,
16 persistedCollectionOptions,
17} from '@tanstack/node-db-sqlite-persistence'
18import Database from 'better-sqlite3'
19
20type Todo = {
21 id: string
22 title: string
23 completed: boolean
24}
25
26// You own database lifecycle directly.
27const database = new Database(`./tanstack-db.sqlite`)
28
29// One shared persistence instance for the whole database.
30const persistence = createNodeSQLitePersistence({
31 database,
32})
33
34export const todosCollection = createCollection(
35 persistedCollectionOptions<Todo, string>({
36 id: `todos`,
37 getKey: (todo) => todo.id,
38 persistence,
39 schemaVersion: 1, // Per-collection schema version
40 }),
41)
42```
43
44## Notes
45
46- `createNodeSQLitePersistence` is shared across collections; it resolves
47 mode-specific behavior (`sync-present` vs `sync-absent`) automatically.
48- `schemaVersion` is specified per collection via `persistedCollectionOptions`.
49- Call `database.close()` when your app shuts down.
50
51## Applied transaction pruning
52
53The `applied_tx` log is a replayable cache, so it is pruned by default to keep
54the SQLite file from growing without bound. When you don't pass prune options,
55the node driver applies:
56
57- `appliedTxPruneMaxRows: 1_000` (per-collection row cap)
58- `appliedTxPruneMaxAgeSeconds: 86_400` (24h age backstop)
59
60Pruning runs inside each write transaction, so every collection self-trims on
61its next sync. If a process asks to recover from a point older than the retained
62replay window, recovery falls back to a full reload. Override either value to
63tune retention, or pass `0` to disable that limit:
64
65```ts
66const persistence = createNodeSQLitePersistence({
67 database,
68 appliedTxPruneMaxRows: 5_000, // higher row cap
69 appliedTxPruneMaxAgeSeconds: 0, // disable the age backstop
70})
71```
72
73Pruning removes rows from `applied_tx`, but SQLite may not immediately shrink
74the database file on disk. Use `VACUUM`, `auto_vacuum`, or your own maintenance
75process if you need to reclaim disk space.
76
77The defaults are exported as `DEFAULT_APPLIED_TX_PRUNE_MAX_ROWS` and
78`DEFAULT_APPLIED_TX_PRUNE_MAX_AGE_SECONDS`.