CoreData: debug: WAL checkpoint - O que significa esse log?

O log

Se você está vendo mensagens como esta no console do Xcode:

CoreData: debug: WAL checkpoint: Database did checkpoint. Log size: 1006 checkpointed: 1005

Pode ficar tranquilo. É uma mensagem informativa do sistema de persistência do CoreData e indica que tudo está funcionando corretamente.

O que é WAL?

WAL (Write-Ahead Logging) é o mecanismo que o SQLite usa para garantir a integridade dos dados. O CoreData usa SQLite como backend padrão, então herda esse comportamento.

O fluxo funciona assim:

Quando você salva dados, eles vão primeiro para um arquivo de log (.sqlite-wal)
O SQLite acumula várias escritas nesse log
Periodicamente, executa um checkpoint - transfere os dados do WAL para o arquivo principal do banco (.sqlite)

Esse mecanismo oferece duas vantagens:

Atomicidade: Se o app crashar no meio de uma escrita, os dados parciais ficam isolados no WAL e não corrompem o banco principal
Performance: Escritas sequenciais no log são mais rápidas que escritas aleatórias no banco

Por que esses logs aparecem?

Duas condições precisam estar presentes:

1. Modo debug ativo

O CoreData só emite esses logs quando está em modo debug. Isso acontece automaticamente em builds de desenvolvimento no Xcode. Em builds de release (App Store), esses logs não aparecem para o usuário final.

2. Atividade suficiente no banco

Checkpoints são disparados automaticamente quando:

O arquivo WAL atinge um certo tamanho
Há atividade suficiente de escrita
O sistema considera apropriado consolidar os dados

Operações como drag and drop, edições em lote ou sincronização com CloudKit geram múltiplas escritas e frequentemente disparam checkpoints.

E se eu uso SwiftData?

Se você usa SwiftData (iOS 17+/macOS 14+) e está vendo logs com prefixo "CoreData:", não estranhe. SwiftData é construído em cima do CoreData.

+------------------+
|    SwiftData     |  <-- API moderna (@Model, ModelContext, etc.)
+------------------+
         |
+------------------+
|    CoreData      |  <-- Roda internamente
+------------------+
         |
+------------------+
|     SQLite       |  <-- WAL checkpoint acontece aqui
+------------------+

Quando você salva um modelo SwiftData, a operação passa pelo CoreData internamente, que por sua vez persiste no SQLite. Os logs de debug vêm dessa camada intermediária.

A Apple não criou logs separados para SwiftData - ele herda os logs do CoreData que está rodando por baixo. Então mesmo em projetos 100% SwiftData, você verá CoreData: debug: WAL checkpoint.

Anatomia do log

Database did checkpoint. Log size: 1006 checkpointed: 1005
                         +----+-----+ +-----+----+
                              |             |
                              |             +-- Paginas transferidas
                              |                 para o banco principal
                              |
                              +-- Paginas no WAL antes do checkpoint

No exemplo acima:

1006 páginas estavam no WAL antes do checkpoint
1005 foram transferidas para o banco principal
A diferença (1) representa escritas que aconteceram durante o checkpoint

Essa diferença é normal em apps com atividade contínua. O SQLite transfere o que pode enquanto novas escritas continuam chegando.

Quando se preocupar

Na prática, não há motivo para preocupação. Se o log aparece com "Database did checkpoint", o checkpoint foi executado com sucesso.

Problemas reais com CoreData/SQLite se manifestam de outras formas:

Erros ao salvar o contexto (NSManagedObjectContext)
Exceções de CoreData no console
Dados não persistindo entre sessões

Se seu app está funcionando normalmente e você só vê os logs de WAL checkpoint, está tudo certo.

Como desativar esses logs

Se os logs estão poluindo seu console durante o desenvolvimento, você pode desativar os logs de debug do CoreData adicionando o argumento de lançamento -com.apple.CoreData.Logging.stderr 0 no scheme do Xcode:

Product -> Scheme -> Edit Scheme
Run -> Arguments -> Arguments Passed On Launch
Adicione -com.apple.CoreData.Logging.stderr 0

Alternativamente, use filtros no console do Xcode para ocultar mensagens contendo "WAL checkpoint".

Referências

SQLite Write-Ahead Logging - documentação oficial do mecanismo WAL
Core Data (Apple Documentation) - referência oficial atual
Core Data Programming Guide (Archive) - documentação histórica, útil para entender princípios arquiteturais que permanecem válidos