feat(database): migrar persistência de MariaDB para PostgreSQL #106

Objetivo

Migrar o ApplyWell backend de MariaDB para PostgreSQL, preservando todos os dados e contratos existentes (REST, MCP e Ask ApplyWell) e evitando dependências permanentes de dois SGBDs.

Stack atual identificada: Java 21, Spring Boot 4.1.1, Hibernate/JPA, Flyway e MariaDB. A migração deve considerar o ambiente de produção já existente, não apenas subir um PostgreSQL vazio.

Escopo

1. Dependências e configuração

• Substituir mariadb-java-client / mysql-connector-j pelo driver org.postgresql:postgresql no pom.xml; substituir flyway-mysql pelo módulo org.flywaydb:flyway-database-postgresql.
• Ajustar src/main/resources/application.yml: DB_URL com jdbc:postgresql://..., driver e dialeto Hibernate (preferir autodetecção quando adequado).
• Revisar o mapeamento UUID: hoje hibernate.type.preferred_uuid_jdbc_type: BINARY; definir estratégia compatível com o tipo uuid nativo do PostgreSQL e com os dados legados.
• Revisar application-test.yml, perfis e demais configurações que assumem MariaDB/MySQL.

2. Schema e Flyway

• Auditar src/main/resources/db/migration/ para incompatibilidades SQL (backticks, AUTO_INCREMENT, DDL/DML específicos, tipos BINARY/TINYINT, índices, constraints etc.).
• Definir estratégia reproduzível para inicializar o schema PostgreSQL equivalente ao schema atual, mantendo histórico de migrações rastreável. Não reescrever silenciosamente migrações já aplicadas em produção.
• Validar chaves primárias, estrangeiras, unicidade, índices, sequências/identity, defaults, timestamps/timezone, valores booleanos e conversão de UUID.
• Garantir que um PostgreSQL vazio inicialize com Flyway e passe em ddl-auto=validate sem correções manuais.

3. SQL específico e busca textual do chatbot

• Migrar AssistantApplicationQueryRepository: a query atual usa MATCH (...) AGAINST (... IN NATURAL LANGUAGE MODE) do MariaDB.
• Implementar busca com recursos nativos do PostgreSQL (ex.: tsvector/tsquery + índice GIN, se fizer sentido), preservando filtros por usuário autenticado, paginação/limites e ordenação determinística.
• Cobrir comportamento de tokens curtos/simbólicos (Go, AI, C#) e de registros arquivados.
• Revisar outras queries nativas e funções SQL específicas de MySQL/MariaDB.

4. Infraestrutura, CI e testes

• Atualizar docker-compose.yml, docker-compose.prod.yml, .env.example, documentação, variáveis/segredos e healthchecks.
• Atualizar workflows, incluindo .github/workflows/load-test.yml, que atualmente inicia MariaDB.
• Priorizar testes de integração com PostgreSQL real via Testcontainers, em vez de depender somente de H2 em MODE=MySQL; executar toda a suíte.
• Cobrir autenticação/OAuth, CRUD, relatórios/analytics, MCP, chatbot/FTS, exportações e jobs agendados.

5. Migração dos dados e cutover

• Criar procedimento testável de migração de schema + dados existentes, com tratamento de tipos, IDs, constraints e sequências.
• Realizar dry-run em ambiente isolado com cópia dos dados, sem alterar produção.
• Validar contagem de registros, integridade referencial, amostras de dados críticos e funcionamento da aplicação.
• Documentar backup com restauração testada, janela de manutenção/cutover, alteração de DB_URL, smoke tests e rollback para MariaDB caso a validação falhe.
• Manter a instância/dados antigos intactos até confirmação explícita de sucesso.

Critérios de aceite

• Backend inicializa e opera apenas com PostgreSQL em desenvolvimento, testes e produção.
• Flyway cria e valida o schema sem intervenção manual.
• Dados existentes preservados e reconciliados, sem perda ou corrupção.
• Endpoints REST, MCP, autenticação, relatórios e chatbot funcionam sem regressões.
• Busca textual continua segura (isolamento por usuário) e funcional.
• Testes automatizados e workflow de CI passam com PostgreSQL.
• Runbook de migração e rollback documentado e validado.

Referências no repositório

• pom.xml
• application.yml
• db/migration/
• AssistantApplicationQueryRepository
• docker-compose.prod.yml
• load-test.yml
• Issue #81: Ask ApplyWell e MariaDB FULLTEXT

Fora do escopo: mudanças de API ou novas funcionalidades no frontend. Prioridade é migração íntegra, com comportamento equivalente e custo de manutenção baixo.