Skip to content

Free, Open Source, Self-Hosted WhatsApp API Gateway

fix(search): skip FTS schema DDL at boot when it already exists

Yudhi Armyndharis713a0f57406c
diff --git a/src/modules/search/providers/builtin-fts.provider.postgres.spec.ts b/src/modules/search/providers/builtin-fts.provider.postgres.spec.ts
index 8696eda6b..5864ed145 100644
--- a/src/modules/search/providers/builtin-fts.provider.postgres.spec.ts
+++ b/src/modules/search/providers/builtin-fts.provider.postgres.spec.ts
@@ -15,6 +15,8 @@ import { BuiltInFtsProvider } from './builtin-fts.provider';
interface ProbeScript {
/** Whether the active schema's `messages` carries the generated `body_ts` column. */
bodyTsPresent?: boolean;
+ /** Whether that table carries the GIN index; defaults to bodyTsPresent. */
+ indexPresent?: boolean;
/** When set, the probe query itself rejects (degraded pool / mid-recovery state). */
probeError?: Error;
/** When set, the boot-time ensure DDL rejects, leaving the availability cache unprimed. */
@@ -26,6 +28,10 @@ function makePostgresDataSource(script: ProbeScript) {
const state: ProbeScript = { ...script };
const query = jest.fn((sql: string) => {
const s = String(sql);
+ // The boot-time ensure reads the column and the index in one catalog query.
+ if (/AS col,[\s\S]*AS idx/.test(s)) {
+ return Promise.resolve([{ col: !!state.bodyTsPresent, idx: state.indexPresent ?? !!state.bodyTsPresent }]);
+ }
if (/to_regclass\('messages'\)/.test(s)) {
if (state.probeError) return Promise.reject(state.probeError);
return Promise.resolve(state.bodyTsPresent ? [{ attname: 'body_ts' }] : []);
@@ -100,7 +106,7 @@ describe('BuiltInFtsProvider (postgres probe)', () => {
// ensure can die on a transient error even though the column already exists (e.g. GIN index
// build raced a statement timeout). The probe must read the active schema's real state and keep
// search available — same decision a healthy boot would have cached.
- const { ds } = makePostgresDataSource({ bodyTsPresent: true, failEnsure: true });
+ const { ds } = makePostgresDataSource({ bodyTsPresent: true, indexPresent: false, failEnsure: true });
const provider = new BuiltInFtsProvider(ds);
await provider.onModuleInit();
@@ -109,6 +115,33 @@ describe('BuiltInFtsProvider (postgres probe)', () => {
expect((await provider.health()).ok).toBe(true);
});
+ it('issues no DDL at boot when the column and the index already exist (no table lock on migrated databases)', async () => {
+ const { ds, query } = makePostgresDataSource({ bodyTsPresent: true });
+ const provider = new BuiltInFtsProvider(ds);
+ await provider.onModuleInit();
+
+ expect(sqlOf(query).some(q => /ALTER TABLE|CREATE INDEX/.test(q))).toBe(false);
+ expect((await provider.health()).ok).toBe(true);
+ });
+
+ it('creates only the index when the column exists but the index is missing', async () => {
+ const { ds, query } = makePostgresDataSource({ bodyTsPresent: true, indexPresent: false });
+ await new BuiltInFtsProvider(ds).onModuleInit();
+
+ const calls = sqlOf(query);
+ expect(calls.some(q => /ALTER TABLE/.test(q))).toBe(false);
+ expect(calls.filter(q => /CREATE INDEX IF NOT EXISTS "idx_messages_body_ts"/.test(q))).toHaveLength(1);
+ });
+
+ it('creates the column and the index when neither exists', async () => {
+ const { ds, query } = makePostgresDataSource({ bodyTsPresent: false });
+ await new BuiltInFtsProvider(ds).onModuleInit();
+
+ const calls = sqlOf(query);
+ expect(calls.filter(q => /ALTER TABLE "messages" ADD COLUMN IF NOT EXISTS "body_ts"/.test(q))).toHaveLength(1);
+ expect(calls.filter(q => /CREATE INDEX IF NOT EXISTS "idx_messages_body_ts"/.test(q))).toHaveLength(1);
+ });
+
it('a probe error fails closed (501/unhealthy, never a raw 500) and is NOT cached — a later probe recovers', async () => {
const { ds, state } = makePostgresDataSource({ probeError: new Error('connection reset') });
const provider = new BuiltInFtsProvider(ds);
diff --git a/src/modules/search/providers/builtin-fts.provider.ts b/src/modules/search/providers/builtin-fts.provider.ts
index 29d08b808..20d5f9a2f 100644
--- a/src/modules/search/providers/builtin-fts.provider.ts
+++ b/src/modules/search/providers/builtin-fts.provider.ts
@@ -51,7 +51,8 @@ export class BuiltInFtsProvider implements SearchProvider, OnModuleInit {
* the entity but NEVER runs migrations — so the migration that establishes `messages_fts` /
* `body_ts` is skipped and search would 501 on a fresh SQLite box. This re-applies the same
* idempotent DDL as the migration (1782400000000-AddMessagesFts); `IF NOT EXISTS` / `IF NOT` guards
- * make it a no-op once the schema exists, so migrations-based deployments are unaffected. Probes the
+ * make it a no-op once the schema exists, and on Postgres no DDL is issued at all when the catalog
+ * already holds the column and index, so migrations-based deployments take no table lock. Probes the
* result into `ftsAvailable` so the first search() / health() call doesn't re-probe.
*/
async onModuleInit(): Promise<void> {
@@ -132,7 +133,10 @@ export class BuiltInFtsProvider implements SearchProvider, OnModuleInit {
/**
* Creates the FTS schema if missing. Mirrors migration 1782400000000-AddMessagesFts verbatim and is
* idempotent (every statement is `IF NOT EXISTS` / `IF NOT`), so:
- * - migrations-based deployments: the migration has already run; this is a set of no-ops.
+ * - migrations-based deployments: the migration has already run; SQLite runs a set of no-ops,
+ * and Postgres reads the catalog and issues no DDL, because `ALTER TABLE ... IF NOT EXISTS`
+ * still queues for ACCESS EXCLUSIVE on `messages` before it finds the column, stalling every
+ * message read and write behind any open transaction.
* - synchronize-based deployments (dev compose / zero-config first boot): migrations are skipped,
* so this is what actually brings the index up at boot. Without it search 501s on every fresh
* SQLite box, contradicting docs/26's "zero-config, on by default" promise.
@@ -142,12 +146,22 @@ export class BuiltInFtsProvider implements SearchProvider, OnModuleInit {
private async ensureFtsSchema(): Promise<boolean> {
const isPostgres = this.dataSource.options.type === 'postgres';
if (isPostgres) {
- await this.dataSource.query(
- `ALTER TABLE "messages" ADD COLUMN IF NOT EXISTS "body_ts" tsvector GENERATED ALWAYS AS (to_tsvector('simple', coalesce(body, ''))) STORED`,
- );
- await this.dataSource.query(
- `CREATE INDEX IF NOT EXISTS "idx_messages_body_ts" ON "messages" USING GIN ("body_ts")`,
+ // Uncached on purpose (probeFts caches and swallows errors). Both objects are looked up on the
+ // table to_regclass resolves, the same one the runtime queries hit; only a missing one is created.
+ const rows: Array<{ col: boolean; idx: boolean }> = await this.dataSource.query(
+ `SELECT EXISTS (SELECT 1 FROM pg_attribute a WHERE a.attrelid = to_regclass('messages') AND a.attname = 'body_ts' AND NOT a.attisdropped) AS col,
+ EXISTS (SELECT 1 FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid WHERE i.indrelid = to_regclass('messages') AND c.relname = 'idx_messages_body_ts') AS idx`,
);
+ if (!rows[0]?.col) {
+ await this.dataSource.query(
+ `ALTER TABLE "messages" ADD COLUMN IF NOT EXISTS "body_ts" tsvector GENERATED ALWAYS AS (to_tsvector('simple', coalesce(body, ''))) STORED`,
+ );
+ }
+ if (!rows[0]?.idx) {
+ await this.dataSource.query(
+ `CREATE INDEX IF NOT EXISTS "idx_messages_body_ts" ON "messages" USING GIN ("body_ts")`,
+ );
+ }
return true;
}
// SQLite: probe FTS5 first; skip leaving any schema if this build lacks it.