@strav/search 0.3.20 → 0.3.22

package/src/drivers/postgres/engine/pg_engine.ts

@@ -0,0 +1,300 @@
+import type { SQL } from 'bun'
+import type {
+  SearchDocument,
+  SearchOptions,
+  SearchResult,
+  SearchHit,
+} from '../../../types.ts'
+import type { PgIndexSettings, ResolvedTypoTolerance } from '../types.ts'
+import { FieldRegistry } from './field_registry.ts'
+import { ensureIndexTable, dropIndex as dropIndexSchema } from './schema.ts'
+import { parseQuery, buildTsqueryExpression } from './fts_query_builder.ts'
+import { compileSearch } from './query_compiler.ts'
+import { formatSnippet } from './snippet_formatter.ts'
+import {
+  expandTokens,
+  hasFuzzystrmatch,
+  recordTerms,
+  unrecordTerms,
+} from './typo_expander.ts'
+import {
+  indexTableName,
+  termsTableName,
+  quoteIdent,
+  quoteLiteral,
+} from '../storage/identifiers.ts'
+import { rebuildInPlace, type RebuildOptions } from '../rebuild/rebuild_inplace.ts'
+
+export interface PgEngineOptions {
+  sql: SQL
+  schema: string
+  index: string
+  language: string
+  typoTolerance: ResolvedTypoTolerance
+  ginFastUpdate: boolean
+  workMem: string | null
+  settings?: PgIndexSettings
+}
+
+/** Postgres tsvector silently truncates at ~1MB lexemes. Truncate inputs to be safe. */
+const MAX_TEXT_BYTES = 900_000
+
+/** One PgEngine wraps a single index. */
+export class PgEngine {
+  readonly registry: FieldRegistry
+  private readonly sql: SQL
+  private readonly schema: string
+  private readonly index: string
+  private readonly typo: ResolvedTypoTolerance
+  private readonly ginFastUpdate: boolean
+  private readonly workMem: string | null
+  private readonly tableName: string
+  private fuzzyAvailable: boolean | null = null
+  private ensured = false
+
+  constructor(opts: PgEngineOptions) {
+    this.sql = opts.sql
+    this.schema = opts.schema
+    this.index = opts.index
+    this.typo = opts.typoTolerance
+    this.ginFastUpdate = opts.ginFastUpdate
+    this.workMem = opts.workMem
+    this.registry = new FieldRegistry(opts.settings, opts.language)
+    this.tableName = indexTableName(opts.schema, opts.index)
+  }
+
+  /** Lazy: ensure the table + indexes + trigger exist. Idempotent. */
+  async ensure(): Promise<void> {
+    if (this.ensured) return
+    await ensureIndexTable(this.sql, this.schema, this.index, this.registry, this.ginFastUpdate)
+    if (this.typo.enabled && this.fuzzyAvailable === null) {
+      this.fuzzyAvailable = await hasFuzzystrmatch(this.sql)
+    }
+    this.ensured = true
+  }
+
+  // ── Writes ──────────────────────────────────────────────────────────────
+
+  async upsert(id: string | number, document: Record<string, unknown>): Promise<void> {
+    await this.upsertMany([{ id, ...document }])
+  }
+
+  async upsertMany(documents: SearchDocument[]): Promise<void> {
+    if (documents.length === 0) return
+    await this.ensure()
+
+    await this.sql.begin(async (tx: SQL) => {
+      for (const raw of documents) {
+        const { id, ...rest } = raw
+        const idStr = String(id)
+        // Bun's SQL treats stringified JSON as a JSONB string value (double-
+        // encoding the JSON). Passing the object directly lets it generate
+        // proper JSONB so `doc->>'field'` works for the typed generated cols.
+        const doc = { id, ...(rest as Record<string, unknown>) }
+        const newText = truncate(this.registry.concatSearchableText(rest as Record<string, unknown>))
+
+        const oldRows = (await tx.unsafe(
+          `SELECT doc FROM ${this.tableName} WHERE id = $1`,
+          [idStr]
+        )) as Array<{ doc: Record<string, unknown> | string }>
+        if (oldRows.length > 0) {
+          const oldDoc = parseDoc(oldRows[0]!.doc)
+          const oldText = this.registry.concatSearchableText(oldDoc)
+          if (this.typo.enabled) await unrecordTerms(tx, this.schema, this.index, oldText)
+        }
+
+        const ftsExpr = this.buildFtsExpression(rest as Record<string, unknown>)
+        const sqlStr =
+          `INSERT INTO ${this.tableName} (id, doc, fts) VALUES ($1, $2, ${ftsExpr.sql}) ` +
+          `ON CONFLICT (id) DO UPDATE SET doc = EXCLUDED.doc, fts = EXCLUDED.fts`
+        await tx.unsafe(sqlStr, [idStr, doc as any, ...ftsExpr.params])
+
+        if (this.typo.enabled) await recordTerms(tx, this.schema, this.index, newText)
+      }
+    })
+  }
+
+  async delete(id: string | number): Promise<void> {
+    await this.deleteMany([id])
+  }
+
+  async deleteMany(ids: Array<string | number>): Promise<void> {
+    if (ids.length === 0) return
+    await this.ensure()
+
+    await this.sql.begin(async (tx: SQL) => {
+      const idStrs = ids.map(String)
+      const placeholders = idStrs.map((_, i) => `$${i + 1}`).join(', ')
+
+      if (this.typo.enabled) {
+        const rows = (await tx.unsafe(
+          `SELECT doc FROM ${this.tableName} WHERE id IN (${placeholders})`,
+          idStrs
+        )) as Array<{ doc: Record<string, unknown> | string }>
+        for (const r of rows) {
+          const oldDoc = parseDoc(r.doc)
+          await unrecordTerms(tx, this.schema, this.index, this.registry.concatSearchableText(oldDoc))
+        }
+      }
+
+      await tx.unsafe(
+        `DELETE FROM ${this.tableName} WHERE id IN (${placeholders})`,
+        idStrs
+      )
+    })
+  }
+
+  async flush(): Promise<void> {
+    await this.ensure()
+    await this.sql.begin(async (tx: SQL) => {
+      await tx.unsafe(`TRUNCATE ${this.tableName}`)
+      if (this.typo.enabled) {
+        await tx.unsafe(`TRUNCATE ${termsTableName(this.schema, this.index)}`)
+      }
+    })
+  }
+
+  async drop(): Promise<void> {
+    await dropIndexSchema(this.sql, this.schema, this.index)
+    this.ensured = false
+  }
+
+  // ── Reads ───────────────────────────────────────────────────────────────
+
+  async search(query: string, options?: SearchOptions): Promise<SearchResult> {
+    await this.ensure()
+    const start = performance.now()
+    const opts = options ?? {}
+    const parsed = parseQuery(query)
+
+    const expansions = await this.maybeExpand(parsed.positiveTokens)
+    const tsquery = buildTsqueryExpression(parsed, expansions, this.registry.language)
+
+    const compiled = compileSearch({
+      registry: this.registry,
+      schema: this.schema,
+      index: this.index,
+      tsquery: { sql: tsquery.sql, params: tsquery.params },
+      search: opts,
+    })
+
+    const result = await this.sql.begin(async (tx: SQL) => {
+      if (this.workMem) {
+        await tx.unsafe(`SET LOCAL work_mem = ${quoteLiteral(this.workMem)}`)
+      }
+      const rows = (await tx.unsafe(compiled.sql, compiled.params)) as RawHitRow[]
+      const totalRows = (await tx.unsafe(compiled.countSql, compiled.countParams)) as Array<{
+        n: number
+      }>
+      return { rows, total: totalRows[0]?.n ?? rows.length }
+    })
+
+    const projection = opts.attributesToRetrieve
+    const hits: SearchHit[] = result.rows.map(row =>
+      projectHit(row, compiled.snippetColumns, projection)
+    )
+
+    return {
+      hits,
+      totalHits: result.total,
+      page: Math.max(1, opts.page ?? 1),
+      perPage: Math.max(1, opts.perPage ?? 20),
+      processingTimeMs: Math.round(performance.now() - start),
+    }
+  }
+
+  /** REINDEX the GIN index. Periodic maintenance for write-heavy indexes. */
+  async optimize(): Promise<void> {
+    await this.ensure()
+    const ginName = `${quoteIdent(this.schema)}.${quoteIdent(`search_${this.index}_fts_gin`)}`
+    await this.sql.unsafe(`REINDEX INDEX ${ginName}`)
+  }
+
+  /**
+   * Recompute every row's `fts` using the current registry's language + weight
+   * scheme. Auto-picks tier (in-place vs batched) by row count; throws on
+   * tables larger than the supported tier-2 ceiling.
+   */
+  async rebuild(options?: RebuildOptions) {
+    await this.ensure()
+    return rebuildInPlace(this.sql, this.schema, this.index, this.registry, options)
+  }
+
+  // ── Internals ───────────────────────────────────────────────────────────
+
+  private buildFtsExpression(document: Record<string, unknown>): {
+    sql: string
+    params: string[]
+  } {
+    const segments = this.registry.projectFtsSegments(document)
+    const lang = `${quoteLiteral(this.registry.language)}::regconfig`
+    const params: string[] = []
+    const fragments = segments.map(seg => {
+      params.push(truncate(seg.text))
+      return `setweight(to_tsvector(${lang}, $${params.length + 2}), '${seg.tier}')`
+    })
+    // The `+2` above accounts for the leading id ($1) and doc ($2) bindings
+    // that callers prepend. Caller MUST keep those positions stable.
+    return { sql: fragments.join(' || '), params }
+  }
+
+  private async maybeExpand(tokens: string[]): Promise<Map<string, string[]>> {
+    if (!this.typo.enabled || tokens.length === 0) return new Map()
+    return expandTokens(
+      this.sql,
+      this.schema,
+      this.index,
+      tokens,
+      this.typo,
+      this.fuzzyAvailable === true
+    )
+  }
+}
+
+interface RawHitRow {
+  id: string
+  doc: Record<string, unknown> | string
+  score: number
+  [snippetCol: string]: unknown
+}
+
+function projectHit(
+  row: RawHitRow,
+  snippetCols: string[],
+  attributesToRetrieve: string[] | undefined
+): SearchHit {
+  const document = parseDoc(row.doc)
+
+  let projected = document
+  if (attributesToRetrieve && attributesToRetrieve.length > 0) {
+    const out: Record<string, unknown> = {}
+    for (const attr of attributesToRetrieve) {
+      if (attr in document) out[attr] = document[attr]
+    }
+    projected = out
+  }
+
+  const hit: SearchHit = { document: projected }
+
+  if (snippetCols.length > 0) {
+    const highlights: Record<string, string> = {}
+    for (const col of snippetCols) {
+      const raw = row[`__snip_${col}`] as string | null | undefined
+      if (raw) highlights[col] = formatSnippet(raw)
+    }
+    if (Object.keys(highlights).length > 0) hit.highlights = highlights
+  }
+
+  return hit
+}
+
+function parseDoc(doc: Record<string, unknown> | string): Record<string, unknown> {
+  if (typeof doc === 'string') return JSON.parse(doc) as Record<string, unknown>
+  return doc
+}
+
+function truncate(text: string): string {
+  if (Buffer.byteLength(text, 'utf8') <= MAX_TEXT_BYTES) return text
+  // Truncate by char count; over-conservative is fine.
+  return text.slice(0, MAX_TEXT_BYTES)
+}

package/src/drivers/postgres/engine/query_compiler.ts

@@ -0,0 +1,165 @@
+import type { SearchOptions } from '../../../types.ts'
+import type { FieldRegistry } from './field_registry.ts'
+import { compileFilter } from '../filters/filter_compiler.ts'
+import { quoteIdent, quoteLiteral, indexTableName } from '../storage/identifiers.ts'
+
+export interface CompiledSearch {
+  /** Main SELECT returning hits + score + snippets. */
+  sql: string
+  /** Bound parameters for the SELECT. */
+  params: unknown[]
+  /** COUNT(*) variant for totalHits (uses the same MATCH + filter, no rank/snippets). */
+  countSql: string
+  countParams: unknown[]
+  /** Names of headlight columns we asked PG to return (`__snip_<field>`). */
+  snippetColumns: string[]
+}
+
+const DEFAULT_HEADLINE_OPTIONS =
+  'StartSel=<mark>,StopSel=</mark>,MaxWords=35,MinWords=15,ShortWord=0,HighlightAll=false,MaxFragments=2'
+
+/** ts_rank_cd normalization bitmask. 1 = divide by 1+log(doc length), 32 = rank/(rank+1). */
+const DEFAULT_RANK_FLAGS = 1 | 32
+
+export interface QueryCompilerOptions {
+  registry: FieldRegistry
+  schema: string
+  index: string
+  /** Output of buildTsqueryExpression — already starts at placeholder 1. */
+  tsquery: { sql: string; params: string[] }
+  search: SearchOptions
+}
+
+export function compileSearch(opts: QueryCompilerOptions): CompiledSearch {
+  const { registry, schema, index, tsquery, search } = opts
+  const filterableSet = new Set(registry.filterable)
+  const sortableSet = new Set(registry.sortable)
+
+  const filter = compileFilter(search.filter, filterableSet, tsquery.params.length)
+  const params: unknown[] = [...tsquery.params, ...filter.params]
+
+  const whereParts: string[] = []
+  if (tsquery.sql) whereParts.push(`fts @@ q.query`)
+  if (filter.sql) whereParts.push(filter.sql)
+  const where = whereParts.length > 0 ? `WHERE ${whereParts.join(' AND ')}` : ''
+
+  const orderBy = compileOrder(search.sort, sortableSet, !tsquery.sql)
+
+  const perPage = Math.max(1, search.perPage ?? 20)
+  const page = Math.max(1, search.page ?? 1)
+  const offset = (page - 1) * perPage
+
+  const limitPh = `$${params.length + 1}`
+  const offsetPh = `$${params.length + 2}`
+  params.push(perPage, offset)
+
+  const wantedHighlights = pickHighlightFields(search.attributesToHighlight, registry)
+  const lang = `${quoteLiteral(registry.language)}::regconfig`
+
+  // The ranked CTE: filter + order + LIMIT, returns top-K rows + score only.
+  // ts_headline runs only on this top-K slice (huge perf win — ts_headline
+  // re-tokenizes raw text per row).
+  const cte = tsquery.sql
+    ? `WITH q AS (SELECT (${tsquery.sql}) AS query),
+           ranked AS (
+             SELECT id, doc, ts_rank_cd(fts, q.query, ${DEFAULT_RANK_FLAGS}) AS score
+               FROM ${indexTableName(schema, index)}, q
+               ${where}
+               ${orderBy}
+               LIMIT ${limitPh} OFFSET ${offsetPh}
+           )`
+    : `WITH ranked AS (
+             SELECT id, doc, 0::real AS score
+               FROM ${indexTableName(schema, index)}
+               ${where}
+               ${orderBy}
+               LIMIT ${limitPh} OFFSET ${offsetPh}
+           )`
+
+  const snippetCols = wantedHighlights.map(field => {
+    return `ts_headline(${lang}, coalesce(doc->>${quoteLiteral(field)}, ''), ` +
+      `${tsquery.sql ? '(SELECT query FROM q)' : 'plainto_tsquery(' + lang + ", '')"}, ` +
+      `${quoteLiteral(DEFAULT_HEADLINE_OPTIONS)}) AS ${quoteIdent(`__snip_${field}`)}`
+  })
+
+  const selectCols = ['id', 'doc', 'score', ...snippetCols]
+
+  // Re-emit ORDER BY in the outer SELECT — Postgres doesn't preserve row
+  // order across CTE boundaries.
+  const outerOrderBy = compileOuterOrder(search.sort, sortableSet, !tsquery.sql)
+  const sql = `${cte}
+    SELECT ${selectCols.join(', ')}
+    FROM ranked
+    ${outerOrderBy}`
+
+  // Count uses the MATCH + filter, but no rank/snippet/limit.
+  const countSql = tsquery.sql
+    ? `SELECT COUNT(*)::int AS n FROM ${indexTableName(schema, index)}, ` +
+        `(SELECT (${tsquery.sql}) AS query) q ${where}`
+    : `SELECT COUNT(*)::int AS n FROM ${indexTableName(schema, index)} ${where}`
+
+  const countParams = [...tsquery.params, ...filter.params]
+
+  return {
+    sql,
+    params,
+    countSql,
+    countParams,
+    snippetColumns: wantedHighlights,
+  }
+}
+
+function compileOrder(
+  sort: string[] | undefined,
+  sortableSet: ReadonlySet<string>,
+  matchAll: boolean
+): string {
+  if (sort && sort.length > 0) {
+    const parts: string[] = []
+    for (const spec of sort) {
+      const [field, dirRaw] = spec.split(':') as [string, string | undefined]
+      if (!field || !sortableSet.has(field)) {
+        throw new Error(
+          `Field "${field}" is not in sortableAttributes. Add it to the index settings before sorting on it.`
+        )
+      }
+      const dir = dirRaw?.toLowerCase() === 'desc' ? 'DESC' : 'ASC'
+      parts.push(`${quoteIdent(field)} ${dir}`)
+    }
+    return `ORDER BY ${parts.join(', ')}`
+  }
+  if (matchAll) return 'ORDER BY id ASC'
+  return 'ORDER BY score DESC'
+}
+
+/** ORDER BY for the outer SELECT — references columns visible on `ranked`. */
+function compileOuterOrder(
+  sort: string[] | undefined,
+  sortableSet: ReadonlySet<string>,
+  matchAll: boolean
+): string {
+  if (sort && sort.length > 0) {
+    // The CTE only exposes id, doc, score — sortable columns aren't in scope,
+    // so we sort by `doc->>'field'` lexically. Same lex semantics as the
+    // typed generated columns (which are TEXT) used inside the CTE.
+    const parts: string[] = []
+    for (const spec of sort) {
+      const [field, dirRaw] = spec.split(':') as [string, string | undefined]
+      if (!field || !sortableSet.has(field)) continue
+      const dir = dirRaw?.toLowerCase() === 'desc' ? 'DESC' : 'ASC'
+      parts.push(`(doc->>${quoteLiteral(field)}) ${dir}`)
+    }
+    return parts.length > 0 ? `ORDER BY ${parts.join(', ')}` : ''
+  }
+  if (matchAll) return 'ORDER BY id ASC'
+  return 'ORDER BY score DESC'
+}
+
+function pickHighlightFields(
+  requested: string[] | undefined,
+  registry: FieldRegistry
+): string[] {
+  if (registry.usesDefaultTextColumn) return []
+  if (!requested || requested.length === 0) return []
+  return requested.filter(f => registry.searchable.includes(f))
+}

package/src/drivers/postgres/engine/schema.ts

@@ -0,0 +1,187 @@
+import type { SQL } from 'bun'
+import { quoteIdent, quoteLiteral, indexTableName, termsTableName, metaTableName, bareIndexTable, bareTermsTable } from '../storage/identifiers.ts'
+import { MissingExtensionError } from '../errors.ts'
+import type { FieldRegistry } from './field_registry.ts'
+import type { ResolvedTypoTolerance } from '../types.ts'
+
+const SCHEMA_VERSION = 1
+
+/**
+ * Idempotent: ensures the search schema, the shared `_meta` table, and the
+ * required extensions exist. Called once per driver instantiation.
+ */
+export async function ensureSchemaAndExtensions(
+  sql: SQL,
+  schema: string,
+  typo: ResolvedTypoTolerance
+): Promise<void> {
+  await sql.unsafe(`CREATE SCHEMA IF NOT EXISTS ${quoteIdent(schema)}`)
+
+  await sql.unsafe(`
+    CREATE TABLE IF NOT EXISTS ${metaTableName(schema)} (
+      index_name TEXT NOT NULL,
+      key        TEXT NOT NULL,
+      value      TEXT NOT NULL,
+      PRIMARY KEY (index_name, key)
+    )
+  `)
+
+  if (typo.enabled) {
+    try {
+      await sql.unsafe('CREATE EXTENSION IF NOT EXISTS pg_trgm')
+    } catch {
+      throw new MissingExtensionError('pg_trgm')
+    }
+    // fuzzystrmatch is optional — used to re-rank trigram candidates with a
+    // bounded Levenshtein. If absent we silently fall back to trigram-only.
+    try {
+      await sql.unsafe('CREATE EXTENSION IF NOT EXISTS fuzzystrmatch')
+    } catch {
+      // ignore
+    }
+  }
+}
+
+/**
+ * Idempotent: create the per-index table, GIN index, terms_dict, and trigger.
+ * Returns true if the table was newly created (caller may seed `_meta`).
+ */
+export async function ensureIndexTable(
+  sql: SQL,
+  schema: string,
+  index: string,
+  registry: FieldRegistry,
+  ginFastUpdate: boolean
+): Promise<boolean> {
+  const exists = await tableExists(sql, schema, bareIndexTable(index))
+  if (exists) return false
+
+  const typedColsDdl = registry.typedColumns
+    .map(c => `, ${quoteIdent(c.name)} TEXT GENERATED ALWAYS AS (${c.expression}) STORED`)
+    .join('')
+
+  await sql.unsafe(`
+    CREATE TABLE ${indexTableName(schema, index)} (
+      id   TEXT PRIMARY KEY,
+      doc  JSONB NOT NULL,
+      fts  tsvector NOT NULL DEFAULT ''::tsvector${typedColsDdl}
+    )
+  `)
+
+  await sql.unsafe(
+    `CREATE INDEX ${quoteIdent(`${bareIndexTable(index)}_fts_gin`)} ` +
+      `ON ${indexTableName(schema, index)} USING gin(fts) ` +
+      `WITH (fastupdate = ${ginFastUpdate ? 'on' : 'off'})`
+  )
+
+  for (const col of registry.typedColumns) {
+    await sql.unsafe(
+      `CREATE INDEX ${quoteIdent(`${bareIndexTable(index)}_${col.name}_idx`)} ` +
+        `ON ${indexTableName(schema, index)}(${quoteIdent(col.name)})`
+    )
+  }
+
+  // Belt-and-suspenders: if anyone INSERTs without computing fts, recompute it
+  // from doc using the current language + weight scheme. The driver always
+  // sets fts itself; the trigger only fires when the caller didn't.
+  await ensureFtsTrigger(sql, schema, index, registry)
+
+  await ensureTermsDict(sql, schema, index)
+
+  await sql.unsafe(
+    `INSERT INTO ${metaTableName(schema)} (index_name, key, value) VALUES ` +
+      `($1, 'schema_version', $2), ($1, 'language', $3), ($1, 'searchable', $4), ` +
+      `($1, 'filterable', $5), ($1, 'sortable', $6) ` +
+      `ON CONFLICT (index_name, key) DO NOTHING`,
+    [
+      index,
+      String(SCHEMA_VERSION),
+      registry.language,
+      JSON.stringify(registry.searchable),
+      JSON.stringify(registry.filterable),
+      JSON.stringify(registry.sortable),
+    ]
+  )
+
+  return true
+}
+
+export async function ensureTermsDict(sql: SQL, schema: string, index: string): Promise<void> {
+  const exists = await tableExists(sql, schema, bareTermsTable(index))
+  if (exists) return
+
+  await sql.unsafe(`
+    CREATE TABLE ${termsTableName(schema, index)} (
+      term     TEXT PRIMARY KEY,
+      doc_freq INTEGER NOT NULL DEFAULT 0
+    )
+  `)
+  await sql.unsafe(
+    `CREATE INDEX ${quoteIdent(`${bareTermsTable(index)}_trgm`)} ` +
+      `ON ${termsTableName(schema, index)} USING gin (term gin_trgm_ops)`
+  )
+  await sql.unsafe(
+    `CREATE INDEX ${quoteIdent(`${bareTermsTable(index)}_len`)} ` +
+      `ON ${termsTableName(schema, index)} (length(term))`
+  )
+}
+
+async function ensureFtsTrigger(
+  sql: SQL,
+  schema: string,
+  index: string,
+  registry: FieldRegistry
+): Promise<void> {
+  const fnName = `${bareIndexTable(index)}_fts_trigger`
+  const lang = quoteLiteral(registry.language)
+  const segments = registry.usesDefaultTextColumn
+    ? `setweight(to_tsvector(${lang}::regconfig, ${defaultTextProjection()}), 'A')`
+    : registry.searchable
+        .map(attr => {
+          const weight = registry.weights.get(attr)!
+          return `setweight(to_tsvector(${lang}::regconfig, coalesce(NEW.doc->>${quoteLiteral(attr)}, '')), '${weight}')`
+        })
+        .join(' || ')
+
+  await sql.unsafe(`
+    CREATE OR REPLACE FUNCTION ${quoteIdent(schema)}.${quoteIdent(fnName)}() RETURNS trigger AS $$
+    BEGIN
+      IF NEW.fts IS NULL OR NEW.fts = ''::tsvector THEN
+        NEW.fts := ${segments};
+      END IF;
+      RETURN NEW;
+    END;
+    $$ LANGUAGE plpgsql
+  `)
+
+  await sql.unsafe(`
+    CREATE TRIGGER ${quoteIdent(`${bareIndexTable(index)}_fts_trg`)}
+    BEFORE INSERT OR UPDATE ON ${indexTableName(schema, index)}
+    FOR EACH ROW EXECUTE FUNCTION ${quoteIdent(schema)}.${quoteIdent(fnName)}()
+  `)
+}
+
+function defaultTextProjection(): string {
+  // For default mode (no searchableAttributes) the trigger fallback walks
+  // every JSONB string value — same shape as the field_registry default.
+  return `(SELECT coalesce(string_agg(value, ' '), '') FROM jsonb_each_text(NEW.doc))`
+}
+
+async function tableExists(sql: SQL, schema: string, table: string): Promise<boolean> {
+  const rows = (await sql.unsafe(
+    `SELECT 1 AS present FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace ` +
+      `WHERE n.nspname = $1 AND c.relname = $2 AND c.relkind = 'r' LIMIT 1`,
+    [schema, table]
+  )) as Array<Record<string, unknown>>
+  return rows.length > 0
+}
+
+/** Drop a single index's tables and trigger function. Idempotent. */
+export async function dropIndex(sql: SQL, schema: string, index: string): Promise<void> {
+  await sql.unsafe(`DROP TABLE IF EXISTS ${indexTableName(schema, index)} CASCADE`)
+  await sql.unsafe(`DROP TABLE IF EXISTS ${termsTableName(schema, index)} CASCADE`)
+  await sql.unsafe(
+    `DROP FUNCTION IF EXISTS ${quoteIdent(schema)}.${quoteIdent(`${bareIndexTable(index)}_fts_trigger`)}() CASCADE`
+  )
+  await sql.unsafe(`DELETE FROM ${metaTableName(schema)} WHERE index_name = $1`, [index])
+}

package/src/drivers/postgres/engine/snippet_formatter.ts

@@ -0,0 +1,31 @@
+/**
+ * `ts_headline` returns text with literal `<mark>` / `</mark>` markers around
+ * matched terms. The surrounding text comes from the source document — which
+ * may itself contain HTML the caller didn't escape. We HTML-escape the
+ * snippet, then restore the marker tags, mirroring what the embedded driver
+ * does with sentinel markers.
+ */
+const OPEN_TAG = '<mark>'
+const CLOSE_TAG = '</mark>'
+const OPEN_PLACEHOLDER = '
STRAV_OPEN
'
+const CLOSE_PLACEHOLDER = '
STRAV_CLOSE
'
+
+export function formatSnippet(snippet: string | null | undefined): string {
+  if (!snippet) return ''
+  // Replace ts_headline's literal tags with sentinel control bytes that
+  // can't appear in source text, escape, then swap back.
+  const swapped = snippet
+    .replaceAll(OPEN_TAG, OPEN_PLACEHOLDER)
+    .replaceAll(CLOSE_TAG, CLOSE_PLACEHOLDER)
+  const escaped = escapeHtml(swapped)
+  return escaped.replaceAll(OPEN_PLACEHOLDER, OPEN_TAG).replaceAll(CLOSE_PLACEHOLDER, CLOSE_TAG)
+}
+
+function escapeHtml(input: string): string {
+  return input
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
+}