Stores reference

Each backend package exports a create*Store factory you pass into a backends entry of createStore. All backends implement the same per-domain store contracts, so switching backends is a config change, not a code change. The backend type is WaStoreBackend<S, C> — both parameters default to the full domain matrix (every persistence domain plus every cache domain). Every bundled @zapo-js/store-* package ships a full backend; a hand-written partial backend narrows itself with WaStoreBackend<S, C> and createStore() refuses undeclared domains at compile time. See Custom backends.

SQLite

@zapo-js/store-sqlite — createSqliteStore(config).

import { createSqliteStore } from '@zapo-js/store-sqlite'

const sqlite = createSqliteStore({
  path: '.auth/state.sqlite',
  driver: 'auto'
})

Field	Type	Description
`path`	`string`	Database file path. Mutually exclusive with `connection`.
`connection`	`WaSqliteConnection`	Pre-opened connection to reuse. Mutually exclusive with `path`.
`driver`	`WaSqliteDriver`	Driver selection — `'auto'` (default), `'better-sqlite3'`, `'bun'`, `'node'`. Ignored when `connection` is set. See choosing a driver.
`pragmas`	`Record<string, string \| number>`	SQLite pragmas. Ignored when `connection` is set.
`tableNames`	`WaSqliteTableNameOverrides`	Override table names. Ignored when `connection` is set.
`batchSizes`	`WaSqliteBatchSizeSelection`	Tune batch sizes.
`cacheTtlMs`	`{ retryMs?, groupMetadataMs?, chatMetadataMs?, deviceListMs?, messageSecretMs? }`	Cache TTLs.

Provide exactly one of path or connection. With path, the library opens (and ref-counts) its own connection and closes it on store.destroy(). With connection, you own the lifecycle — store.destroy() leaves it open so you can keep using it elsewhere.

Choosing a driver

Since @zapo-js/store-sqlite 1.3.0 the store no longer needs a native addon: better-sqlite3 is an optional peer dependency, and the runtime’s built-in node:sqlite works as a fallback. That makes SQLite persistence available on platforms where the addon can’t be built — Termux, musl without prebuilds, locked-down CI.

`driver`	Requires	Notes
`'better-sqlite3'`	The native addon (build or prebuild)	Fastest row materialization on Node. Does not load under Bun.
`'bun'`	Bun	`bun:sqlite`, ships with the runtime.
`'node'`	Node 22.13+ or Bun 1.4+	`node:sqlite`, ships with the runtime. Node 22.5–22.12 keeps it behind `--experimental-sqlite` and warns while the module is experimental.
`'auto'` (default)	—	`bun:sqlite` under Bun, otherwise `better-sqlite3`, falling back to `node` only when the addon isn’t installed.

Behavior for existing installs is unchanged: with better-sqlite3 present, 'auto' still prefers it and never touches node:sqlite.

On Node 20, 21, or 22.5–22.12 without the flag, node:sqlite does not exist, so 'auto' cannot fall back to it — you get the better-sqlite3 install error, and installing the addon is the real fix there.

The on-disk format is identical across drivers — same schema, same migrations — so you can switch an existing database between them without migrating anything. Write throughput is effectively the same on all three; SQLite itself dominates. node:sqlite is slower only when materializing wide or multi-row result sets, since it builds a fresh object per row: roughly 1.3× on a single wide row and 2.5× on a 50-row page with blobs, measured against better-sqlite3 on Node 22. That cost lands on history/mailbox queries, not on the per-message session writes.

Bring your own connection

Share a single SQLite handle with the rest of your application by opening it yourself with openSqliteConnection and passing it through connection:

import { createStore } from 'zapo-js'
import { createSqliteStore, openSqliteConnection } from '@zapo-js/store-sqlite'

const connection = await openSqliteConnection({
  path: 'app.sqlite',
  sessionId: 'shared',
  pragmas: { journal_mode: 'WAL', synchronous: 'NORMAL' }
})

const store = createStore({
  backends: { sqlite: createSqliteStore({ connection }) },
  providers: {
    auth: 'sqlite',
    signal: 'sqlite',
    preKey: 'sqlite',
    session: 'sqlite',
    identity: 'sqlite',
    senderKey: 'sqlite',
    appState: 'sqlite',
    privacyToken: 'sqlite',
    messages: 'none',
    threads: 'none',
    contacts: 'none'
  }
})

// ... use connection elsewhere in your app ...

await store.destroy()
connection.close() // you opened it, you close it

openSqliteConnection takes the same driver option and follows the same resolution order.

PostgreSQL

@zapo-js/store-postgres — createPostgresStore(config).

import { createPostgresStore } from '@zapo-js/store-postgres'

const postgres = createPostgresStore({
  pool: { connectionString: process.env.DATABASE_URL },
  tablePrefix: 'wa_'
})

Field	Type	Description
`pool`	`Pool \| PoolConfig`	An existing `pg` pool or a pool config. Required.
`tablePrefix`	`string`	Prefix for created tables.
`cacheTtlMs`	object	Cache TTLs (same shape as SQLite).
`cleanup`	`{ intervalMs?, onError? }`	Background cleanup poller.
`batchInsertChunkSize`	`number`	Upper bound on rows per multi-row `INSERT` in batch writes. Default `500`. See Batch insert chunking.

Also exports createPgPool and ensurePgMigrations. Requires the pg peer dependency.

MySQL

@zapo-js/store-mysql — createMysqlStore(config).

import { createMysqlStore } from '@zapo-js/store-mysql'

const mysql = createMysqlStore({
  pool: { uri: process.env.MYSQL_URL },
  tablePrefix: 'wa_'
})

Field	Type	Description
`pool`	`Pool \| PoolOptions`	A `mysql2` pool or options. Required.
`tablePrefix`	`string`	Prefix for created tables.
`cacheTtlMs`	object	Cache TTLs.
`cleanup`	`{ enabled?, intervalMs?, onError? }`	Background cleanup poller.
`batchInsertChunkSize`	`number`	Upper bound on rows per multi-row `INSERT` in batch writes. Default `500`. See Batch insert chunking.

Also exports createMysqlPool and ensureMysqlMigrations. Requires the mysql2 peer dependency.

Batch insert chunking

batchInsertChunkSize caps how many rows the PostgreSQL and MySQL backends fold into a single multi-row INSERT for batch writes — Signal sessions, remote identities, sender-key distributions, prekey generation, and the message/thread/contact upsertBatch paths used by write-behind persistence. The value is rounded down to the nearest power of two internally (500 → 256, 1000 → 512, …), and each batch is decomposed into power-of-two sub-chunks. That keeps the set of distinct prepared statements per connection bounded at log2(chunkSize) + 1 regardless of how N varies between calls — important for staying under the mysql2 client-side cache and MySQL’s max_prepared_stmt_count quota, and for keeping pg’s named statement cache stable. Leave the default unless benchmarks for your workload show it helps. Raise it for steady high-fanout group sends; lower it if your database limits are tight.

createPostgresStore({
  pool: { connectionString: process.env.DATABASE_URL },
  batchInsertChunkSize: 2000 // → effective 1024
})

Redis

@zapo-js/store-redis — createRedisStore(config).

import { createRedisStore } from '@zapo-js/store-redis'

const redis = createRedisStore({
  redis: { host: '127.0.0.1', port: 6379 },
  keyPrefix: 'wa:'
})

Field	Type	Description
`redis`	`Redis \| RedisOptions`	An `ioredis` instance or options. Required.
`keyPrefix`	`string`	Prefix for all keys.
`cacheTtlMs`	object	Cache TTLs.
`storeTtlMs`	object	Opt-in per-domain TTL on the otherwise-persistent stores (see Per-domain store TTL).

Per-domain store TTL

Persistent store domains never expire by default. Set storeTtlMs.<domain>Ms to make Redis prune that domain’s keys automatically — implemented as PEXPIRE on each write, no background cleanup needed. Any domain left unset stays persistent (byte-identical to the previous behavior).

createRedisStore({
  redis: { host: '127.0.0.1', port: 6379 },
  storeTtlMs: {
    messagesMs: 30 * 24 * 60 * 60_000, // drop messages older than 30 days
    sessionMs:   7 * 24 * 60 * 60_000  // drop sessions idle for 7 days
  }
})

Two semantics, by domain kind:

Group	Domains	Refresh on
Data	`messagesMs`, `threadsMs`, `contactsMs`, `privacyTokenMs`	write only — keys expire a fixed window after their last update (history / retention bounding).
Crypto & session	`preKeyMs`, `sessionMs`, `identityMs`, `signalMs`, `senderKeyMs`, `appStateMs`	read and write (sliding) — an actively used session keeps its keys alive, only idle sessions are evicted.

auth has no TTL knob on purpose: expiring login credentials would log the device out. Pick a crypto TTL longer than your worst idle window — an idle session beyond that window evicts the Signal / app-state keys and forces a re-handshake or re-sync. Non-positive ttlMs values are rejected at construction.

Requires the ioredis peer dependency.

MongoDB

@zapo-js/store-mongo — createMongoStore(config).

import { createMongoStore } from '@zapo-js/store-mongo'

const mongo = createMongoStore({
  db: { uri: process.env.MONGO_URL, database: 'zapo' },
  collectionPrefix: 'wa_'
})

Field	Type	Description
`db`	`Db \| { uri, database, options? }`	A `mongodb` `Db` or connection info. Required.
`collectionPrefix`	`string`	Prefix for created collections.
`cacheTtlMs`	object	Cache TTLs.

Requires the mongodb peer dependency. Bulk writes use { ordered: false } so independent upserts run in parallel — a per-document failure does not abort the rest of the batch.

Cache expiry and cleanup

The five cache domains (retry, groupMetadata, chatMetadata, deviceList, messageSecret) carry a TTL set through cacheTtlMs. How expired entries are evicted differs per backend:

Backend	Mechanism	Action required
`memory`	Periodic in-process sweep (interval `min(60s, ttl/2)`, `unref()`-ed timer)	None — automatic
`sqlite`	Filter on read; expired rows are skipped and overwritten on next upsert	None
`postgres`	Filter on read + background poller deletes expired rows	Call `startCleanup(sessionId)`
`mysql`	Filter on read + background poller deletes expired rows	Call `startCleanup(sessionId)`
`redis`	Native key `EXPIRE`	None
`mongo`	TTL index (server-side monitor, ~60s sweep latency)	None

For PostgreSQL and MySQL, without startCleanup your cache tables grow monotonically. Reads still ignore expired rows so stale data is never served, but disk usage climbs forever. Start one poller per session id.

const result = createPostgresStore({
  pool: { connectionString: process.env.DATABASE_URL },
  cleanup: { intervalMs: 60_000, onError: (e) => log.warn('cache cleanup failed', e) }
})

const store = createStore({ backends: { pg: result }, providers: { /* ... */ } })
const client = new WaClient({ store, sessionId: 'default' }, logger)

const poller = result.startCleanup('default')

process.on('SIGTERM', async () => {
  await client.disconnect()
  await result.destroy() // also stops every poller it tracks
})

cleanup.intervalMs defaults to 60_000 (60s). result.destroy() stops every poller started through it, so calling poller.stop() yourself is only useful if you want to halt cleanup before tearing down the backend. For MongoDB, the TTL monitor’s ~60s latency means cache entries can linger past the configured TTL. Acceptable for groupMetadata/deviceList; switch to Redis if you need tighter eviction.

Mixing backends

createStore lets each domain choose a backend by name, so you can combine them:

createStore({
  backends: { redis, postgres },
  providers: {
    auth: 'redis',
    signal: 'redis',
    preKey: 'redis',
    session: 'redis',
    identity: 'redis',
    senderKey: 'redis',
    appState: 'redis',
    privacyToken: 'redis',
    messages: 'postgres',
    threads: 'postgres',
    contacts: 'postgres'
  }
})

Every persistence domain must be listed once backends is set — see Stores for the rule and the accepted values ('<backend>', 'memory', 'none').

Getting started

Core concepts

Guides

Plugins

Reference

Advanced

Reverse engineering

Stores reference

SQLite

Choosing a driver

Bring your own connection

PostgreSQL

MySQL

Batch insert chunking

Redis

Per-domain store TTL

MongoDB

Cache expiry and cleanup

Mixing backends

​SQLite

​Choosing a driver

​Bring your own connection

​PostgreSQL

​MySQL

​Batch insert chunking

​Redis

​Per-domain store TTL

​MongoDB

​Cache expiry and cleanup

​Mixing backends

SQLite

Choosing a driver

Bring your own connection

PostgreSQL

MySQL

Batch insert chunking

Redis

Per-domain store TTL

MongoDB

Cache expiry and cleanup

Mixing backends