transaction-correctness

トランザクションの正確性ガイド

Turso は WAL（先行書き込みログ）モードのみを使用します。

ファイル：.db、.db-wal（.db-shm はありません。Turso はインメモリの WAL インデックスを使用します）

WAL の仕組み

書き込みパス

1. 書き込み側は WAL ファイルにフレーム（ページデータ）を追記します（シーケンシャル I/O）。
2. COMMIT は、ヘッダーの db_size がゼロ以外のフレームです（トランザクションの終了を示します）。
3. チェックポイントが実行されるまで、元の DB は変更されません。

読み取りパス

1. 読み取り側は読み取りマークを取得します（mxFrame = 最後の有効なコミットフレーム）。
2. 各ページについて、mxFrame までの WAL を確認し、見つからない場合はメイン DB にフォールバックします。
3. 読み取り側には、読み取りマーク時点で一貫性のあるスナップショットが表示されます。

チェックポイント処理

WAL の内容をメイン DB に転送します。

WAL grows → checkpoint triggered (default: 1000 pages) → pages copied to DB → WAL reused

チェックポイントの種類：

• PASSIVE：ノンブロッキングです。アクティブな読み取り側が必要とするページの処理を停止します。
• FULL：読み取り側を待ち、すべてのページをチェックポイント処理します。
• RESTART：FULL と同様に処理し、WAL を先頭にリセットします。
• TRUNCATE：RESTART と同様に処理し、WAL ファイルをゼロ長に切り詰めます。

WAL インデックス

SQLite は WAL インデックスに共有メモリファイル（-shm）を使用します。Turso は使用しません。マルチプロセスアクセスがサポートされていないため、インメモリのデータ構造（frame_cache ハッシュマップ、アトミックな読み取りマーク）を使用します。

並行性のルール

• 書き込み側は常に 1 つです。
• 読み取り側は書き込み側をブロックせず、書き込み側も読み取り側をブロックしません。
• チェックポイント処理は、アクティブな読み取り側が必要とするページで停止する必要があります。

復旧

クラッシュ時：

1. 最初の接続が排他ロックを取得します。
2. WAL から有効なコミットを再生します。
3. ロックを解放し、通常の操作を再開します。

Turso の実装

主要なファイル：

• WAL の実装 - WAL の実装
• ページ管理、トランザクション

接続ごとのデータと共有データ

接続ごと（プライベート）：

• Pager - ページキャッシュ、ダーティページ、セーブポイント、コミット状態
• WalFile - 接続のスナップショットビュー：
  • max_frame / min_frame - この接続のスナップショットのフレーム範囲
  • max_frame_read_lock_index - この接続が保持する読み取りロックスロット
  • last_checksum - ローリングチェックサムの状態

接続間で共有：

• WalFileShared - WAL のグローバル状態：
  • frame_cache - ページからフレームへのインデックス（.shm ファイルを置き換えます）
  • max_frame / nbackfills - WAL のグローバルな進行状況
  • read_locks[5] - 読み取りマークスロット（フレーム値を内包した TursoRwLock）
  • write_lock - 排他書き込みロック
  • checkpoint_lock - チェックポイント処理の直列化
  • file - WAL ファイルハンドル
• DatabaseStorage - メインの .db ファイル
• BufferPool - 共有メモリ割り当て

正確性の不変条件

1. 耐久性：成功を返す前に、COMMIT レコードを fsync する必要があります。
2. 原子性：部分的なトランザクションが読み取り側に見えることはありません。
3. 分離性：各読み取り側には、一貫性のあるスナップショットが表示されます。
4. 更新の消失防止：チェックポイント処理によって未コミットの変更が上書きされることはありません。

参考資料

• SQLite WAL
• WAL ファイル形式