Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

perf(baileys): trim the message store cap with an index walk

Yudhi Armyndharisc07c71b229d5
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index dac255f8b..489894bb6 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -857,7 +857,8 @@ src/database/migrations/ # data connection (pluggable)
├── 1785800000000-AddSessionOwnership.ts
├── 1785900000000-AddAutomationRules.ts # 14th migration table; FKs sessions ON DELETE CASCADE
├── 1786000000000-AddSessionNodeUrl.ts
-└── 1786100000000-AddMessageMediaPathIndex.ts # partial index on messages.mediaPath (orphan sweep)
+├── 1786100000000-AddMessageMediaPathIndex.ts # partial index on messages.mediaPath (orphan sweep)
+└── 1786800000000-AddBaileysStoredMessagesSessionCreatedIdIndex.ts # (sessionId, createdAt, id) index for the Baileys store cap trim
```
> [!NOTE]
diff --git a/src/database/migrations/1786800000000-AddBaileysStoredMessagesSessionCreatedIdIndex.ts b/src/database/migrations/1786800000000-AddBaileysStoredMessagesSessionCreatedIdIndex.ts
new file mode 100644
index 000000000..525dc0d53
--- /dev/null
+++ b/src/database/migrations/1786800000000-AddBaileysStoredMessagesSessionCreatedIdIndex.ts
@@ -0,0 +1,42 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Replaces `baileys_stored_messages (sessionId, createdAt)` with `(sessionId, createdAt, id)`.
+ *
+ * Every stored Baileys message runs the per-session cap trim, which finds the cutoff row ordered by
+ * `createdAt DESC, id DESC` and then deletes everything at or below it by `(createdAt, id)`. Without
+ * `id` in the index SQLite sorts the session's rows in a temp B-tree for the cutoff on every write;
+ * with it both statements walk the index. The new index's leading columns serve every query the old
+ * one did, so the old one is dropped.
+ *
+ * Hand-authored because `synchronize` is off for the data connection on PostgreSQL. The name matches
+ * the entity's @Index so the synchronize and migration schema paths converge. IF [NOT] EXISTS on
+ * both dialects keeps it idempotent.
+ */
+export class AddBaileysStoredMessagesSessionCreatedIdIndex1786800000000 implements MigrationInterface {
+ name = 'AddBaileysStoredMessagesSessionCreatedIdIndex1786800000000';
+
+ public async up(queryRunner: QueryRunner): Promise<void> {
+ // Lift the runtime statement_timeout for this transaction only, as AddMessageMediaPathIndex does.
+ if (queryRunner.dataSource.options.type === 'postgres') {
+ await queryRunner.query('SET LOCAL statement_timeout = 0');
+ }
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS "IDX_baileys_stored_messages_session_created_id" ON "baileys_stored_messages" ("sessionId", "createdAt", "id")`,
+ );
+ await queryRunner.query(`DROP INDEX IF EXISTS "IDX_baileys_stored_messages_session_created"`);
+ // The entity's former unnamed (sessionId, createdAt) index, present only where synchronize built
+ // the table; the new index covers it.
+ await queryRunner.query(`DROP INDEX IF EXISTS "IDX_ae44b476c522450bd395615a7c"`);
+ }
+
+ public async down(queryRunner: QueryRunner): Promise<void> {
+ if (queryRunner.dataSource.options.type === 'postgres') {
+ await queryRunner.query('SET LOCAL statement_timeout = 0');
+ }
+ await queryRunner.query(
+ `CREATE INDEX IF NOT EXISTS "IDX_baileys_stored_messages_session_created" ON "baileys_stored_messages" ("sessionId", "createdAt")`,
+ );
+ await queryRunner.query(`DROP INDEX IF EXISTS "IDX_baileys_stored_messages_session_created_id"`);
+ }
+}
diff --git a/src/database/migrations/__tests__/1786800000000-AddBaileysStoredMessagesSessionCreatedIdIndex.spec.ts b/src/database/migrations/__tests__/1786800000000-AddBaileysStoredMessagesSessionCreatedIdIndex.spec.ts
new file mode 100644
index 000000000..0da9db7ab
--- /dev/null
+++ b/src/database/migrations/__tests__/1786800000000-AddBaileysStoredMessagesSessionCreatedIdIndex.spec.ts
@@ -0,0 +1,83 @@
+import { DataSource } from 'typeorm';
+import { AddBaileysStoredMessagesSessionCreatedIdIndex1786800000000 } from '../1786800000000-AddBaileysStoredMessagesSessionCreatedIdIndex';
+
+describe('AddBaileysStoredMessagesSessionCreatedIdIndex migration', () => {
+ let ds: DataSource;
+ const OLD = 'IDX_baileys_stored_messages_session_created';
+ const NEW = 'IDX_baileys_stored_messages_session_created_id';
+
+ beforeEach(async () => {
+ ds = new DataSource({ type: 'better-sqlite3', database: ':memory:' });
+ await ds.initialize();
+ // The table and indexes as AddBaileysStoredMessages created them.
+ await ds.query(
+ `CREATE TABLE "baileys_stored_messages" ("id" varchar PRIMARY KEY NOT NULL, "sessionId" varchar NOT NULL, ` +
+ `"waMessageId" varchar NOT NULL, "serializedMessage" text NOT NULL, "createdAt" datetime NOT NULL DEFAULT (datetime('now')))`,
+ );
+ await ds.query(
+ `CREATE UNIQUE INDEX "UQ_baileys_stored_messages_session_wamsg" ON "baileys_stored_messages" ("sessionId", "waMessageId")`,
+ );
+ await ds.query(`CREATE INDEX "${OLD}" ON "baileys_stored_messages" ("sessionId", "createdAt")`);
+ });
+
+ afterEach(async () => {
+ await ds.destroy();
+ });
+
+ const indexNames = async (): Promise<string[]> => {
+ const rows = await ds.query<{ name: string }[]>(`PRAGMA index_list("baileys_stored_messages")`);
+ return rows.map(r => r.name);
+ };
+ const plan = async (sql: string): Promise<string> =>
+ (await ds.query<{ detail: string }[]>(`EXPLAIN QUERY PLAN ${sql}`)).map(r => r.detail).join(' | ');
+
+ // The cap trim's cutoff lookup (BaileysMessageStoreService.enforceLimit).
+ const cutoffQuery =
+ `SELECT "id", "createdAt" FROM "baileys_stored_messages" WHERE "sessionId" = 's1' ` +
+ `ORDER BY "createdAt" DESC, "id" DESC LIMIT 1 OFFSET 5000`;
+
+ it('replaces the (sessionId, createdAt) index with (sessionId, createdAt, id)', async () => {
+ await new AddBaileysStoredMessagesSessionCreatedIdIndex1786800000000().up(ds.createQueryRunner());
+
+ const names = await indexNames();
+ expect(names).toContain(NEW);
+ expect(names).not.toContain(OLD);
+ const columns = await ds.query<{ name: string }[]>(`PRAGMA index_info("${NEW}")`);
+ expect(columns.map(c => c.name)).toEqual(['sessionId', 'createdAt', 'id']);
+ });
+
+ it('drops the redundant unnamed (sessionId, createdAt) index a synchronized table carries', async () => {
+ await ds.query(
+ `CREATE INDEX "IDX_ae44b476c522450bd395615a7c" ON "baileys_stored_messages" ("sessionId", "createdAt")`,
+ );
+
+ await new AddBaileysStoredMessagesSessionCreatedIdIndex1786800000000().up(ds.createQueryRunner());
+
+ expect(await indexNames()).not.toContain('IDX_ae44b476c522450bd395615a7c');
+ });
+
+ it('is idempotent, and down() restores the old index', async () => {
+ const runner = ds.createQueryRunner();
+ const migration = new AddBaileysStoredMessagesSessionCreatedIdIndex1786800000000();
+
+ await migration.up(runner);
+ await expect(migration.up(runner)).resolves.toBeUndefined();
+
+ await migration.down(runner);
+ await expect(migration.down(runner)).resolves.toBeUndefined();
+ const names = await indexNames();
+ expect(names).toContain(OLD);
+ expect(names).not.toContain(NEW);
+ });
+
+ it('serves the cap cutoff from the index without a sort', async () => {
+ // Baseline: the old index leaves the id tiebreak to a temp B-tree.
+ expect(await plan(cutoffQuery)).toContain('TEMP B-TREE');
+
+ await new AddBaileysStoredMessagesSessionCreatedIdIndex1786800000000().up(ds.createQueryRunner());
+
+ const after = await plan(cutoffQuery);
+ expect(after).toContain(`COVERING INDEX ${NEW}`);
+ expect(after).not.toContain('TEMP B-TREE');
+ });
+});
diff --git a/src/database/migrations/__tests__/__fixtures__/known-migration-drift.json b/src/database/migrations/__tests__/__fixtures__/known-migration-drift.json
index 3f2b9037c..eb07675c9 100644
--- a/src/database/migrations/__tests__/__fixtures__/known-migration-drift.json
+++ b/src/database/migrations/__tests__/__fixtures__/known-migration-drift.json
@@ -1,12 +1,12 @@
{
"data": [
- "DROP INDEX \"IDX_baileys_stored_messages_session_created\"",
+ "DROP INDEX \"IDX_baileys_stored_messages_session_created_id\"",
"DROP INDEX \"UQ_baileys_stored_messages_session_wamsg\"",
"CREATE TABLE \"temporary_baileys_stored_messages\" (\"id\" varchar PRIMARY KEY NOT NULL, \"sessionId\" varchar NOT NULL, \"waMessageId\" varchar NOT NULL, \"serializedMessage\" text NOT NULL, \"createdAt\" datetime NOT NULL DEFAULT (datetime('now')))",
"INSERT INTO \"temporary_baileys_stored_messages\"(\"id\", \"sessionId\", \"waMessageId\", \"serializedMessage\", \"createdAt\") SELECT \"id\", \"sessionId\", \"waMessageId\", \"serializedMessage\", \"createdAt\" FROM \"baileys_stored_messages\"",
"DROP TABLE \"baileys_stored_messages\"",
"ALTER TABLE \"temporary_baileys_stored_messages\" RENAME TO \"baileys_stored_messages\"",
- "CREATE INDEX \"IDX_baileys_stored_messages_session_created\" ON \"baileys_stored_messages\" (\"sessionId\", \"createdAt\") ",
+ "CREATE INDEX \"IDX_baileys_stored_messages_session_created_id\" ON \"baileys_stored_messages\" (\"sessionId\", \"createdAt\", \"id\") ",
"CREATE UNIQUE INDEX \"UQ_baileys_stored_messages_session_wamsg\" ON \"baileys_stored_messages\" (\"sessionId\", \"waMessageId\") ",
"DROP INDEX \"IDX_templates_session_name\"",
"DROP INDEX \"IDX_templates_sessionId\"",
@@ -22,9 +22,8 @@
"DROP TABLE \"automation_rules\"",
"ALTER TABLE \"temporary_automation_rules\" RENAME TO \"automation_rules\"",
"CREATE INDEX \"IDX_automation_rules_sessionId\" ON \"automation_rules\" (\"sessionId\") ",
- "DROP INDEX \"IDX_baileys_stored_messages_session_created\"",
- "DROP INDEX \"UQ_baileys_stored_messages_session_wamsg\"",
"DROP INDEX \"IDX_lid_mappings_phone\"",
+ "DROP INDEX \"UQ_baileys_stored_messages_session_wamsg\"",
"DROP INDEX \"IDX_templates_sessionId\"",
"DROP INDEX \"IDX_status_updates_expiresAt\"",
"DROP INDEX \"UQ_status_updates_sessionId_waStatusId\"",
@@ -69,19 +68,18 @@
"CREATE INDEX \"IDX_ingress_events_dispatchState\" ON \"ingress_events\" (\"dispatchState\", \"createdAt\") ",
"CREATE INDEX \"IDX_ingress_events_createdAt\" ON \"ingress_events\" (\"createdAt\") ",
"CREATE UNIQUE INDEX \"UQ_ingress_events_instance_delivery\" ON \"ingress_events\" (\"pluginId\", \"instanceId\", \"providerDeliveryId\") ",
- "CREATE INDEX \"IDX_ae44b476c522450bd395615a7c\" ON \"baileys_stored_messages\" (\"sessionId\", \"createdAt\") ",
- "CREATE UNIQUE INDEX \"IDX_1bb396e881628cd4dc8f0d2a8b\" ON \"baileys_stored_messages\" (\"sessionId\", \"waMessageId\") ",
"CREATE INDEX \"IDX_1e39479a7a8aa37eab08df013b\" ON \"lid_mappings\" (\"phone\") ",
+ "CREATE UNIQUE INDEX \"IDX_1bb396e881628cd4dc8f0d2a8b\" ON \"baileys_stored_messages\" (\"sessionId\", \"waMessageId\") ",
"CREATE INDEX \"IDX_951ec734b350580529e0b7ab2d\" ON \"status_updates\" (\"expiresAt\") ",
"CREATE UNIQUE INDEX \"IDX_1152eee4d077ae74396d73c1fb\" ON \"status_updates\" (\"sessionId\", \"waStatusId\") ",
"CREATE INDEX \"IDX_432ae5ea12bbda479dcae30fb1\" ON \"status_updates\" (\"sessionId\", \"contactJid\") ",
- "DROP INDEX \"IDX_ae44b476c522450bd395615a7c\"",
+ "DROP INDEX \"IDX_baileys_stored_messages_session_created_id\"",
"DROP INDEX \"IDX_1bb396e881628cd4dc8f0d2a8b\"",
"CREATE TABLE \"temporary_baileys_stored_messages\" (\"id\" varchar PRIMARY KEY NOT NULL, \"sessionId\" varchar NOT NULL, \"waMessageId\" varchar NOT NULL, \"serializedMessage\" text NOT NULL, \"createdAt\" datetime NOT NULL DEFAULT (datetime('now')), CONSTRAINT \"FK_55c1dfd945d2c552a5313b25460\" FOREIGN KEY (\"sessionId\") REFERENCES \"sessions\" (\"id\") ON DELETE CASCADE ON UPDATE NO ACTION)",
"INSERT INTO \"temporary_baileys_stored_messages\"(\"id\", \"sessionId\", \"waMessageId\", \"serializedMessage\", \"createdAt\") SELECT \"id\", \"sessionId\", \"waMessageId\", \"serializedMessage\", \"createdAt\" FROM \"baileys_stored_messages\"",
"DROP TABLE \"baileys_stored_messages\"",
"ALTER TABLE \"temporary_baileys_stored_messages\" RENAME TO \"baileys_stored_messages\"",
- "CREATE INDEX \"IDX_ae44b476c522450bd395615a7c\" ON \"baileys_stored_messages\" (\"sessionId\", \"createdAt\") ",
+ "CREATE INDEX \"IDX_baileys_stored_messages_session_created_id\" ON \"baileys_stored_messages\" (\"sessionId\", \"createdAt\", \"id\") ",
"CREATE UNIQUE INDEX \"IDX_1bb396e881628cd4dc8f0d2a8b\" ON \"baileys_stored_messages\" (\"sessionId\", \"waMessageId\") ",
"DROP INDEX \"IDX_templates_session_name\"",
"CREATE TABLE \"temporary_templates\" (\"id\" varchar PRIMARY KEY NOT NULL, \"sessionId\" varchar NOT NULL, \"name\" varchar(100) NOT NULL, \"body\" text NOT NULL, \"header\" text, \"footer\" text, \"createdAt\" datetime NOT NULL DEFAULT (datetime('now')), \"updatedAt\" datetime NOT NULL DEFAULT (datetime('now')), CONSTRAINT \"FK_53208331c90e332d3f13780729c\" FOREIGN KEY (\"sessionId\") REFERENCES \"sessions\" (\"id\") ON DELETE CASCADE ON UPDATE NO ACTION)",
diff --git a/src/database/migrations/__tests__/migration-drift.spec.ts b/src/database/migrations/__tests__/migration-drift.spec.ts
index eba182891..d7edccacb 100644
--- a/src/database/migrations/__tests__/migration-drift.spec.ts
+++ b/src/database/migrations/__tests__/migration-drift.spec.ts
@@ -86,7 +86,7 @@ const tally = (statements: string[]): Map<string, number> =>
statements.reduce((counts, sql) => counts.set(sql, (counts.get(sql) ?? 0) + 1), new Map<string, number>());
/**
- * Compared as a MULTISET, not a set. 32 of the 95 data statements are repeats (the rebuild cycle
+ * Compared as a MULTISET, not a set. 32 of the 93 data statements are repeats (the rebuild cycle
* drops and recreates the same index on more than one table pass), so a set comparison would pass a
* change that only alters HOW MANY times a statement is emitted: one rebuild pass appearing or
* disappearing leaves the distinct-statement list identical. Counting catches that.
diff --git a/src/engine/adapters/baileys-message-store.service.spec.ts b/src/engine/adapters/baileys-message-store.service.spec.ts
index 3bb1df340..35f0c3b4c 100644
--- a/src/engine/adapters/baileys-message-store.service.spec.ts
+++ b/src/engine/adapters/baileys-message-store.service.spec.ts
@@ -1,5 +1,5 @@
import type { WAMessage } from '@whiskeysockets/baileys';
-import { DataSource, Repository } from 'typeorm';
+import { DataSource, DeleteQueryBuilder, Repository } from 'typeorm';
import { BaileysStoredMessage } from './baileys-stored-message.entity';
import { BaileysMessageStoreService } from './baileys-message-store.service';
import { Session, SessionStatus } from '../../modules/session/entities/session.entity';
@@ -182,6 +182,35 @@ describe('BaileysMessageStoreService', () => {
expect(await s.getMessage('s2', 'T4')).not.toBeNull();
});
+ it('evicts same-createdAt rows by id at the cap and bounds the trim delete by the index', async () => {
+ process.env.BAILEYS_MESSAGE_STORE_LIMIT = '3';
+ await seedSession('s3');
+ const s = new BaileysMessageStoreService(repo);
+ const sharedTs = new Date('2024-01-01T00:00:00.000Z');
+ for (const id of ['a', 'b', 'c', 'd']) {
+ await repo.save(
+ repo.create({ id, sessionId: 's3', waMessageId: `W${id}`, serializedMessage: '{}', createdAt: sharedTs }),
+ );
+ }
+ // Pass-through spy: records the SQL every delete builder runs.
+ const spy = jest.spyOn(DeleteQueryBuilder.prototype, 'getQueryAndParameters');
+
+ await s.put('s3', msg('NEW'));
+ const deletes = spy.mock.results.map(r => r.value as [string, unknown[]]);
+ spy.mockRestore();
+
+ // The newest row and the two highest ids of the tied run survive.
+ const left = await repo.find({ where: { sessionId: 's3' }, order: { id: 'ASC' } });
+ expect(left.map(r => r.waMessageId).sort()).toEqual(['NEW', 'Wc', 'Wd']);
+ // The range delete must be bounded by (createdAt, id) on the index, not walk the whole session.
+ expect(deletes).toHaveLength(1);
+ const [sql, params] = deletes[0];
+ const detail = (await ds.query<{ detail: string }[]>(`EXPLAIN QUERY PLAN ${sql}`, params))
+ .map(r => r.detail)
+ .join(' | ');
+ expect(detail).toMatch(/IDX_baileys_stored_messages_session_created_id \(sessionId=\? AND \(createdAt,id\)/);
+ });
+
// Issue #319 — an orphaned adapter (its session was deleted/recreated during reconnect
// churn) keeps receiving messages.upsert and calls put() under a sessionId that no longer
// has a parent row. The FK then fails (SQLITE_CONSTRAINT in prod) on EVERY message, the
diff --git a/src/engine/adapters/baileys-message-store.service.ts b/src/engine/adapters/baileys-message-store.service.ts
index b95a77b18..20a126f4a 100644
--- a/src/engine/adapters/baileys-message-store.service.ts
+++ b/src/engine/adapters/baileys-message-store.service.ts
@@ -216,7 +216,9 @@ export class BaileysMessageStoreService implements BaileysMessageStore {
.createQueryBuilder()
.delete()
.where('sessionId = :sessionId', { sessionId })
- .andWhere('(createdAt < :createdAt OR (createdAt = :createdAt AND id <= :id))', { createdAt, id })
+ // Row-value form, not `createdAt < c OR (createdAt = c AND id <= i)`: same rows, but the OR keeps
+ // the planner from bounding the range, so it walked every row of the session on each write.
+ .andWhere('(createdAt, id) <= (:createdAt, :id)', { createdAt, id })
.execute();
}
}
diff --git a/src/engine/adapters/baileys-stored-message.entity.ts b/src/engine/adapters/baileys-stored-message.entity.ts
index 7116d2e5b..b69ee445a 100644
--- a/src/engine/adapters/baileys-stored-message.entity.ts
+++ b/src/engine/adapters/baileys-stored-message.entity.ts
@@ -11,7 +11,8 @@ import { Session } from '../../modules/session/entities/session.entity';
*/
@Entity('baileys_stored_messages')
@Index(['sessionId', 'waMessageId'], { unique: true }) // lookup + dedup (send-return vs upsert echo)
-@Index(['sessionId', 'createdAt']) // eviction ordering
+// Eviction ordering: the cap trim's cutoff lookup and range delete both walk (createdAt, id).
+@Index('IDX_baileys_stored_messages_session_created_id', ['sessionId', 'createdAt', 'id'])
export class BaileysStoredMessage {
@PrimaryGeneratedColumn('uuid')
id!: string;