Referência de stores

Cada pacote de backend exporta uma factory create*Store que você passa para uma entrada de backends do createStore. Todos os backends implementam os mesmos contratos de store por domínio, então trocar de backend é uma mudança de config, não de código. O tipo do backend é WaStoreBackend<S, C> — os dois parâmetros assumem por padrão a matriz completa de domínios (todo domínio de persistência mais todo domínio de cache). Todo pacote @zapo-js/store-* incluído entrega um backend completo; um backend parcial escrito à mão se estreita com WaStoreBackend<S, C> e o createStore() recusa domínios não declarados em tempo de compilação. Veja Backends customizados.

SQLite

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

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

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

Campo	Tipo	Descrição
`path`	`string`	Caminho do arquivo de banco de dados. Mutuamente exclusivo com `connection`.
`connection`	`WaSqliteConnection`	Connection já aberta para reutilizar. Mutuamente exclusivo com `path`.
`driver`	`WaSqliteDriver`	Seleção do driver — `'auto'` (padrão), `'better-sqlite3'`, `'bun'`, `'node'`. Ignorado quando `connection` é informado. Veja escolhendo um driver.
`pragmas`	`Record<string, string \| number>`	Pragmas do SQLite. Ignorado quando `connection` é informado.
`tableNames`	`WaSqliteTableNameOverrides`	Sobrescreve os nomes das tabelas. Ignorado quando `connection` é informado.
`batchSizes`	`WaSqliteBatchSizeSelection`	Ajusta os tamanhos de lote.
`cacheTtlMs`	`{ retryMs?, groupMetadataMs?, chatMetadataMs?, deviceListMs?, messageSecretMs? }`	TTLs de cache.

Informe exatamente um entre path e connection. Com path, a biblioteca abre (e faz ref-count d)e sua própria connection e a fecha em store.destroy(). Com connection, você é dono do ciclo de vida — store.destroy() mantém a connection aberta para você continuar usando em outros lugares.

Escolhendo um driver

Desde o @zapo-js/store-sqlite 1.3.0 a store não precisa mais de um addon nativo: better-sqlite3 é uma peer dependency opcional, e o módulo embutido node:sqlite do runtime serve de fallback. Isso torna a persistência em SQLite viável em plataformas onde o addon não compila — Termux, musl sem prebuilds, CI travada.

`driver`	Requer	Notas
`'better-sqlite3'`	O addon nativo (build ou prebuild)	Materialização de linhas mais rápida no Node. Não carrega sob Bun.
`'bun'`	Bun	`bun:sqlite`, vem com o runtime.
`'node'`	Node 22.13+ ou Bun 1.4+	`node:sqlite`, vem com o runtime. Node 22.5–22.12 mantém atrás de `--experimental-sqlite` e emite warning enquanto o módulo é experimental.
`'auto'` (padrão)	—	`bun:sqlite` sob Bun, senão `better-sqlite3`, caindo para `node` só quando o addon não está instalado.

O comportamento de instalações existentes não muda: com better-sqlite3 presente, 'auto' continua preferindo-o e nunca toca em node:sqlite.

No Node 20, 21 ou 22.5–22.12 sem a flag, node:sqlite não existe, então 'auto' não consegue cair nele — você recebe o erro de instalação do better-sqlite3, e instalar o addon é a solução real ali.

O formato em disco é idêntico entre os drivers — mesmo schema, mesmas migrations — então você pode trocar o driver de um banco existente sem migrar nada. A vazão de escrita é praticamente a mesma nos três; o próprio SQLite domina. O node:sqlite só é mais lento ao materializar result sets largos ou de várias linhas, já que constrói um objeto novo por linha: cerca de 1,3× numa única linha larga e 2,5× numa página de 50 linhas com blobs, medido contra o better-sqlite3 no Node 22. Esse custo cai nas queries de histórico/mailbox, não nas escritas de sessão por mensagem.

Use sua própria connection

Compartilhe um único handle do SQLite com o resto da sua aplicação abrindo-o você mesmo com openSqliteConnection e passando via 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 a connection em outras partes da sua aplicação ...

await store.destroy()
connection.close() // você abriu, você fecha

openSqliteConnection aceita a mesma opção driver e segue a mesma ordem de resolução.

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_'
})

Campo	Tipo	Descrição
`pool`	`Pool \| PoolConfig`	Um pool `pg` existente ou uma config de pool. Obrigatório.
`tablePrefix`	`string`	Prefixo para as tabelas criadas.
`cacheTtlMs`	object	TTLs de cache (mesmo formato do SQLite).
`cleanup`	`{ intervalMs?, onError? }`	Poller de limpeza em segundo plano.
`batchInsertChunkSize`	`number`	Limite superior de linhas por `INSERT` multi-linha em escritas em lote. Padrão `500`. Veja Chunking de inserts em lote.

Também exporta createPgPool e ensurePgMigrations. Requer a peer dependency pg.

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_'
})

Campo	Tipo	Descrição
`pool`	`Pool \| PoolOptions`	Um pool `mysql2` ou opções. Obrigatório.
`tablePrefix`	`string`	Prefixo para as tabelas criadas.
`cacheTtlMs`	object	TTLs de cache.
`cleanup`	`{ enabled?, intervalMs?, onError? }`	Poller de limpeza em segundo plano.
`batchInsertChunkSize`	`number`	Limite superior de linhas por `INSERT` multi-linha em escritas em lote. Padrão `500`. Veja Chunking de inserts em lote.

Também exporta createMysqlPool e ensureMysqlMigrations. Requer a peer dependency mysql2.

Chunking de inserts em lote

batchInsertChunkSize limita quantas linhas os backends PostgreSQL e MySQL agrupam em um único INSERT multi-linha em escritas em lote — sessões do Signal, identidades remotas, distribuições de sender key, geração de prekeys e os caminhos upsertBatch de message/thread/contact usados pela write-behind persistence. O valor é arredondado para baixo até a potência de dois mais próxima internamente (500 → 256, 1000 → 512, …), e cada lote é decomposto em sub-chunks de potência de dois. Isso mantém o conjunto de prepared statements distintos por conexão limitado a log2(chunkSize) + 1 independentemente de como N varia entre chamadas — importante para ficar abaixo do cache do cliente mysql2 e da quota max_prepared_stmt_count do MySQL, e para manter o cache de statements nomeados do pg estável. Mantenha o padrão a menos que benchmarks do seu workload mostrem benefício. Aumente para envios em grupo de alto fanout sustentados; reduza se os limites do seu banco forem apertados.

createPostgresStore({
  pool: { connectionString: process.env.DATABASE_URL },
  batchInsertChunkSize: 2000 // → efetivo 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:'
})

Campo	Tipo	Descrição
`redis`	`Redis \| RedisOptions`	Uma instância `ioredis` ou opções. Obrigatório.
`keyPrefix`	`string`	Prefixo para todas as chaves.
`cacheTtlMs`	object	TTLs de cache.
`storeTtlMs`	object	TTL opt-in por domínio nos stores normalmente persistentes (veja TTL por domínio do store).

TTL por domínio do store

Domínios de store persistentes nunca expiram por padrão. Defina storeTtlMs.<domínio>Ms para o Redis prunar as chaves daquele domínio automaticamente — implementado como PEXPIRE em cada escrita, sem precisar de cleanup em background. Qualquer domínio deixado de fora permanece persistente (comportamento byte-idêntico ao anterior).

createRedisStore({
  redis: { host: '127.0.0.1', port: 6379 },
  storeTtlMs: {
    messagesMs: 30 * 24 * 60 * 60_000, // descarta mensagens mais antigas que 30 dias
    sessionMs:   7 * 24 * 60 * 60_000  // descarta sessions ociosas por 7 dias
  }
})

Duas semânticas, por tipo de domínio:

Grupo	Domínios	Refresh em
Dados	`messagesMs`, `threadsMs`, `contactsMs`, `privacyTokenMs`	só write — chaves expiram uma janela fixa após a última escrita (limite de histórico / retenção).
Crypto & sessão	`preKeyMs`, `sessionMs`, `identityMs`, `signalMs`, `senderKeyMs`, `appStateMs`	read e write (sliding) — uma sessão ativa mantém as chaves vivas, só sessões ociosas são evictadas.

auth não tem botão de TTL de propósito: expirar credenciais de login deslogaria o device. Escolha um TTL de crypto maior que sua pior janela de ociosidade — uma sessão ociosa além dessa janela evicta as chaves de Signal / app-state e força um novo handshake ou re-sync. Valores ttlMs não-positivos são rejeitados na construção.

Requer a peer dependency ioredis.

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_'
})

Campo	Tipo	Descrição
`db`	`Db \| { uri, database, options? }`	Um `Db` do `mongodb` ou informações de conexão. Obrigatório.
`collectionPrefix`	`string`	Prefixo para as collections criadas.
`cacheTtlMs`	object	TTLs de cache.

Requer a peer dependency mongodb. Escritas em lote usam { ordered: false } para que upserts independentes rodem em paralelo — uma falha por documento não aborta o resto do lote.

Expiração e limpeza de cache

Os cinco domínios de cache (retry, groupMetadata, chatMetadata, deviceList, messageSecret) usam um TTL definido em cacheTtlMs. A forma como entradas expiradas são removidas varia por backend:

Backend	Mecanismo	Ação necessária
`memory`	Sweep periódico in-process (intervalo `min(60s, ttl/2)`, timer com `unref()`)	Nenhuma — automático
`sqlite`	Filtro na leitura; linhas expiradas são ignoradas e sobrescritas no próximo upsert	Nenhuma
`postgres`	Filtro na leitura + poller de fundo apaga linhas expiradas	Chamar `startCleanup(sessionId)`
`mysql`	Filtro na leitura + poller de fundo apaga linhas expiradas	Chamar `startCleanup(sessionId)`
`redis`	`EXPIRE` nativo de chave	Nenhuma
`mongo`	TTL index (monitor server-side, latência de ~60s)	Nenhuma

No PostgreSQL e MySQL, sem startCleanup suas tabelas de cache crescem monotonicamente. Leituras continuam ignorando linhas expiradas (dado obsoleto nunca é servido), mas o uso de disco cresce sem limite. Inicie um poller por 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() // também para todos os pollers que ele rastreia
})

cleanup.intervalMs tem default 60_000 (60s). result.destroy() para todos os pollers iniciados por ele, então chamar poller.stop() manualmente só é útil se você quiser interromper a limpeza antes de derrubar o backend. No MongoDB, a latência de ~60s do TTL monitor faz entradas de cache poderem persistir um pouco além do TTL configurado. Aceitável para groupMetadata/deviceList; troque pelo Redis se precisar de eviction mais agressivo.

Misturando backends

O createStore permite que cada domínio escolha um backend por nome, então você pode combiná-los:

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'
  }
})

Todo domínio de persistência deve ser listado quando backends é definido — veja Stores para a regra e os valores aceitos ('<backend>', 'memory', 'none').

Primeiros passos

Conceitos

Guias

Plugins

Referência

Avançado

Engenharia reversa

Referência de stores

SQLite

Escolhendo um driver

Use sua própria connection

PostgreSQL

MySQL

Chunking de inserts em lote

Redis

TTL por domínio do store

MongoDB

Expiração e limpeza de cache

Misturando backends

​SQLite

​Escolhendo um driver

​Use sua própria connection

​PostgreSQL

​MySQL

​Chunking de inserts em lote

​Redis

​TTL por domínio do store

​MongoDB

​Expiração e limpeza de cache

​Misturando backends

SQLite

Escolhendo um driver

Use sua própria connection

PostgreSQL

MySQL

Chunking de inserts em lote

Redis

TTL por domínio do store

MongoDB

Expiração e limpeza de cache

Misturando backends