AKASHIC ZERO

【Python実装】SQLite WAL無副作用スナップショット読取とflock競合制御:実機計測と検証コード

SQLite WAL無副作用スナップショット読取とflock競合制御:実機計測と検証コード — 境界条件の検証コード・監査レシート・導入手順を同梱した実践技術キット。

PythonSQLite個人開発生成AIシステム設計

単一ホスト上で複数の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行をコミット直後の未チェックポイント状態(本体 4096 bytes / WAL 164832 bytes / コミット済み 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

ご案内(対象読者・収録物・返金ポリシー)

  • 対象読者: Python でローカル自律システム・CLIツール・バッチワーカーの SQLite 並行制御を標準ライブラリだけで堅牢化したい開発者
  • 有料パート収録物:
  1. SQLite WAL バイナリヘッダ・累積チェックサム検証&メモリ内ページ合成の完全Pythonコード(単体検証テスト付き)
  2. 決定論的ジッタ付き有界バックオフ(LockRetryBudget)と LockBusy 安全退避の状態設計コード(単体検証テスト付き)
  3. 競合シミュレーション比較コード・設計判断表・実運用の障害チェックリスト・OSシステムコール接続仕様(sqlite3.deserialize / fcntl.flock)および生テスト出力ログ
  • 価格・返金: ¥380(note公式の返金申請に対応しています)
FREE TECHNICAL BRIEFING

実測ポストモーテム・修正パッチの続報を受け取る

一次検証データ・Fail-Closed 境界実装・新規無料記事の公開時にのみ配信します(広告なし・いつでも1クリック解除可能)。プライバシーポリシーに同意のうえご登録ください。

購読管理フォームを別タブで開く ↗