Persistent store

​

Choosing a store

• One bot process on a VPS or in a container: SQLiteStore. No server to run, one file to back up.
• Several processes of the same bot (replicas), or state that other services read: RedisStore. Every replica must see the same data, so MemoryStore and SQLiteStore do not fit there. If you already run PostgreSQL, MySQL/MariaDB or MongoDB, the matching store does the same job.
• Always pass a store instance (store: new SQLiteStore({ … })). A string such as store: 'sqlite' is accepted only for compatibility and still creates a MemoryStore.

​

MemoryStore

import { Bot, MemoryStore } from '@botmesh/core'

const bot = new Bot({
  provider,
  store: new MemoryStore({
    file: './store.json',     // optional snapshot
    autoSaveInterval: '1m',   // a duration or ms; 0 disables the timer
    maxMessagesPerChat: 1000, // the default; Infinity removes the cap
  }),
})

​

SQLiteStore

pnpm add @botmesh/sqlite-store better-sqlite3

import { Bot } from '@botmesh/core'
import { BaileysProvider } from '@botmesh/baileys'
import { SQLiteStore } from '@botmesh/sqlite-store'

const bot = new Bot({
  provider: new BaileysProvider({ session: 'my-bot' }),
  store: new SQLiteStore({ file: './data/bot.db' }),
})

​

Installing better-sqlite3

​

Options

​

What it stores

​

Schema versions and upgrades

• Back up the file before upgrading @botmesh/sqlite-store if you may need to roll back.
• When several processes share one file, stop the ones on the old version before a new one opens it.

​

Lifecycle

​

Persistent flows

import { Bot, flow } from '@botmesh/core'
import { SQLiteStore } from '@botmesh/sqlite-store'

const bot = new Bot({ provider, store: new SQLiteStore({ file: './data/bot.db' }) })

bot.use(
  flow('signup')
    .persistent()                 // checkpoint saved after each step
    .ask('What is your name?', 'name')
    .ask('And your email?', 'email')
    .say((_ctx, c) => `Thanks, ${c.state.name}!`),
)

​

RedisStore

pnpm add @botmesh/redis-store redis

import { Bot } from '@botmesh/core'
import { RedisStore } from '@botmesh/redis-store'

const bot = new Bot({
  provider,
  store: new RedisStore({ url: process.env.REDIS_URL, prefix: 'mybot', sessionTtl: '7d' }),
})

​

PostgreSQL, MySQL and MongoDB

pnpm add @botmesh/postgres-store pg      # PostgreSQL
pnpm add @botmesh/mysql-store mysql2     # MySQL 8.x or MariaDB
pnpm add @botmesh/mongo-store mongodb    # MongoDB (driver 6.x or 7.x)

import { PostgresStore } from '@botmesh/postgres-store'
import { MysqlStore } from '@botmesh/mysql-store'
import { MongoStore } from '@botmesh/mongo-store'

const store = new PostgresStore({ connectionString: process.env.DATABASE_URL, tablePrefix: 'mybot_' })
// or: new MysqlStore({ uri: process.env.MYSQL_URL, tablePrefix: 'mybot_' })
// or: new MongoStore({ url: process.env.MONGO_URL, dbName: 'mybot' })

const bot = new Bot({ provider, store, scheduler: { store: store.schedules() } })

​

User data tables

​

Writing your own store

import type { MessageRef } from '@botmesh/core'
import type { IStore, StoredMessage } from '@botmesh/core/spi'

class MyStore implements IStore {
  async start(): Promise<void> { /* connect */ }
  async stop(): Promise<void> { /* disconnect */ }
  async saveMessage(msg: StoredMessage): Promise<void> { /* … */ }
  async getMessage(ref: MessageRef): Promise<StoredMessage | undefined> { /* … */ }
  // …every other required method of IStore
}

• upsertChat / upsertContact shallow-merge onto the stored record. An own field set to undefined unsets that field, so a partial upsert must omit what it does not know. The bot already does: a message without a display name never erases the stored one.
• deleteChat also deletes that chat’s message log.
• getMessagesByChat(chatId, limit) returns the newest limit messages, oldest first (default 50). A limit of 0 or less returns nothing, a fraction rounds up and Infinity returns the whole log. The persistent stores order by timestamp, so re-saving a message with a new timestamp moves it; MemoryStore keeps a re-saved message at the position of its first save.
• saveMessage ignores a message without ref.id or chatId (providers send ref.id: '' when they have no stable id), and getMessage of such a ref resolves undefined. Re-saving an id replaces the stored message.
• maxMessagesPerChat is opt-in in persistent stores. Reject a negative or fractional cap with a RangeError.
• setUserData rejects with a TypeError when the value is not JSON (undefined), and writes nothing.
• Message rows are keyed by messageKey(ref) (from @botmesh/core/spi): {chatId}:{id} with % and : escaped in each part (%25, %3A), so ids that contain : (Twilio’s whatsapp:+1… chat ids) never collide. Rows written under the older unescaped key (legacyMessageKey(ref)) must still be read and deleted, after checking that the row’s stored ref.id and ref.chatId are the requested message, and re-saving moves them to the new key.

• User data (getUserData, setUserData, deleteUserData, listUserData, purgeExpiredUserData): without them ctx.user rejects with UNSUPPORTED_STORE. Check them with test-utils/user-data-conformance.ts.
• Cursors (getCursor/setCursor): they also persist the WELCOME markers and the handoff index.
• Conditional checkpoints (setCheckpointIf/clearCheckpointIf): needed for a safe hand-over between replicas. Without them the bot logs a warning when coordination is on.

​

Docker