active: true
derived: false
groups:
- DB
header: |
  SQLite書き込みタスクのキャンセル戦略
level: 1.51
links:
- ARCH003: hztRUPwAahIBkVhPgOSP_qIfRnh6FSkrUlxLmmzOQg8=
- REQ019: -fKZXaJcRIvlKc33dQlwqZp5NX4u9a8fhsbFwR9tK0k=
normative: true
ref: ''
reviewed: rLFDeF0Nl7Sp-8GK1IgKEV4liKBY3qHLsAGtw5g6UCw=
status: accepted
text: |
  # SQLite書き込みタスクのキャンセル戦略

  ## コンテキストと課題

  `db.py` (`SQLiteTaskDB`) では、バックグラウンドでの書き込みを直列化するために専用の Writer スレッドとキューを使用しています。シャットダウン時 (`shutdown(wait=True)`) には、キューに積まれた全てのタスクの完了を待機しますが、タイムアウトが発生した場合の振る舞いが問題となります。特に、現在実行中 (RUNNING) の書き込みタスクを強制的にキャンセルすべきかどうかの設計判断が求められました。

  ## 判断基準

  * **Data Integrity**: SQLiteデータベースファイルの破損や不整合を絶対に防ぐこと。
  * **Predictability**: 実行中のトランザクションが予測不能な状態で中断されないこと。
  * **Responsiveness**: シャットダウン処理が完全にフリーズしないこと（タイムアウトの尊重）。

  ## 検討した選択肢

  * **Option 1**: タイムアウト時に、実行中のタスクであってもスレッドを強制終了、または接続を強制的に閉じてキャンセルする。
  * **Option 2**: PENDING (待機中) のタスクは破棄するが、RUNNING (実行中) のタスクは絶対にキャンセルせず、完遂を待つ（警告ログのみ出力）。

  ## 決定事項

  採用した選択肢: **Option 2**.

  実行中の書き込みタスク (RUNNING) は、タイムアウト時間を超過した場合でも強制的にキャンセルしない設計としました。

  ### Rationale / 理由

  SQLite のトランザクション実行中にスレッドを強制終了させたり、非同期的に接続を閉じたりすると、データベースファイルが破損する（Corruption）、あるいはWALファイルが不適切な状態になるリスクがあります。

  キューの処理ロジックにおいて、すでにキューから取り出され実行状態に入ったタスクは「不可分なアトミック操作」と見なします。シャットダウンのタイムアウトは「新たなタスクの取り出し」を停止するためには機能しますが、実行中のI/O処理を途中で引き裂くことはしません。これにより、システムの安全性とデータ一貫性を最優先しています。

  ## 影響・結果

  * **ポジティブ**:
    * SQLite データベースの破損リスクを完全に排除できる。
    * トランザクションの整合性が保証される。
  * **ネガティブ**:
    * 実行中のタスクがI/Oレベルで極端にスタック（OS起因など）した場合、タイムアウト後もプロセスの終了が遅延する可能性がある。
