jhonny-editor/rag/SETUP.md

Setup do banco RAG — Doza

Pré-requisito: o container compartilhado rag-hub-db já precisa estar rodando na VPS (/docker/rag-hub/, ver admin/VPS-ACCESS.md). Se ele ainda não existe, esse é um passo único para toda a infra, não deste projeto — consulte quem já configurou antes de recriar.

1. Abrir túnel SSH até o Postgres

O banco não tem porta pública. Toda conexão (local ou de outro projeto) passa por túnel SSH:

ssh -N -L 55435:127.0.0.1:55435 root@179.197.228.240

Mantenha esse comando rodando em um terminal enquanto for usar o banco. As credenciais SSH (host, chave) estão em admin/VPS-ACCESS.md.

2. Criar o banco deste projeto (só na primeira vez)

Conectado via túnel, como usuário admin do rag-hub-db (rag_admin, senha em admin/VPS-ACCESS.md na VPS):

psql -h 127.0.0.1 -p 55435 -U rag_admin -d postgres \
  -c "CREATE DATABASE rag_doza OWNER rag_admin;"

Se já existe (caso comum — este projeto já tem o banco criado), pule este passo.

3. Aplicar o schema

psql -h 127.0.0.1 -p 55435 -U rag_admin -d rag_doza -f rag/schema.sql

schema.sql é idempotente (CREATE EXTENSION IF NOT EXISTS, CREATE TABLE IF NOT EXISTS) — rodar de novo não duplica nem apaga dados.

4. Conferir

psql -h 127.0.0.1 -p 55435 -U rag_admin -d rag_doza -c '\dx' -c '\dt doza.*'

Deve listar as extensões vector e pg_trgm, e a tabela doza.code_chunks.

5. Configurar o código do projeto

Copiar .env.example para .env (fora do git) e preencher com os valores reais do túnel/credenciais — ver admin/VPS-ACCESS.md.

Evoluir o schema (banco que já existe)

Não edite schema.sql/schema-tigre.sql esperando que sejam reaplicados — eles descrevem o estado final, para bancos novos. Num banco existente, crie uma migration numerada em migrations/ e aplique:

rag/migrate_tigre.sh                                   # a mais recente
rag/migrate_tigre.sh rag/migrations/003-outra.sql      # uma específica

O script resolve a senha do rag_admin dentro da VPS — ela não passa pelo shell local. Depois de qualquer migration que mexa em como o embedding é gerado, reindexe com rag/index_tigre.sh --full, senão vetores de regimes diferentes convivem no mesmo índice.

Resetar do zero (se precisar)

psql -h 127.0.0.1 -p 55435 -U rag_admin -d postgres \
  -c "DROP DATABASE rag_doza;" \
  -c "CREATE DATABASE rag_doza OWNER rag_admin;"
psql -h 127.0.0.1 -p 55435 -U rag_admin -d rag_doza -f rag/schema.sql

⚠️ Isso apaga todo o índice/embeddings já gerados deste projeto — só é RAG de apoio ao desenvolvimento, então é seguro recriar e reindexar do zero quando fizer sentido (ex: mudança grande na estrutura do repo).