端末のデータとオフライン

アプリの端末内の DB は、ほとんどが SQLite（ファイル1つで動く小さな DB）です。Android では Room、iOS では SwiftData・Core Data・GRDB などがその上に乗っています。サーバーの DB と違い、利用者の端末ごとにばらばらの版の DB があるのが難しいところです。

user_version とマイグレーション

SQLite には、DB ファイルの中に数字を1つ持てる PRAGMA user_version があります。これを「スキーマの版」として使い、起動時に今の版を見て、足りない分の変更を順番に流します。これがマイグレーションです。Room は @Database(version = N) の版をこの仕組みで管理し、Migration(1, 2) のように1段ずつ書きます。

PRAGMA user_version;            -- 今の版（例：2）
BEGIN;
ALTER TABLE notes ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0;
PRAGMA user_version = 3;
COMMIT;

（SRE）サーバー側のマイグレーション

端末の DB は、画面の表示と裏の同期が同時に読み書きします。SQLite の書き込みの方式を WAL にすると、この同時アクセスが滑らかになります。

SQLite の既定（ロールバックジャーナル）では、書き込み中は読み込みも待たされます。PRAGMA journal_mode=WAL; にすると、変更をまず別のファイル（-wal）に追記するので、書き込み中でも読み込みが止まりません。裏で同期しながら画面で一覧を表示するアプリでは効果が大きく、Room は多くの端末で既定で WAL を使います。

落とし穴は、DB ファイルが .db・-wal・-shm の3つになることです。.db だけをコピーして書き出すと、まだ -wal にある最近の変更が抜けます。書き出す前は DB を閉じるか、チェックポイント（PRAGMA wal_checkpoint）で本体に書き戻します。

端末の DB を直接 SQLite の API で扱うことは少なく、ライブラリを通して使います。違いは、SQL を自分で書くか、オブジェクトとして扱うかです。

どれを使っても、中は SQLite なので、インデックス・トランザクション・WAL の知識はそのまま使えます。選ぶときは、対応する最低の OS の版と、SQL をどれだけ自分で書きたいかで決めます。

端末の DB でも、件数が数万を超えると、問い合わせの書き方で速さが大きく変わります。基本はサーバーの DB と同じです。

EXPLAIN QUERY PLAN
SELECT * FROM notes WHERE folder_id = 3 ORDER BY updated_at DESC;
-- SCAN notes なら全件読み。SEARCH notes USING INDEX ... ならインデックスを使っている

インデックスを増やすと書き込みが遅くなり、DB のファイルも大きくなるので、実際に遅い問い合わせに合わせて足します。

（SRE）インデックスの仕組み（B-Tree）

オフラインファーストは、画面は常に端末の DB を読んで表示し、サーバーとは裏で同期する設計です。電波がなくても見られて、編集もでき、つながったら送ります。表示が速くなる利点もあります。難しいのは、端末とサーバー（や別の端末）で同じデータが別々に変わったときの衝突です。

（SRE）冪等性の実装方法

この章では、衝突の扱い・送信待ちのキュー・差分の同期をそれぞれ次のトピックで説明します。

オフラインで編集できるようにすると、同じデータが端末とサーバー（や別の端末）で別々に変わる衝突が必ず起きます。データの種類ごとに、どう見つけてどう解決するかを決めておきます。

衝突したときは、サーバーの最新を取り直して「自動でまとめる」「利用者に選んでもらう」「別の版として両方残す」のどれかにします。削除は行を消さずに「削除済み」の印（墓標）を付けて同期しないと、別の端末から復活してしまいます。

オフラインでの変更は、すぐ送れないので「送るべきもの」を DB に記録しておきます。これが送信待ちのキュー（outbox）です。

オフラインでの変更は、DB の更新と同じトランザクションで「送信待ち」の表に1行追加します。つながったら古い順に送り、成功したら消します。

• 各操作に一意の ID（冪等キー）を付ける。送った後に応答が届かず再送しても、サーバーは二重に処理しない。
• 同じ行への変更は順番を守って送る。
• 送る処理は、Android は WorkManager（ネットワークがあるときの条件付き）、iOS はアプリを開いたときと BGTaskScheduler で動かす。
• 何度送っても失敗する操作（400 など）は止めて、利用者に知らせる。キューの先頭で詰まり続けないようにする。

画面には「未送信」の印を出すと、利用者が安心できます。

サーバーからの変更を取るたびに全件を取り直すと、件数が増えるにつれて通信量も時間も増えます。そこで前回どこまで取ったかを覚えておき、その後に変わった分だけを受け取ります。

削除は「行がない」ことでは伝わらないので、サーバーは削除の印（墓標）を一定期間残して差分に含めます。墓標を消した後に古いトークンで来た端末には、フル同期をさせます。

画像や API の結果を端末に取っておくと、表示が速くなり通信量も減ります。ただし端末の容量とメモリは限られているので、上限と消し方を決めておきます。

画像の読み込みは、Android なら Coil や Glide、iOS なら Kingfisher や SDWebImage のようなライブラリが、2段のキャッシュと表示の大きさへの縮小をまとめて引き受けてくれます。自作するより、こうしたライブラリの設定（上限・縮小）を確かめるほうが確実です。

端末に保存するものは、中身の大事さで保存先を分けます。普通の設定ファイルは、端末のバックアップや、改造した端末（脱獄・root）から読まれることがあるので、秘密の値は入れません。

保存先の使い分け

iOS の Keychain は、いつ読めるかを指定できます（例：kSecAttrAccessibleAfterFirstUnlockThisDeviceOnly は再起動後に一度ロックを解除すれば読め、別の端末へのバックアップの移行には含まれません）。また、アプリを消しても Keychain の項目が残る場合があるので、入れ直したときの扱いを決めておきます。

Android の Keystore は、鍵を端末の安全な領域に置き、鍵そのものを取り出せないようにする仕組みです。データはその鍵で暗号化してから保存します。以前よく使われた Jetpack Security（security-crypto）の EncryptedSharedPreferences は、2025年の 1.1.0 ですべての API が非推奨になり、Keystore を直接使うよう案内されているので、新しく作るなら Keystore の鍵で自分で暗号化する形を選びます。自動バックアップ（dataExtractionRules）からトークンのファイルを外す設定も忘れずに。

端末の暗号化

今の iPhone と Android 端末は、保存領域全体が暗号化されています。ただしこれは「端末を盗まれて分解されたとき」の守りで、ロックを解除した後はアプリから普通に読めます。iOS ではファイルごとに保護の強さを選べ（Data Protection）、既定は「再起動後に一度ロックを解除するまで読めない」です。特に大事なファイルは .complete（ロック中は読めない）にできますが、ロック中に裏で読めなくなるので、裏で使うファイルには向きません。