収録章構成(全3章)
| 章 | タイトル | 文字数 | 区分 |
|---|---|---|---|
| 第1章 | 【Python実装】SQLite WAL無副作用スナップショット読取とflock競合制御:実機計測と検証コード | 17,929文字 | 無料プレビュー収録 |
| 第2章 | AIの「直したら壊れた」ループを防ぐ設計:57行AGENTS.mdでトークン95%削減、別AIの3往復レビューと¥0ゲート | 32,780文字 | 本編収蔵章 |
| 第3章 | Playwrightブラウザ自動投稿の『二重送信・CAPTCHA無限ループ』を完封するAt-Most-Once状態機械とPython実装 | 32,625文字 | 本編収蔵章 |
無料公開プレビュー(第1章): 【Python実装】SQLite WAL無副作用スナップショット読取とflock競合制御:実機計測と検証コード
単一ホスト上で複数のPython自律ワーカー(定期スケジューラ、状態監視デーモン、制作バッチ)を同時に稼働させると、SQLiteまわりの2つの静かな障害に突き当たります。
1つ目は **WALモードDBの「読み取り専用のはずの監視処理」が -shm ファイル生成を試みて失敗する問題** です。監視プロセスやバックアップ機構が読み取り専用権限(たとえば 0o555 ディレクトリ)やロック競合下で sqlite3.connect("file:...?mode=ro", uri=True) を開こうとすると、SQLiteが -shm 共有メモリインデックスを初期化しようとして sqlite3.OperationalError: attempt to write a readonly database で落ちるケースがあります。さらに共有状態ディレクトリ上で不用意にリーダーがファイルを作ると、後続ワーカーとの間で権限・マウント境界の不整合を起こします。
2つ目は 排他制御の非対称性によるスケジュールスキップ暴走 です。バッチ制作ジョブが長時間 flock で排他ロックを握っている間に1分間隔のスケジューラが起動した際、非ブロッキングの LOCK_EX | LOCK_NB を1回だけ試して即座に例外クラッシュさせると、プロセス監視上は「毎時ユニット失敗(EXIT_FAILURE)」が積み上がり、復旧待機中のキューも詰まります。逆に上限なしのブロッキング待ちにすると、多重起動したプロセスがメモリとプロセス枠を食い潰します。
本記事では、Python 3.12 標準ライブラリのみを使ってこの2つの問題を根治する 2層防御パターン を実装・検証コードつきで解説します。
この記事で解決する設計課題と結論
| 障害パターン | 従来の落とし穴 | 本設計(検証済み) | 実機計測値 |
|---|---|---|---|
| WAL読取の副作用・権限エラー | mode=ro でも -shm 不在時に書込失敗 | メインDB+-wal を順次読込しRAM上でページ結合、sqlite3.deserialize() へ渡す | 1,000行WAL復元 p50 6.44 ms(-shm 生成ゼロ) |
| クラッシュ後の不完全WAL | 破損テールや未コミットページを読んで不整合 | salt1/salt2・累積チェックサム・db_size > 0 境界で切り捨て検証 | 破損テール付加後も既コミット2TXのみ厳密復元 |
ワーカー間の flock 衝突 | 即時クラッシュまたは無限待機でプロセス滞留 | 決定論的ジッタ付き指数バックオフ+タイムアウト時 Fail-Closed 退避 | 無競合獲得 p50 13.65 us / タイムアウト時FD漏れ0 |
この設計の要点は 「状態判定の純粋ロジック(Functional Core)」と「OSシステムコールの薄いアダプタ(Imperative Shell)」を明確に分離すること にあります。
実機検証の前提と計測環境(本記事で実測した範囲)
本記事の数値はすべて同一のローカル環境(Python 3.12 / SQLite flagship-verification-receipt相当の sqlite3 3.45.1)で test_sqlite_wal_flock_guard.py(全6テスト+ベンチマーク)を実実行して取得した実測値です。架空のハードウェア性能や推定値は含めていません。
- スナップショット読取対象:
journal_mode=WAL、wal_autocheckpoint=0で1,000行をコミット直後の未チェックポイント状態(本体4096bytes / WAL164832bytes / コミット済み40フレーム) - 読取レイテンシ(30回反復):
p50 = 6.437 ms、p95 = 7.557 ms、max = 7.735 ms - **無競合
flock取得+解放(50回反復)**:p50 = 13.65 us、p95 = 16.26 us - **
0o555読取専用ディレクトリ検査**: 標準file:...?mode=roは-shm不在時にOperationalErrorを送出することを確認した上で、本スナップショット方式は-shmを一切生成せず全レコードを読み取れることを確認
適用限界(使ってはいけないケース)
本手法は万能ではありません。次のワークロードには不向きです。
- 数百MB〜数GBの巨大DBに対する毎秒クエリ: インメモリスナップショット生成のため、DB本体+WALサイズと同等のRAMを一時消費します。数MB〜数十MBまでの状態管理DB・ジョブ台帳・テレメトリDBを想定しています。
- **NFSなど
fcntl.flockが共有カーネルで一貫しない分散ストレージ**: 同一カーネル内のプロセス間排他が前提です。複数ホストにまたがる場合は別機構が必要です。
関連する自律ワーカー基盤の設計記録として、以下の実機ベンチマーク記事もあわせて参考になります。
- 関連実測記録: https://note.com/shiroi1229/n/n9b2f053609f7
1. アーキテクチャ全体像:純粋コアとOSアダプタの分離
WAL無副作用スナップショット読取と有界 flock 制御を運用しやすくする最大のコツは、バイト列解析とバックオフ計算を I/Oを持たない純粋Pythonコア に閉じ込め、ファイル読込・sqlite3.deserialize・fcntl.flock だけを十数行の薄いOSアダプタに隔離することです。これにより、WALのチェックサム検証やクラッシュ復旧のエッジケースを、ファイルシステムやプロセス競合に依存せず決定論的に単体テストできます。
2. WAL バイナリ構造とチェックサム検証(完全実装&単体テスト)
SQLite WAL 先頭32バイトのヘッダには以下の情報が格納されています。
[0:4]マジックナンバー(ビッグエンディアン読取):0x377F0682(32bitワードのチェックサム計算がリトルエンディアン)または0x377F0683(ビッグエンディアン)[4:8]フォーマット版3007000、[8:12]ページサイズ(2の冪乗)、[16:24]salt1 / salt2、[24:32]ヘッダチェックサム- 各フレームは **24バイトヘッダ+
page_sizeバイト本文** で構成され、累積チェックサム(s0, s1)は前フレームからの引き継ぎでframe_header[0:8]とpage_dataに対して計算されます。db_size > 0のフレームだけがトランザクションのコミット境界です。
また、インメモリバッファを sqlite3.Connection.deserialize() へ渡す直前、メモリ上のバッファ内に限り SQLite ヘッダの [18:20] バイト目(書込/読取フォーマットバージョン)を 2(WAL)から 1(従来ジャーナル)へ書き換えることで、deserialize() がディスク上の -shm や -wal を参照しようとして失敗する罠を回避します。ディスク上の元ファイルは1ビットも変更しません。
以下のコードは標準ライブラリのみで完結しており、ヘッダ生成・コミット境界解決・破損テール切り捨て・RAMヘッダ正規化の自己検証テストを含みます。
from __future__ import annotations
import dataclasses
from typing import Optional
WAL_MAGIC_LE = 0x377F0682
WAL_MAGIC_BE = 0x377F0683
WAL_FORMAT_VERSION = 3007000
WAL_HEADER_BYTES = 32
WAL_FRAME_HEADER_BYTES = 24
SQLITE_HEADER_MAGIC = b"SQLite format 3\x00"
@dataclasses.dataclass(frozen=True)
class WalHeader:
magic: int
big_endian_checksum: bool
format_version: int
page_size: int
checkpoint_seq: int
salt1: int
salt2: int
csum1: int
csum2: int
@dataclasses.dataclass(frozen=True)
class WalOverlayReport:
wal_present: bool
wal_header_valid: bool
page_size: int
committed_tx_count: int
committed_frame_count: int
uncommitted_tail_frames: int
stop_reason: str
committed_db_pages: int
snapshot_bytes_len: int
def wal_checksum_step(
chunk: bytes | bytearray,
s0: int,
s1: int,
*,
big_endian: bool,
) -> tuple[int, int]:
if len(chunk) % 8 != 0:
raise ValueError(f"8バイト境界ではないチャンクです: {len(chunk)}")
byteorder = "big" if big_endian else "little"
mask = 0xFFFFFFFF
for off in range(0, len(chunk), 8):
x0 = int.from_bytes(chunk[off : off + 4], byteorder)
x1 = int.from_bytes(chunk[off + 4 : off + 8], byteorder)
s0 = (s0 + x0 + s1) & mask
s1 = (s1 + x1 + s0) & mask
return s0, s1
def _u32_be(buf: bytes, offset: int) -> int:
return int.from_bytes(buf[offset : offset + 4], "big")
def parse_wal_header(wal_bytes: bytes) -> WalHeader:
if len(wal_bytes) < WAL_HEADER_BYTES:
raise ValueError(f"WALヘッダ長不足: {len(wal_bytes)}")
magic = _u32_be(wal_bytes, 0)
if magic not in (WAL_MAGIC_LE, WAL_MAGIC_BE):
raise ValueError(f"未知のWALマジック値: 0x{magic:08x}")
big_endian = magic == WAL_MAGIC_BE
fmt_ver = _u32_be(wal_bytes, 4)
if fmt_ver != WAL_FORMAT_VERSION:
raise ValueError(f"非対応フォーマット版: {fmt_ver}")
page_size = _u32_be(wal_bytes, 8)
if page_size < 512 or page_size > 65536 or (page_size & (page_size - 1)) != 0:
raise ValueError(f"不正なページサイズ: {page_size}")
ckpt_seq = _u32_be(wal_bytes, 12)
salt1 = _u32_be(wal_bytes, 16)
salt2 = _u32_be(wal_bytes, 20)
csum1 = _u32_be(wal_bytes, 24)
csum2 = _u32_be(wal_bytes, 28)
calc0, calc1 = wal_checksum_step(wal_bytes[:24], 0, 0, big_endian=big_endian)
if (calc0, calc1) != (csum1, csum2):
raise ValueError("WALヘッダチェックサム不一致")
return WalHeader(magic, big_endian, fmt_ver, page_size, ckpt_seq, salt1, salt2, csum1, csum2)
def resolve_committed_wal_pages(
wal_bytes: bytes,
) -> tuple[Optional[WalHeader], dict[int, bytes], int, int, int, int, str]:
if not wal_bytes:
return None, {}, 0, 0, 0, 0, "empty_wal"
if len(wal_bytes) < WAL_HEADER_BYTES:
return None, {}, 0, 0, 0, 0, "truncated_wal_header"
try:
hdr = parse_wal_header(wal_bytes)
except ValueError as exc:
return None, {}, 0, 0, 0, 0, f"invalid_wal_header:{exc}"
frame_size = WAL_FRAME_HEADER_BYTES + hdr.page_size
s0, s1 = hdr.csum1, hdr.csum2
committed_pages: dict[int, bytes] = {}
pending_pages: dict[int, bytes] = {}
committed_db_pages = 0
committed_tx_count = 0
committed_frame_count = 0
stop_reason = "eof"
pos = WAL_HEADER_BYTES
while pos + frame_size <= len(wal_bytes):
fhdr = wal_bytes[pos : pos + WAL_FRAME_HEADER_BYTES]
page_data = wal_bytes[pos + WAL_FRAME_HEADER_BYTES : pos + frame_size]
if (_u32_be(fhdr, 8), _u32_be(fhdr, 12)) != (hdr.salt1, hdr.salt2):
stop_reason = "salt_mismatch_old_generation"
break
s0, s1 = wal_checksum_step(fhdr[:8], s0, s1, big_endian=hdr.big_endian_checksum)
s0, s1 = wal_checksum_step(page_data, s0, s1, big_endian=hdr.big_endian_checksum)
if (s0, s1) != (_u32_be(fhdr, 16), _u32_be(fhdr, 20)):
stop_reason = "frame_checksum_mismatch"
break
page_no = _u32_be(fhdr, 0)
db_size = _u32_be(fhdr, 4)
if page_no == 0:
stop_reason = "invalid_page_zero"
break
pending_pages[page_no] = page_data
if db_size > 0:
committed_pages.update(pending_pages)
committed_frame_count += len(pending_pages)
pending_pages.clear()
committed_db_pages = db_size
committed_tx_count += 1
pos += frame_size
if stop_reason == "eof" and pos < len(wal_bytes):
stop_reason = "truncated_tail_frame"
return hdr, committed_pages, committed_db_pages, committed_tx_count, committed_frame_count, len(pending_pages), stop_reason
def assemble_snapshot_bytes(db_bytes: bytes, wal_bytes: bytes = b"") -> tuple[bytes, WalOverlayReport]:
if len(db_bytes) < 100 or db_bytes[:16] != SQLITE_HEADER_MAGIC:
raise ValueError("有効なSQLite3ヘッダではありません")
raw_ps = int.from_bytes(db_bytes[16:18], "big")
base_ps = 65536 if raw_ps == 1 else raw_ps
hdr, committed_pages, db_pages, tx_cnt, fr_cnt, uncomm_cnt, reason = resolve_committed_wal_pages(wal_bytes)
ps = hdr.page_size if hdr is not None else base_ps
target_len = db_pages * ps if db_pages > 0 else len(db_bytes)
buf = bytearray(db_bytes[:target_len])
if len(buf) < target_len:
buf.extend(b"\x00" * (target_len - len(buf)))
for page_no, page_data in committed_pages.items():
start = (page_no - 1) * ps
if start + ps <= len(buf):
buf[start : start + ps] = page_data
if buf[18] == 2:
buf[18] = 1
if buf[19] == 2:
buf[19] = 1
report = WalOverlayReport(bool(wal_bytes), hdr is not None, ps, tx_cnt, fr_cnt, uncomm_cnt, reason, len(buf) // ps, len(buf))
return bytes(buf), report
def _build_synthetic_wal(page_size: int, frames: list[tuple[int, int, bytes]]) -> bytes:
salt1, salt2 = 0x11223344, 0x55667788
prefix = (
WAL_MAGIC_LE.to_bytes(4, "big")
+ WAL_FORMAT_VERSION.to_bytes(4, "big")
+ page_size.to_bytes(4, "big")
+ (0).to_bytes(4, "big")
+ salt1.to_bytes(4, "big")
+ salt2.to_bytes(4, "big")
)
s0, s1 = wal_checksum_step(prefix, 0, 0, big_endian=False)
out = bytearray(prefix + s0.to_bytes(4, "big") + s1.to_bytes(4, "big"))
for page_no, db_size, payload in frames:
meta8 = page_no.to_bytes(4, "big") + db_size.to_bytes(4, "big")
s0, s1 = wal_checksum_step(meta8, s0, s1, big_endian=False)
s0, s1 = wal_checksum_step(payload, s0, s1, big_endian=False)
out.extend(meta8 + salt1.to_bytes(4, "big") + salt2.to_bytes(4, "big") + s0.to_bytes(4, "big") + s1.to_bytes(4,