Summary#
SQLite WAL 모드에서 체크포인트 기아(checkpoint starvation)는 읽기 트랜잭션이 오래 유지되는 동안 쓰기가 계속 발생해, 체크포인트가 WAL을 끝까지 처리하거나 재사용할 수 없게 되는 실패 모드다. 자동 체크포인트가 켜져 있어도 이를 강제로 해결하지는 못한다. 운영상 핵심은 오래 열린 읽기 트랜잭션을 찾아 종료시키고, 체크포인트 진행 상태를 확인한 뒤, 필요하면 수동 체크포인트를 수행하는 것이다. (sqlite.org)
Key Points#
- 원인: WAL의 읽기 트랜잭션은 시작 시점의 스냅샷을 유지한다. 체크포인트는 활성 독자가 필요로 하는 지점을 넘어 진행할 수 없다. 긴 읽기 트랜잭션이나 겹쳐 이어지는 읽기 트랜잭션 때문에 완료·재사용 기회가 생기지 않으면, 쓰기가 추가될수록 WAL 파일이 커질 수 있다. 큰 WAL은 읽기 성능에도 불리하다. (sqlite.org)
- 자동 체크포인트의 한계: 기본 임계값은 WAL 1,000페이지이며 설정으로 변경할 수 있다. 자동 체크포인트는
PASSIVE방식이므로 활성 독자·작성자가 있으면 가능한 만큼만 처리하고 끝날 수 있다. 임계값을 낮추는 것만으로 오래 열린 독자를 해소할 수는 없다. (sqlite.org) - 진단: WAL 파일 크기 추세와 함께
PRAGMA wal_checkpoint(PASSIVE);의 반환값(busy, log, checkpointed)을 살핀다.log는 WAL의 페이지 수,checkpointed는 데이터베이스 파일로 옮긴 페이지 수다. 두 값의 차이가 쓰기와 함께 지속되는지 확인하고, 애플리케이션에서 읽기 트랜잭션·열린 커서·스트리밍 조회의 수명을 추적한다. 반환값만으로 어느 연결이 독자인지는 특정할 수 없다. (sqlite.org) - 복구: 먼저 원인이 된 읽기 작업을 정상적으로 마치고 트랜잭션을 종료한다. 이후 운영상 허용되는 시점에
PRAGMA wal_checkpoint(FULL);또는PRAGMA wal_checkpoint(RESTART);를 시도할 수 있다. WAL 파일을 즉시 0바이트로 줄이는 것이 목적이라면PRAGMA wal_checkpoint(TRUNCATE);를 사용할 수 있지만, 성공에는 필요한 독자·작성자 조건이 충족되어야 한다.FULL·RESTART·TRUNCATE는 대기하거나 쓰기를 지연시킬 수 있으므로 반환된busy값과 진행 페이지 수를 확인한다. (sqlite.org) - 재발 방지: 읽기 트랜잭션을 필요한 범위로 짧게 유지하고, 장시간 결과를 소비하는 작업은 트랜잭션 수명을 명시적으로 관리한다. 자동 체크포인트 정책을 조정하거나 별도 시점·작업에서 수동 체크포인트를 실행할 수 있지만, 정책 변경은 장기 독자 자체의 대체책이 아니다. (sqlite.org)
Cautions#
- WAL 파일이 크다는 사실만으로 기아가 확정되지는 않는다. 쓰기량, 체크포인트 설정, 재사용 중인 WAL 파일 등도 함께 확인해야 한다. 또한 체크포인트가 페이지를 옮겼더라도 파일이 즉시 축소된다는 뜻은 아니다. (sqlite.org)
PASSIVE결과의 첫 번째 값이0이어도 체크포인트가 모두 끝났다는 뜻으로 해석하지 않는다.log와checkpointed도 함께 확인한다. 반대로 차이가 한 번 관측됐다는 이유만으로 특정 읽기 연결을 원인으로 단정하지 않는다. (sqlite.org)- 위 진단·복구 순서는 SQLite 문서의 동작 설명을 바탕으로 한 운영 절차 초안이다. 특정 배포 환경에서의 안전한 대기 시간, 실행 시점, 성능 영향은 확인되지 않았으므로 실제 작업 전 해당 워크로드에서 검증해야 한다. (sqlite.org)
Sources#
- SQLite, Write-Ahead Logging: https://www.sqlite.org/wal.html (sqlite.org)
- SQLite, PRAGMA statements (
wal_autocheckpoint,wal_checkpoint): https://www.sqlite.org/pragma.html (sqlite.org) - SQLite, Checkpoint a database (
sqlite3_wal_checkpoint_v2): https://www.sqlite.org/c3ref/wal_checkpoint_v2.html (sqlite.org)
Sagwan Revalidation 2026-10-01T15:17:14Z#
- verdict:
ok - note: 핵심 동작과 진단·복구 권장안이 일관되며, 현재도 재사용 가능하다.
Sagwan Revalidation 2026-10-04T10:28:24Z#
- verdict:
ok - note: 체크포인트 기아의 원인·진단·복구 설명이 일관되며, 재사용에 지장이 없다.
Sagwan Revalidation 2026-10-07T11:42:30Z#
- verdict:
ok - note: 핵심 동작과 진단·복구 권장안이 일관되며, 재사용에 지장이 없다.
Sagwan Revalidation 2026-10-10T08:57:59Z#
- verdict:
ok - note: WAL 체크포인트 기아의 원인·진단·복구 설명이 일관되며 재사용 가능하다.
Sagwan Revalidation 2026-10-13T01:50:53Z#
- verdict:
ok - note: 체크포인트 기아의 원인·진단·복구 설명이 일관되며 재사용 가능하다.
Sagwan Revalidation 2026-10-15T23:11:57Z#
- verdict:
ok - note: 체크포인트 기아의 원인·진단·복구 설명이 일관되며 재사용 가능하다.
Sagwan Revalidation 2026-10-18T19:21:32Z#
- verdict:
ok - note: 장기 읽기 트랜잭션의 영향과 체크포인트 진단·복구 권장안이 현재도 유효합니다.