Skip to content

ADR-004: SQLite com FTS5 como Banco Principal

Status: Implementado (desde o início do projeto) Tipo: ADR Retroativo

Contexto

O app precisa de busca rápida em um catálogo offline de músicas que pode conter milhares de registros, com busca por título, letra, índice e rótulo litúrgico. Os dados são primariamente somente-leitura (catálogo) mas com dados do usuário misturados (repertórios, favoritos).

Decisão

Usar op-sqlite (SQLite com FTS5 habilitado) como único banco de dados do app, com:

  • Banco principal embarcado como asset (cantaIgreja.db)
  • Extensão via obras baixáveis (ATTACH/DETACH pattern)
  • Migrations versionadas via PRAGMA user_version
  • Tabela virtual FTS5 musica_busca para busca textual

Alternativas Consideradas

  • WatermelonDB — descartado (maior complexidade, sync focado em servidor)
  • Realm — descartado (licença, tamanho do bundle)
  • AsyncStorage + busca em memória — descartado (não escalável para milhares de músicas)
  • API online para busca — descartado (uso offline é requisito central)

Consequências

  • 🟢 Busca offline completa com ranking BM25 (título peso 50, letra peso 5)
  • 🟢 Pattern ATTACH/DETACH permite importar obras sem copiar arquivos inteiros
  • 🟢 FTS5 suporta normalização NFKD via tokenizer unicode61
  • 🟡 Schema dual (catálogo + usuário no mesmo banco) complica backups seletivos
  • 🟡 Migrations precisam ser idempotentes — algumas usam ALTER TABLE IF NOT EXISTS (check por pragma)
  • 🟢 PRAGMA user_version é simples e efetivo para versioning