Banco de Dados
Room é o único mecanismo de persistência estruturada do app (ver Modelo de Dados para as entidades). Este documento cobre o banco em si: arquivo, versionamento e migrações.
Arquivo e instanciação
O nome padrão do arquivo é inkshelf.db. A classe do banco aceita um nome de arquivo como parâmetro e mantém um cache de instâncias abertas por nome — o que permite, tecnicamente, ter mais de um banco com esse mesmo schema aberto ao mesmo tempo, sob arquivos diferentes, sem que um interfira no outro.
Versionamento e migrações
O banco está na versão 24 (consulte InkShelfDatabase.kt, version = , pro número exato caso este documento fique defasado de novo), evoluído por uma cadeia de migrações incrementais desde a versão 2 — cada uma aplicando só a mudança de schema necessária (ALTER TABLE, criação de tabela nova, criação de índice), preservando os dados já existentes. Não há fallback destrutivo configurado: se uma migração não puder ser aplicada, a abertura do banco falha com uma exceção em vez de apagar e recriar o banco do zero.
Uma seleção de mudanças relevantes ao longo do histórico:
| Migração | O que mudou |
|---|---|
| 2 → 3 | Criação da tabela reading_history |
| 3 → 4 | Colunas de metadado ComicInfo.xml em files |
| 4 → 5 | Criação de daily_statistics e reading_sessions |
| 5 → 6 | Coluna isHidden em files e folders |
| 6 → 7 | Campo de progresso EPUB (epubScrollPercent) e criação de chapter_pagination_cache |
| 7 → 8 | lastModifiedAt em folders, usado na ordenação "Mais recente" |
| 8 → 9 | Campos adicionais de progresso EPUB (página global, total de páginas, zoom) |
| 9 → 10 | Criação de bookmarks |
| 10 → 11 | Rótulo opcional em bookmarks |
| 11 → 12 | Índices de performance em files e folders (ver Modelo de Dados) — sem eles, cada navegação de pasta ou listagem de favoritos/em-progresso varria a tabela inteira |
| 14 → 15 | Colunas komgaBookId/komgaLibraryId/komgaSeriesId — chegada do Komga |
| 16 → 17 | Criação de remote_sources/remote_libraries — schema genérico de fonte remota, preparando a chegada do Kavita ao lado do Komga |
| 17 → 18 | remoteSourceId/remoteItemId em files/folders — primeiro uso real das tabelas genéricas, pelo KavitaScanner |
| 18 → 19 | Organização por fonte (Pastas vs Séries) e remoteLibraryId em folders |
| 19 → 20 | Migração do Komga pra fonte remota genérica (múltiplos servidores Komga simultâneos, igual o Kavita já suportava) |
| 20 → 21 | Organização/modo de raiz/capas HQ migram de por-servidor pra por-biblioteca em remote_libraries; remoteLibraryId em files |
| 21 → 22 | localRootUri em files (pasta local de origem) e rootPath em remote_libraries — mais informações nos cards de Configurações |
| 22 → 23 | remoteVolumeId/remoteSeriesId em files — os 4 IDs que a API de progresso do Kavita exige, junto de remoteItemId/remoteLibraryId já existentes |
| 23 → 24 | localProgressUpdatedAt em files — janela de graça do merge de sync remoto (protege progresso local recém-feito, mas deixa o servidor vencer um reset explícito depois de alguns minutos) |
Migrações registradas por código, não geradas
Cada migração é escrita manualmente como SQL explícito, não gerada automaticamente a partir de um diff de schema — o que dá controle total sobre a instrução exata executada (por exemplo, um ALTER TABLE ... ADD COLUMN com valor padrão explícito para não deixar linhas existentes com campo nulo onde o modelo espera um booleano ou inteiro).