Prompt para Adicionar Pesquisa de Texto Completo no PostgreSQL

Prompt de IA copiável para adicionar pesquisa de texto completo nativa do PostgreSQL com tsvector, índice GIN e resultados ranqueados a um aplicativo Next.js existente.

Use este prompt para adicionar pesquisa de texto completo real do PostgreSQL a um aplicativo existente — usando tsvector, um índice GIN e ts_rank — sem que o agente recorra a Elasticsearch, Algolia ou uma API de busca de terceiros.

Prompt Principal

You are working in a Next.js App Router project with TypeScript and PostgreSQL (using the
`postgres` npm package, not Prisma or Drizzle).

Task: add full-text search over the `posts` table (columns: id, title, body, created_at).

Database changes:
1. Write a migration file `migrations/0010_add_fts.sql` that:
   - Adds a generated column: `search_vector tsvector GENERATED ALWAYS AS
     (to_tsvector('english', coalesce(title,'') || ' ' || coalesce(body,''))) STORED;`
   - Creates a GIN index: `CREATE INDEX posts_search_idx ON posts USING GIN (search_vector);`
2. Do NOT use `pg_trgm` or LIKE queries — use `@@` with `to_tsquery` or `websearch_to_tsquery`.

Application changes:
- Create `src/lib/search.ts` with a `searchPosts(query: string, limit = 20)` function that:
  - Uses `websearch_to_tsquery('english', $1)` to parse the query safely.
  - Returns rows ordered by `ts_rank(search_vector, query_vector) DESC`.
  - Returns `{ id, title, body_excerpt, rank }` — body_excerpt via `ts_headline`.
  - Uses parameterized queries only — no string interpolation.
- Create a Server Action `src/lib/actions/search.ts` that calls `searchPosts` and returns results.
- Create `src/components/SearchBox.tsx` (Client Component) with a debounced input (300 ms) that
  calls the Server Action via `useTransition` and renders results.

Do not install pg_search, Meilisearch, or any search service. Stop and list files before coding.

Notas de Implementação

websearch_to_tsquery é mais seguro que to_tsquery para entrada do usuário porque tolera consultas malformadas (operadores ausentes, caracteres especiais) sem lançar um erro no PostgreSQL.
A coluna tsvector gerada é atualizada automaticamente em INSERT/UPDATE — sem necessidade de triggers.
ts_headline requer o texto da coluna original e o vetor de consulta; passe ambos a partir do SELECT.
O índice GIN torna a busca rápida em tabelas grandes; sem ele, as consultas farão varredura sequencial.

Mudanças Esperadas nos Arquivos

migrations/0010_add_fts.sql              (new)
src/lib/search.ts                        (new)
src/lib/actions/search.ts               (new — Server Action)
src/components/SearchBox.tsx            (new — Client Component)

Critérios de Aceitação

psql -f migrations/0010_add_fts.sql executa sem erros no esquema existente.
Pesquisar por uma palavra que aparece apenas em title retorna o post correto.
Pesquisar por uma frase com um erro de digitação (por exemplo, “postgress”) não retorna resultados sem travar.
Os resultados são ordenados com os posts de maior relevância primeiro.

Comandos de Teste

psql "$DATABASE_URL" -f migrations/0010_add_fts.sql
bun run typecheck
bun run dev
# type a search term in SearchBox and verify ranked results appear
psql "$DATABASE_URL" -c "EXPLAIN ANALYZE SELECT * FROM posts WHERE search_vector @@ websearch_to_tsquery('english','test');"
# confirm "Index Scan using posts_search_idx" appears in output

Erros Comuns da IA

Usar LIKE '%query%' em vez do operador de texto completo @@.
Usar to_tsquery('english', $1) com entrada bruta do usuário — quebra em consultas como "foo bar".
Esquecer o índice GIN, deixando a busca como varredura sequencial.
Chamar searchPosts em um Client Component em vez de encapsulá-lo em uma Server Action.

Prompt de Correção

The search is using LIKE or crashing on special characters. Fix in order:
1. Replace any LIKE clause with `search_vector @@ websearch_to_tsquery('english', $1)`.
2. If `to_tsquery` is used directly with user input, replace it with `websearch_to_tsquery`.
3. Confirm the GIN index exists: `CREATE INDEX IF NOT EXISTS posts_search_idx ON posts USING GIN (search_vector);`
Show only the corrected diff. Do not modify unrelated files.