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