Skip to content

Arch — Design Técnico

Gerado pelo Writer (Reversa) em 2026-05-11

Inicialização do Banco (Singleton)

Banco.instance()
  → database !== undefined → retorna diretamente
  → initializingPromise !== undefined → aguarda Promise
  → initializingPromise = initialize()
      → AssetDatabasePreparator.prepare('cantaIgreja.db')
          → moveAssetsDatabase (native) / copia (web)
      → openAsync(nome, { location: strategy.databasePath })
      → MigrationsRepository.runMigrations(db)
          → PRAGMA user_version
          → para v em pending: executa SQL + fn opcional + PRAGMA user_version = v
      → BibliotecaSugestoesRepertorioRepository.popularSugestoesIniciais()
      → Banco.database = db

BancoHooks — ATTACH/DETACH por Plataforma

Native (MobileBancoHooks)

attach(instancia, dbFileName, alias, path?) {
  instancia.attach({ secondaryDbFileName, alias, location? })
}
detach(instancia, alias) {
  instancia.detach(alias)
}

Web (WebBancoHooks) — com validação de segurança

attach(instancia, dbFileName, alias) {
  assertSafeSqliteIdentifier(alias)  // /^[A-Za-z_][A-Za-z0-9_]*$/
  assertSafeSqliteFileName(dbFileName) // /^[A-Za-z0-9._-]+$/
  await Banco.execute(`ATTACH DATABASE 'file:${escaped}?vfs=opfs' AS ${alias}`)
}
detach(instancia, alias) {
  assertSafeSqliteIdentifier(alias)
  await Banco.execute(`DETACH DATABASE ${alias}`)
}

Pipeline de Migrations

MigrationsRepository.runMigrations(db):
  versaoAtual = PRAGMA user_version
  para cada migration (v) em ordem crescente:
    se versaoAtual < v:
      execute SQL da migration
      se migration.fn: await migration.fn(db)
      PRAGMA user_version = v
      versaoAtual = v

API Pública do Banco

Método Assinatura Observação
execute (query, params?) → QueryResult Uso geral
executeBatch (queries: SQLBatchTuple[]) → BatchQueryResult Múltiplas queries
prepareStatement (query) → PreparedStatement Reutilização
attachFromCache (path, alias) → void Download cache
attachFromAssets (dbName, alias) → void Asset local
detach (alias) → void Cleanup obrigatório

Segurança

  • Web: regex impede SQL injection em ATTACH DATABASE via alias e filename
  • Native: instancia.attach() usa API tipada — sem interpolação de string
  • WebBancoHooks.escapeSqliteStringLiteral escapa ' → '' no filename

Riscos e Lacunas

  • 🟡 Migrations v12 e v14 não lidas completamente — SQL não documentado aqui
  • 🟡 AssetDatabasePreparator não lido — lógica de cópia do asset não confirmada
  • 🟡 Web OPFS: cachePath virtual — comportamento de attachFromCache na web não totalmente mapeado (ver repo memory op-sqlite-web-attach-workaround.md)
  • 🔴 Singleton sem reset — testes unitários podem ter contaminação de estado entre testes