SQLite WAL(Write-Ahead Logging) 모드의 읽기·쓰기 동시성과 체크포인트 제어
SQLite의 WAL 모드가 읽기 트랜잭션과 쓰기 트랜잭션의 동작을 어떻게 바꾸는지, 체크포인트가 WAL 내용을 데이터베이스 파일에 반영하는 방식을 설명합니다. WAL에서도 쓰기 작업은 한 번에 하나이며, 오래된 읽기 스냅샷과 잠금은 체크포인트 진행을 제한할 수 있습니다.
발행·오류 제보: infostoa · 편집 기준
이 글의 개별 작성자와 전문 검토자 정보는 제공되지 않습니다.
SQLite 롤백 저널 모드에서는 쓰기 트랜잭션이 변경 전 페이지를 저널에 기록한 뒤 데이터베이스 파일을 갱신합니다. WAL 모드는 변경을 별도 로그에 기록해 읽기와 쓰기가 서로 다른 방식으로 진행되도록 합니다. 다만 WAL도 쓰기 트랜잭션은 한 번에 하나이며, 잠금·체크포인트·장기 읽기 트랜잭션에 따른 제약이 있습니다. 따라서 모든 읽기와 쓰기가 항상 서로를 막지 않는다고 설명할 수 없습니다.
2. WAL(Write-Ahead Log) 모드의 추가 전용 쓰기와 공유 메모리(-shm) 색인
WAL 모드에서는 변경 페이지가 별도 WAL 파일에 추가되고, 읽기 트랜잭션은 시작 시점의 스냅샷을 기준으로 데이터베이스 페이지와 WAL 프레임을 읽습니다. 이 방식은 읽기와 쓰기의 상호작용을 롤백 저널 모드와 다르게 하지만, 동시에 여러 쓰기를 허용하지는 않습니다. SQLite 문서는 WAL 모드에서도 일부 상황에서 SQLITE_BUSY가 발생할 수 있다고 설명하므로 무조건적인 비차단 동시성이나 성능 개선으로 표현하지 않아야 합니다.
WAL 색인은 공유 메모리에 두며, 이 점이 여러 프로세스가 데이터베이스를 사용할 때 같은 호스트에 있어야 하는 이유 중 하나입니다. 데이터베이스와 WAL 파일을 네트워크 파일시스템에 두고 여러 호스트에서 공유하는 구성은 SQLite가 지원하는 WAL 사용 방식이 아닙니다. 배포 전에 파일 위치와 프로세스 경계를 확인하고, 여러 서버에서 동시에 접근해야 한다면 별도의 클라이언트·서버 데이터베이스 구조가 필요한지 검토하세요.
3. 체크포인트 진행과 WAL 크기를 함께 보기
체크포인트는 WAL의 유효 프레임을 데이터베이스 파일에 반영합니다. SQLite 기본 설정은 WAL이 약 1,000페이지에 도달한 커밋에서 자동 체크포인트를 시작하지만, 이는 WAL 크기 상한이나 파일 축소 보장이 아닙니다. 각 읽기 트랜잭션은 시작 때 WAL의 마지막 유효 커밋 위치인 end mark를 기억합니다. 체크포인트는 현재 독자의 end mark를 넘어선 WAL 페이지에 도달하면 그 지점에서 멈춥니다. 이를 “end mark 이전 프레임을 덮어쓸 수 없다”로 뒤집어 말하면 안 됩니다. 체크포인트는 진행 위치를 기억해 다음 실행에서 이어갈 수 있습니다. 겹치는 읽기가 계속되어 완료할 틈이 없으면 WAL이 커질 수 있습니다.
기본 자동 체크포인트는 PASSIVE이며, 다른 연결의 읽기·쓰기가 끝나기를 기다리지 않고 가능한 프레임까지만 처리할 수 있습니다. sqlite3_wal_checkpoint_v2()의 모드 정의를 분리해 읽으세요. FULL은 기존 독자가 최신 스냅샷을 읽을 때까지 기다리고 새 쓰기 시도를 막지만 새 읽기는 허용합니다. RESTART는 여기에 WAL을 처음부터 재사용할 수 있도록 기존 독자가 WAL 사용을 마칠 때까지 더 기다립니다. TRUNCATE는 RESTART처럼 진행한 뒤 성공 직전에 WAL 파일을 0바이트로 자릅니다. 이 API 설명에서 FULL·RESTART가 “독자를 막는다”는 뜻은 아닙니다. WAL 개요의 §6은 RESTART/TRUNCATE 중 독자가 막힐 수 있다고 더 넓게 경고하므로, 연결 API·버전·호출 경로를 확인하고 관측 전 이를 모든 모드에 일반화하지 마세요. WAL 크기만 임계값과 비교하지 말고, 같은 시간 구간의 읽기 트랜잭션 수명과 로그/체크포인트 프레임 수를 함께 살펴보세요.
4. Litestream 복제는 체크포인트 책임이 다를 수 있다
Fly.io가 소개한 Litestream 구성에서는 복제기가 WAL을 읽는 트랜잭션을 열어 SQLite의 자동 체크포인트를 막고, WAL 변경을 직접 복제한 뒤 체크포인트도 직접 실행합니다. 이는 해당 도구의 구현 사례이며 모든 복제 도구가 같은 방식으로 동작한다는 뜻은 아닙니다. 자동 체크포인트가 진행되지 않거나 WAL이 계속 커지는 상황을 조사할 때는 복제기가 읽기 트랜잭션과 체크포인트를 어떻게 조정하는지, 복제 지연·복원 절차가 어떻게 동작하는지 해당 버전의 문서와 시험으로 확인하세요. 이 사례는 무손실·실시간 복제 보장이 아닙니다.
동시 쓰기·체크포인트 배포 점검
2026-10-12 확인한 SQLite WAL §11은 WAL 재설정 경합으로 손상이 발생할 수 있는 매우 드문 버그를 설명합니다. 설명된 조건은 같은 WAL 데이터베이스를 여는 둘 이상의 연결이 별도 스레드나 프로세스에 있고, 쓰기와 체크포인트가 매우 좁은 시점에 겹치는 경우입니다. SQLite 문서 기준으로 3.51.3 이상에서 수정되었고, 일부 이전 계열에는 3.44.6 및 3.50.7 수정판이 있습니다. 먼저 배포 바이너리의 실제 SQLite 버전을 확인하고, 해당 다중 연결·동시 쓰기/체크포인트 패턴을 쓰는지 확인하세요. 모든 WAL 배포에 동일한 긴급성이나 발생 가능성을 뜻하지 않습니다.