Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

docs(database): list the SQLite index repair migration

Yudhi Armyndharisd9be8d1b75f2
diff --git a/docs/05-database-design.md b/docs/05-database-design.md
index b266ed8c8..50b752117 100644
--- a/docs/05-database-design.md
+++ b/docs/05-database-design.md
@@ -733,6 +733,8 @@ The data connection also owns:
Additionally, the `AddMessagesFts` migration creates the full-text-search structures over `messages` (a FTS5 virtual table on SQLite, a generated `body_ts` `tsvector` column plus GIN index on PostgreSQL) that back the `/search` endpoint.
+On SQLite that index can stop matching `messages` after a table rebuild, and a search then returns other messages. The `RepairSqliteMessageFts` migration checks the index against the full message content once and rebuilds it on a mismatch. With `DATABASE_SYNCHRONIZE=true` the same check runs after the schema sync on every boot; it reads all stored text, and a failure of the check is logged without stopping the boot.
+
> [!NOTE]
> **Tables that do _not_ exist.** Earlier drafts referenced `contacts`, `session_logs`, `webhook_logs`, `api_key_logs`, `webhook_idempotency`, and `ip_whitelist`. None of these are implemented. Contacts are read live from the engine; auditing is the single `audit_logs` table; webhook idempotency is not a persisted table; and per-key IP restrictions are stored inline on `api_keys."allowedIps"` (a `simple-array`), not in a separate `ip_whitelist` table.
@@ -936,7 +938,8 @@ src/database/migrations/ # data connection (pluggable)
├── 1791100000000-AddIntegrationDeliveryFailureDeliveryIndex.ts # (pluginId, instanceId, deliveryId) index for the dead-letter guards
├── 1791200000000-AddWebhookOutboxSessionIndex.ts # (sessionId) index for the per-session outbox delete
├── 1791300000000-BackfillLegacyMessageTypes.ts # converts raw wwebjs message types to the neutral vocabulary, once
-└── 1791400000000-AddLidMappingReportSource.ts # distinguishes mapping reports from cached display data
+├── 1791400000000-AddLidMappingReportSource.ts # distinguishes mapping reports from cached display data
+└── 1791600000000-RepairSqliteMessageFts.ts # rebuilds the SQLite full-text index when it no longer matches messages
```
> [!NOTE]
diff --git a/docs/26-global-search.md b/docs/26-global-search.md
index d757cddb8..b8dad933e 100644
--- a/docs/26-global-search.md
+++ b/docs/26-global-search.md
@@ -213,6 +213,8 @@ Adding search to an existing deployment runs the one-time `1782400000000-AddMess
The migration is safe to re-run (idempotent guards) and has a `down` path that drops the FTS schema on
both dialects. After it applies, search works immediately — no separate reindex command.
+On SQLite the `1791600000000-RepairSqliteMessageFts` migration then compares the index with the full message content and rebuilds it when they differ, which a table rebuild (a schema sync, for one) can cause. A healthy index is left alone. With `DATABASE_SYNCHRONIZE=true` the same check runs after the schema sync on every boot; it reads all stored text, and a failed check is logged and does not stop the boot.
+
---
> See also: [06 - API Specification](./06-api-specification.md) (§6.4.12 Search),