@strav/search 0.4.31 → 1.0.0-alpha.31

package/src/drivers/postgres/postgres_fts_driver.ts

@@ -1,184 +1,542 @@
-import type { SQL } from 'bun'
+/**
+ * `PostgresFtsDriver` — `SearchEngine` backed by Postgres
+ * `tsvector` + GIN, one table per index inside a dedicated
+ * schema (`strav_search` by default).
+ *
+ * What the driver provisions for each `createIndex(name, …)`:
+ *
+ *   ```
+ *   CREATE TABLE "strav_search"."<name>" (
+ *     id        text PRIMARY KEY,
+ *     tenant_id text,                    -- nullable for single-tenant apps
+ *     document  jsonb NOT NULL,
+ *     fts       tsvector NOT NULL
+ *   );
+ *   CREATE INDEX "<name>_fts"    ON … USING GIN(fts);
+ *   CREATE INDEX "<name>_tenant" ON … (tenant_id) WHERE tenant_id IS NOT NULL;
+ *   -- Per filterable / sortable attribute:
+ *   CREATE INDEX "<name>_<attr>" ON … ((document->>'<attr>'));
+ *   -- RLS on `tenant_id`:
+ *   ALTER TABLE … ENABLE ROW LEVEL SECURITY;
+ *   ALTER TABLE … FORCE ROW LEVEL SECURITY;
+ *   CREATE POLICY "<name>_isolate" ON …
+ *     USING (tenant_id IS NULL OR tenant_id = current_setting('app.tenant_id', true));
+ *   ```
+ *
+ * Settings (search/filter/sort attributes, primary key,
+ * language) live in `strav_search._meta` so multi-process
+ * deployments stay coherent. The driver caches the resolved
+ * SQL fragments per index in memory.
+ *
+ * Search uses `websearch_to_tsquery` + `ts_rank_cd` for
+ * ranking, plus `ts_headline` snippets for any field in
+ * `attributesToHighlight`. The total hit count comes from a
+ * `COUNT(*) OVER ()` window so pagination metadata is correct
+ * without a separate query.
+ *
+ * What V1 does **not** do:
+ *
+ *   - **Typo tolerance / `pg_trgm`.** The 0.x driver shipped a
+ *     trigram-based fuzzy expander; the surface area is large
+ *     and the trade-offs index-specific. Deferred to V1.1 —
+ *     apps that need it today drop down to the Memory or
+ *     Meilisearch drivers.
+ *   - **In-place rebuild tiers.** Apps re-index via the mixin's
+ *     `Repository.importAll()` (or the future `search:reindex`
+ *     console command) — no per-driver size heuristic.
+ *   - **Adding a `filterableAttribute` to a large existing
+ *     index** is fine — the index is built lazily via
+ *     `CREATE INDEX IF NOT EXISTS` on `(document->>'<attr>')`,
+ *     no `ALTER TABLE ADD COLUMN`.
+ */
+
+import {
+  currentTransactionalContext,
+  type DatabaseExecutor,
+  type PostgresDatabase,
+} from '@strav/database'
+import { IndexNotFoundError, SearchError, SearchQueryError } from '../../search_error.ts'
 import type { SearchEngine } from '../../search_engine.ts'
 import type {
+  DriverConfig,
+  IndexSettings,
   SearchDocument,
+  SearchHit,
   SearchOptions,
   SearchResult,
-  IndexSettings,
-  DriverConfig,
 } from '../../types.ts'
-import { PgEngine } from './engine/pg_engine.ts'
-import { ensureSchemaAndExtensions } from './engine/schema.ts'
-import { resolveTypoTolerance } from './engine/typo_expander.ts'
-import type { PostgresFtsConfig, PgIndexSettings, ResolvedTypoTolerance } from './types.ts'
-import { MissingConnectionError } from './errors.ts'
+import { DEFAULT_SEARCH_SCHEMA, validateIdentifier } from './apply_search_migration.ts'
+
+interface ResolvedIndex {
+  settings: IndexSettings
+  language: string
+  /** Tokenized + validated attribute names — safe to splice into SQL. */
+  searchable: string[]
+  filterable: Set<string>
+  sortable: Set<string>
+  /** SQL fragment that produces the tsvector for the document JSONB. */
+  ftsExpression: string
+}
 
-const DEFAULT_SCHEMA = 'strav_search'
 const DEFAULT_LANGUAGE = 'english'
-const DEFAULT_WORK_MEM = '64MB'
+const TENANT_SETTING = 'app.tenant_id'
+
+export interface PostgresFtsDriverOptions {
+  db: PostgresDatabase
+  /** Schema for index tables. Defaults to `strav_search`. */
+  schema?: string
+  /** Default text-search configuration (`english`, `french`, ...). */
+  language?: string
+}
 
-/**
- * Postgres-backed full-text search driver. Implements the same `SearchEngine`
- * interface as the embedded SQLite driver — drop-in swap by config.
- *
- * Sized for higher-volume workloads (1M-100M docs per index) using `tsvector`
- * + GIN + `pg_trgm` for typo tolerance + `ts_headline` for snippets.
- *
- * Connection: pass `connection` (a Bun `SQL` instance) in the driver config,
- * or rely on `Database.raw` from `@strav/database` (must be bootstrapped).
- */
 export class PostgresFtsDriver implements SearchEngine {
   readonly name = 'postgres-fts'
 
-  private readonly config: PostgresFtsConfig
-  private readonly schemaName: string
+  private readonly db: PostgresDatabase
+  private readonly schema: string
   private readonly defaultLanguage: string
-  private readonly typo: ResolvedTypoTolerance
-  private readonly ginFastUpdate: boolean
-  private readonly workMem: string | null
-  private readonly engines = new Map<string, PgEngine>()
-  private readonly pendingSettings = new Map<string, PgIndexSettings>()
-  private bootstrapped: Promise<void> | null = null
-  private resolvedSql: SQL | null = null
-
-  constructor(config: DriverConfig) {
-    this.config = (config ?? {}) as PostgresFtsConfig
-    this.schemaName = this.config.schema ?? DEFAULT_SCHEMA
-    this.defaultLanguage = this.config.language ?? DEFAULT_LANGUAGE
-    this.typo = resolveTypoTolerance(this.config.typoTolerance)
-    this.ginFastUpdate = this.config.gin?.fastupdate ?? false
-    this.workMem =
-      this.config.workMem === null
-        ? null
-        : (this.config.workMem ?? DEFAULT_WORK_MEM)
-  }
-
-  // ── Document operations ──────────────────────────────────────────────────
+  private readonly indexes = new Map<string, ResolvedIndex>()
+
+  constructor(options: PostgresFtsDriverOptions) {
+    this.db = options.db
+    this.schema = validateIdentifier(options.schema ?? DEFAULT_SEARCH_SCHEMA, 'schema')
+    this.defaultLanguage = options.language ?? DEFAULT_LANGUAGE
+  }
+
+  static fromConfig(db: PostgresDatabase, config: DriverConfig): PostgresFtsDriver {
+    return new PostgresFtsDriver({
+      db,
+      ...(typeof config.schema === 'string' ? { schema: config.schema } : {}),
+      ...(typeof config.language === 'string' ? { language: config.language } : {}),
+    })
+  }
+
+  /**
+   * Route reads + writes through the ambient `UnitOfWork`
+   * transaction when one is active (e.g., inside
+   * `tenants.withTenant(...)`), so RLS scoping applies
+   * uniformly with the rest of the app's database calls.
+   */
+  private exec(): DatabaseExecutor {
+    const ambient = currentTransactionalContext()
+    if (ambient) return ambient.tx
+    return this.db as unknown as DatabaseExecutor
+  }
+
+  // ─── Index lifecycle ────────────────────────────────────────────────────
+
+  async createIndex(index: string, settings: IndexSettings = {}): Promise<void> {
+    const indexName = validateIdentifier(index, 'index')
+    const language = sanitizeLanguage(this.defaultLanguage)
+    const resolved = resolveIndexSettings(settings, language)
+
+    const ex = this.exec()
+    const table = this.qualify(indexName)
+
+    // Table + columns.
+    await ex.execute(
+      `CREATE TABLE IF NOT EXISTS ${table} (
+         "id"        text PRIMARY KEY,
+         "tenant_id" text,
+         "document"  jsonb NOT NULL,
+         "fts"       tsvector NOT NULL
+       )`,
+    )
+
+    // Indexes — GIN over fts + B-tree over tenant_id + expression
+    // index per filterable / sortable attribute.
+    await ex.execute(
+      `CREATE INDEX IF NOT EXISTS "${indexName}_fts"
+         ON ${table} USING GIN ("fts")`,
+    )
+    await ex.execute(
+      `CREATE INDEX IF NOT EXISTS "${indexName}_tenant"
+         ON ${table} ("tenant_id") WHERE "tenant_id" IS NOT NULL`,
+    )
+    for (const attr of [...resolved.filterable, ...resolved.sortable]) {
+      await ex.execute(
+        `CREATE INDEX IF NOT EXISTS "${indexName}_${attr}"
+           ON ${table} (("document"->>'${attr}'))`,
+      )
+    }
+
+    // RLS — single policy keyed off `app.tenant_id`. Rows with
+    // `tenant_id IS NULL` are visible to every tenant (the
+    // single-tenant default).
+    await ex.execute(`ALTER TABLE ${table} ENABLE ROW LEVEL SECURITY`)
+    await ex.execute(`ALTER TABLE ${table} FORCE ROW LEVEL SECURITY`)
+    await ex.execute(`DROP POLICY IF EXISTS "${indexName}_isolate" ON ${table}`)
+    await ex.execute(
+      `CREATE POLICY "${indexName}_isolate" ON ${table}
+         USING (
+           "tenant_id" IS NULL
+           OR "tenant_id" = current_setting('${TENANT_SETTING}', true)
+         )
+         WITH CHECK (
+           "tenant_id" IS NULL
+           OR "tenant_id" = current_setting('${TENANT_SETTING}', true)
+         )`,
+    )
+
+    // Persist the settings + language for cross-process reads.
+    await ex.execute(
+      `INSERT INTO "${this.schema}"."_meta" ("index_name", "settings", "language", "updated_at")
+         VALUES ($1, $2::jsonb, $3, now())
+         ON CONFLICT ("index_name") DO UPDATE
+           SET "settings"   = EXCLUDED."settings",
+               "language"   = EXCLUDED."language",
+               "updated_at" = now()`,
+      [indexName, JSON.stringify(settings), language],
+    )
+
+    this.indexes.set(indexName, resolved)
+  }
+
+  async deleteIndex(index: string): Promise<void> {
+    const indexName = validateIdentifier(index, 'index')
+    const ex = this.exec()
+    await ex.execute(`DROP TABLE IF EXISTS ${this.qualify(indexName)} CASCADE`)
+    await ex.execute(`DELETE FROM "${this.schema}"."_meta" WHERE "index_name" = $1`, [indexName])
+    this.indexes.delete(indexName)
+  }
+
+  async flush(index: string): Promise<void> {
+    const indexName = validateIdentifier(index, 'index')
+    const exists = await this.indexExists(indexName)
+    if (!exists) return
+    await this.exec().execute(`DELETE FROM ${this.qualify(indexName)}`)
+  }
+
+  // ─── Writes ─────────────────────────────────────────────────────────────
 
   async upsert(
     index: string,
     id: string | number,
-    document: Record<string, unknown>
+    document: Record<string, unknown>,
   ): Promise<void> {
-    await (await this.engineFor(index)).upsert(id, document)
+    await this.upsertMany(index, [{ id, ...document }])
   }
 
-  async upsertMany(index: string, documents: SearchDocument[]): Promise<void> {
-    await (await this.engineFor(index)).upsertMany(documents)
+  async upsertMany(index: string, documents: readonly SearchDocument[]): Promise<void> {
+    if (documents.length === 0) return
+    const indexName = validateIdentifier(index, 'index')
+    const resolved = await this.resolveIndex(indexName)
+    const table = this.qualify(indexName)
+    const ex = this.exec()
+
+    // Insert one row at a time so each row's fts expression can
+    // bind its own JSONB parameter cleanly. Bulk INSERT with
+    // VALUES + per-row CTE was tried and complicates the
+    // parameter math far more than it saves in latency for
+    // typical batches of <500 rows.
+    for (const doc of documents) {
+      await ex.execute(
+        `INSERT INTO ${table} ("id", "tenant_id", "document", "fts")
+           VALUES (
+             $1,
+             current_setting('${TENANT_SETTING}', true),
+             $2,
+             ${resolved.ftsExpression}
+           )
+           ON CONFLICT ("id") DO UPDATE
+             SET "document" = EXCLUDED."document",
+                 "fts"      = EXCLUDED."fts"`,
+        // Pass the document as a JS object — `bun:sql` encodes JSONB
+        // params directly. Pre-`JSON.stringify`-ing causes Postgres
+        // to store a JSON string scalar instead of an object, which
+        // breaks every `->>` projection downstream.
+        [String(doc.id), { ...(doc as Record<string, unknown>) }],
+      )
+    }
   }
 
   async delete(index: string, id: string | number): Promise<void> {
-    await (await this.engineFor(index)).delete(id)
+    await this.deleteMany(index, [id])
   }
 
-  async deleteMany(index: string, ids: Array<string | number>): Promise<void> {
-    await (await this.engineFor(index)).deleteMany(ids)
+  async deleteMany(index: string, ids: readonly (string | number)[]): Promise<void> {
+    if (ids.length === 0) return
+    const indexName = validateIdentifier(index, 'index')
+    const placeholders = ids.map((_, i) => `$${i + 1}`).join(', ')
+    const params = ids.map((id) => String(id))
+    await this.exec().execute(
+      `DELETE FROM ${this.qualify(indexName)} WHERE "id" IN (${placeholders})`,
+      params,
+    )
   }
 
-  // ── Index operations ─────────────────────────────────────────────────────
+  // ─── Reads ──────────────────────────────────────────────────────────────
 
-  async flush(index: string): Promise<void> {
-    await (await this.engineFor(index)).flush()
-  }
+  async search(index: string, query: string, options: SearchOptions = {}): Promise<SearchResult> {
+    const indexName = validateIdentifier(index, 'index')
+    const resolved = await this.resolveIndex(indexName)
 
-  async deleteIndex(index: string): Promise<void> {
-    const engine = this.engines.get(index)
-    if (engine) {
-      await engine.drop()
-      this.engines.delete(index)
+    if (options.filter !== undefined && (typeof options.filter !== 'object' || Array.isArray(options.filter))) {
+      throw new SearchQueryError(
+        'PostgresFtsDriver: `filter` must be a flat key/value object. Engine-native strings are not portable.',
+      )
+    }
+
+    const page = Math.max(1, options.page ?? 1)
+    const perPage = Math.max(1, options.perPage ?? 20)
+    const limit = perPage
+    const offset = (page - 1) * perPage
+
+    const table = this.qualify(indexName)
+    const params: unknown[] = []
+    const select: string[] = ['"id"', '"document"']
+    const whereClauses: string[] = []
+    const trimmedQuery = query.trim()
+
+    if (trimmedQuery.length > 0) {
+      params.push(trimmedQuery)
+      const qIdx = params.length
+      select.push(`ts_rank_cd("fts", websearch_to_tsquery('${resolved.language}', $${qIdx})) AS rank`)
+      whereClauses.push(`"fts" @@ websearch_to_tsquery('${resolved.language}', $${qIdx})`)
     } else {
-      // Drop directly without instantiating an engine.
-      const sql = this.resolveSql()
-      const { dropIndex } = await import('./engine/schema.ts')
-      await dropIndex(sql, this.schemaName, index)
+      select.push('0.0 AS rank')
     }
-    this.pendingSettings.delete(index)
-  }
 
-  async createIndex(index: string, options?: IndexSettings): Promise<void> {
-    if (options) this.pendingSettings.set(index, options as PgIndexSettings)
-    const engine = await this.engineFor(index)
-    await engine.ensure()
-  }
+    if (options.filter) {
+      for (const [key, value] of Object.entries(options.filter)) {
+        if (!resolved.filterable.has(key)) {
+          throw new SearchQueryError(
+            `PostgresFtsDriver: filter key "${key}" is not in this index's filterableAttributes.`,
+            { context: { index: indexName, key, filterable: [...resolved.filterable] } },
+          )
+        }
+        params.push(typeof value === 'number' || typeof value === 'boolean' ? String(value) : value)
+        whereClauses.push(`("document"->>'${key}') = $${params.length}`)
+      }
+    }
+
+    // Highlights — one ts_headline column per requested attribute.
+    if (options.attributesToHighlight) {
+      params.push(trimmedQuery.length > 0 ? trimmedQuery : '')
+      const qIdx = params.length
+      for (const attr of options.attributesToHighlight) {
+        if (!isSafeAttribute(attr)) {
+          throw new SearchQueryError(
+            `PostgresFtsDriver: highlight attribute "${attr}" contains illegal characters.`,
+          )
+        }
+        select.push(
+          `ts_headline(
+            '${resolved.language}',
+            coalesce("document"->>'${attr}', ''),
+            websearch_to_tsquery('${resolved.language}', $${qIdx}),
+            'StartSel=<mark>,StopSel=</mark>,MaxFragments=2,MinWords=3,MaxWords=15'
+          ) AS "hl_${attr}"`,
+        )
+      }
+    }
 
-  // ── Search ───────────────────────────────────────────────────────────────
+    // Sort — explicit user sort takes precedence; otherwise rank for queried,
+    // id for empty queries.
+    const orderClauses: string[] = []
+    if (options.sort) {
+      for (const directive of options.sort) {
+        const [field, dirRaw] = directive.split(':') as [string, string | undefined]
+        const dir = dirRaw?.toLowerCase() === 'desc' ? 'DESC' : 'ASC'
+        if (!resolved.sortable.has(field)) {
+          throw new SearchQueryError(
+            `PostgresFtsDriver: sort attribute "${field}" is not in this index's sortableAttributes.`,
+            { context: { index: indexName, field, sortable: [...resolved.sortable] } },
+          )
+        }
+        orderClauses.push(`("document"->>'${field}') ${dir}`)
+      }
+    } else if (trimmedQuery.length > 0) {
+      orderClauses.push('rank DESC')
+    } else {
+      orderClauses.push('"id" ASC')
+    }
 
-  async search(index: string, query: string, options?: SearchOptions): Promise<SearchResult> {
-    return (await this.engineFor(index)).search(query, options)
-  }
+    select.push('COUNT(*) OVER () AS total')
+    params.push(limit, offset)
+    const sql =
+      `SELECT ${select.join(', ')}
+         FROM ${table}
+         ${whereClauses.length > 0 ? `WHERE ${whereClauses.join(' AND ')}` : ''}
+         ORDER BY ${orderClauses.join(', ')}
+         LIMIT $${params.length - 1} OFFSET $${params.length}`
 
-  // ── Lifecycle ────────────────────────────────────────────────────────────
+    const start = performance.now()
+    let rows: Array<Record<string, unknown>>
+    try {
+      rows = await this.exec().query<Record<string, unknown>>(sql, params)
+    } catch (cause) {
+      const msg = (cause as Error).message ?? ''
+      if (msg.includes('does not exist')) {
+        throw new IndexNotFoundError(indexName, this.name)
+      }
+      throw new SearchQueryError(`PostgresFtsDriver: search query failed: ${msg}`, { cause })
+    }
 
-  /** Run REINDEX on every open index, or just one if specified. */
-  async optimize(index?: string): Promise<void> {
-    if (index) {
-      await (await this.engineFor(index)).optimize()
-      return
+    const totalHits = rows.length === 0 ? 0 : Number(rows[0]!.total ?? 0)
+    const hits: SearchHit[] = rows.map((row) => {
+      // `bun:sql` returns jsonb columns as text — parse so apps see
+      // the original document shape.
+      const document =
+        typeof row.document === 'string'
+          ? (JSON.parse(row.document) as Record<string, unknown>)
+          : (row.document as Record<string, unknown>)
+      const projected = projectAttributes(document, options.attributesToRetrieve)
+      const hit: SearchHit = { document: projected }
+      if (options.attributesToHighlight) {
+        const highlights: Record<string, string> = {}
+        for (const attr of options.attributesToHighlight) {
+          const value = row[`hl_${attr}`]
+          if (typeof value === 'string') highlights[attr] = value
+        }
+        if (Object.keys(highlights).length > 0) hit.highlights = highlights
+      }
+      return hit
+    })
+
+    return {
+      hits,
+      totalHits,
+      page,
+      perPage,
+      processingTimeMs: performance.now() - start,
     }
-    for (const engine of this.engines.values()) await engine.optimize()
+  }
+
+  // ─── Internals ──────────────────────────────────────────────────────────
+
+  private qualify(index: string): string {
+    return `"${this.schema}"."${index}"`
+  }
+
+  private async indexExists(index: string): Promise<boolean> {
+    const row = await this.exec().queryOne<{ exists: boolean }>(
+      `SELECT EXISTS (
+         SELECT 1 FROM pg_tables WHERE schemaname = $1 AND tablename = $2
+       ) AS "exists"`,
+      [this.schema, index],
+    )
+    return row?.exists === true
   }
 
   /**
-   * Rebuild a single index's `fts` column in place. Use after changing
-   * `searchableAttributes` or weights — without it, existing rows keep the
-   * old fts values.
+   * Load `_meta` into the in-memory cache. Called lazily so apps
+   * that only ever read from indexes created by another process
+   * still get the right `ftsExpression` shape.
    */
-  async rebuild(
-    index: string,
-    options?: { reindex?: boolean; pauseMs?: number; onProgress?: (done: number, total: number) => void }
-  ): Promise<{ tier: 1 | 2; rows: number; elapsedMs: number }> {
-    return (await this.engineFor(index)).rebuild(options)
-  }
-
-  // ── Internals ────────────────────────────────────────────────────────────
-
-  private async engineFor(index: string): Promise<PgEngine> {
-    let engine = this.engines.get(index)
-    if (engine) return engine
-
-    await this.bootstrap()
-    const settings = this.pendingSettings.get(index)
-    engine = new PgEngine({
-      sql: this.resolveSql(),
-      schema: this.schemaName,
-      index,
-      language: settings?.language ?? this.defaultLanguage,
-      typoTolerance: this.typo,
-      ginFastUpdate: this.ginFastUpdate,
-      workMem: this.workMem,
-      settings,
-    })
-    this.engines.set(index, engine)
-    this.pendingSettings.delete(index)
-    return engine
-  }
+  private async resolveIndex(index: string): Promise<ResolvedIndex> {
+    const cached = this.indexes.get(index)
+    if (cached) return cached
 
-  /** Resolve the SQL connection (config.connection or Database.raw fallback). */
-  private resolveSql(): SQL {
-    if (this.resolvedSql) return this.resolvedSql
-    if (this.config.connection) {
-      this.resolvedSql = this.config.connection
-      return this.resolvedSql
+    const row = await this.exec().queryOne<{ settings: unknown; language: string }>(
+      `SELECT "settings", "language" FROM "${this.schema}"."_meta" WHERE "index_name" = $1`,
+      [index],
+    )
+    if (!row) {
+      throw new IndexNotFoundError(index, this.name)
     }
-    try {
-      // Lazy require to avoid a hard dep at import time.
-      const databaseModule = require('@strav/database')
-      const Database = databaseModule.default ?? databaseModule.Database
-      this.resolvedSql = Database.raw as SQL
-      return this.resolvedSql
-    } catch {
-      throw new MissingConnectionError()
+    const settings = (row.settings ?? {}) as IndexSettings
+    const resolved = resolveIndexSettings(settings, sanitizeLanguage(row.language))
+    this.indexes.set(index, resolved)
+    return resolved
+  }
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────
+
+const FTS_WEIGHTS: readonly ('A' | 'B' | 'C' | 'D')[] = ['A', 'B', 'C', 'D']
+
+function resolveIndexSettings(settings: IndexSettings, language: string): ResolvedIndex {
+  const searchable = (settings.searchableAttributes ?? []).map((attr) => {
+    if (!isSafeAttribute(attr)) {
+      throw new SearchError(
+        `PostgresFtsDriver: searchable attribute "${attr}" contains illegal characters. ` +
+          `Must match /^[a-z_][a-z0-9_]*$/.`,
+        { code: 'search.config' },
+      )
     }
+    return attr
+  })
+  const filterable = new Set(
+    (settings.filterableAttributes ?? []).filter((a) => {
+      if (!isSafeAttribute(a)) {
+        throw new SearchError(
+          `PostgresFtsDriver: filterable attribute "${a}" contains illegal characters.`,
+          { code: 'search.config' },
+        )
+      }
+      return true
+    }),
+  )
+  const sortable = new Set(
+    (settings.sortableAttributes ?? []).filter((a) => {
+      if (!isSafeAttribute(a)) {
+        throw new SearchError(
+          `PostgresFtsDriver: sortable attribute "${a}" contains illegal characters.`,
+          { code: 'search.config' },
+        )
+      }
+      return true
+    }),
+  )
+
+  const ftsExpression = buildFtsExpression(searchable, language)
+
+  return { settings, language, searchable, filterable, sortable, ftsExpression }
+}
+
+/**
+ * Compose a SQL expression that produces a tsvector for the row
+ * being inserted. The JSONB document is bound as `$2::jsonb`.
+ *
+ * When `searchableAttributes` is set, each one becomes a weighted
+ * `setweight(to_tsvector(lang, coalesce(doc->>'<attr>', '')), 'A|B|C|D')`
+ * pegged to its position. When the list is empty we fall back to
+ * indexing every text leaf in the JSONB via `jsonb_path_query_array`
+ * → `array_to_string`, weighted 'A'.
+ */
+function buildFtsExpression(searchable: readonly string[], language: string): string {
+  if (searchable.length === 0) {
+    return (
+      `setweight(to_tsvector('${language}', ` +
+      `coalesce((SELECT string_agg(value::text, ' ') FROM jsonb_each_text($2::jsonb)), '')),` +
+      ` 'A')`
+    )
   }
+  return searchable
+    .map((attr, i) => {
+      const weight = FTS_WEIGHTS[Math.min(i, FTS_WEIGHTS.length - 1)]
+      return `setweight(to_tsvector('${language}', coalesce($2::jsonb->>'${attr}', '')), '${weight}')`
+    })
+    .join(' || ')
+}
+
+function projectAttributes(
+  document: Record<string, unknown>,
+  attributes: string[] | undefined,
+): Record<string, unknown> {
+  if (!attributes || attributes.length === 0) return { ...document }
+  const out: Record<string, unknown> = {}
+  for (const attr of attributes) {
+    if (attr in document) out[attr] = document[attr]
+  }
+  if ('id' in document && !('id' in out)) out.id = document.id
+  return out
+}
+
+function isSafeAttribute(name: string): boolean {
+  return /^[a-z_][a-z0-9_]*$/.test(name)
+}
 
-  /** Idempotent: ensure schema + extensions exist, once per driver. */
-  private bootstrap(): Promise<void> {
-    if (this.bootstrapped) return this.bootstrapped
-    this.bootstrapped = ensureSchemaAndExtensions(
-      this.resolveSql(),
-      this.schemaName,
-      this.typo
+function sanitizeLanguage(language: string): string {
+  // Postgres text-search configuration names are user-defined,
+  // but the built-ins ship with lowercase ASCII identifiers; we
+  // refuse anything else so the value can be spliced directly.
+  if (!/^[a-z_][a-z0-9_]*$/.test(language)) {
+    throw new SearchError(
+      `PostgresFtsDriver: invalid language ${JSON.stringify(language)} — must match /^[a-z_][a-z0-9_]*$/.`,
+      { code: 'search.config' },
     )
-    return this.bootstrapped
   }
+  return language
 }