sqlite-to-fast-sql

SQLite から Fast SQL への移行

ブリッジベースの SQL プラグインを @capgo/capacitor-fast-sql に置き換え、ユーザーデータを失わないようにします。

使用するタイミング

次の場合に実行します：

• package.json に @capacitor-community/sqlite、cordova-sqlite-storage、@capawesome-team/capacitor-sqlite、ORM の Capacitor ドライバー、またはその他の SQLite プラグインがあり、ユーザーが Fast SQL を希望している。
• すべての行が JSON として Capacitor ブリッジを経由するため、大規模な SELECT や同期書き込みが遅い。
• アプリで暗号化、トランザクション、バッチ書き込み、BLOB、または暗号化されたキー値ストアが必要である。

次の場合は使用しないでください：

• @capacitor/preferences または IndexedDB のみを使用するアプリ → capacitor-offline-first。
• @ionic-enterprise/secure-storage / Identity Vault → ionic-enterprise-sdk-migration。
• Fast SQL をすでに使用しており、スキーマ設計または同期ロジックが必要なアプリ → capacitor-offline-first。

ライブプロジェクトのスナップショット

検出された SQL 関連パッケージ： !node -e "const fs=require('fs');if(!fs.existsSync('package.json'))process.exit(0);const pkg=JSON.parse(fs.readFileSync('package.json','utf8'));const needles=['sqlite','sqlcipher','typeorm','watermelondb','pouchdb','@capacitor-community/sqlite','@capawesome-team/capacitor-sqlite','@capgo/capacitor-fast-sql'];const out=[];for(const section of ['dependencies','devDependencies']){for(const [name,version] of Object.entries(pkg[section]||{})){if(needles.some((needle)=>name.includes(needle)))out.push(section+'.'+name+'='+version)}}console.log(out.sort().join('\n'))"

Fast SQL の違い

• ネイティブ SQLite には Capacitor ブリッジではなく、localhost 上のトークン保護された HTTP サーバーを介してアクセスするため、大きな結果セットやバッチでブリッジのシリアライズを回避できます。そのため、iOS ATS と Android のクリアテキスト設定が必要です。
• プラグインのメジャーバージョンは Capacitor のメジャーバージョンに準じます（Capacitor 8 では v8）。現在：8.2.x。
• データベースファイル：iOS は Documents/<database>.db、Android は <filesDir>/<database>.db です。他のプラグインではパスや名前が異なるため、既存のデータは自動的に引き継がれません。
• Web：永続化に OPFS を使用する公式の @sqlite.org/sqlite-wasm（依存関係にバンドル済みで、sql.js のインストールは不要です）。旧バージョンでは sql.js と IndexedDB を使用していましたが、そのデータは自動的に移行されません。
• 暗号化：SQLCipher。プラットフォームごとにオプトインします。

手順

ステップ 1：現状を確認する

package.json を読み込み、データレイヤーを grep します。以下を記録します：プラグインとバージョン、データベース名、スキーマ／マイグレーションの仕組み（user_version、アップグレード文、ORM マイグレーション）、トランザクションの使用状況、BLOB、暗号化（およびキーの取得元）、JSON のインポート／エクスポート、Web サポート、概算データサイズ。コードを変更する前に、これらを報告します。

ステップ 2：API を対応付ける

import { FastSQL, KeyValueStore } from '@capgo/capacitor-fast-sql';

const db = await FastSQL.connect({ database: 'app' });            // { encrypted, encryptionKey, readOnly }
const rows = await db.query('SELECT * FROM todo WHERE done = ?', [0]);
const { rowsAffected, insertId } = await db.run('INSERT INTO todo (title) VALUES (?)', ['A']);
await db.execute('CREATE TABLE IF NOT EXISTS todo (id INTEGER PRIMARY KEY, title TEXT, done INTEGER DEFAULT 0)');
await db.executeBatch([{ statement: 'INSERT INTO log (m) VALUES (?)', params: ['x'] }]);
await db.transaction(async (tx) => { await tx.run('UPDATE a SET n = n - 1'); await tx.run('UPDATE b SET n = n + 1'); });
await FastSQL.disconnect('app');

@capacitor-community/sqlite	Fast SQL
new SQLiteConnection(CapacitorSQLite)、createConnection(name, encrypted, mode, version, readonly)、db.open()	FastSQL.connect({ database, encrypted, encryptionKey, readOnly })
db.query(sql, values) → { values }	db.query(sql, params) → 行の配列
db.run(sql, values) → { changes: { changes, lastId } }	db.run(sql, params) → { rowsAffected, insertId }
db.execute(multiStatementSql)	ステートメントごとの db.execute(sql)、または executeBatch
db.executeSet([{ statement, values }])	db.executeBatch([{ statement, params }])
beginTransaction/commitTransaction/rollbackTransaction、呼び出し時の transaction フラグ	db.transaction(cb) または beginTransaction() / commit() / rollback()
addUpgradeStatement + バージョン	独自の PRAGMA user_version マイグレーションランナーを維持する
closeConnection(name)	FastSQL.disconnect(name)
importFromJson / exportToJson	提供なし。executeBatch で行を書き込む
cordova-sqlite-storage の db.executeSql(sql, params, ok, err) / db.transaction(tx => tx.executeSql(...))	db.query/db.run および db.transaction(async tx => ...)

キー値データ（Ionic Storage、Preferences のようなラッパー）→ set/get/has/remove/clear/keys を備えた KeyValueStore.open({ database, encrypted, encryptionKey, store })。

ステップ 3：インストールと設定

npm install @capgo/capacitor-fast-sql
npx cap sync

iOS ios/App/App/Info.plist（ループバックのみ。他のホストに対する ATS は弱めません）：

<key>NSAppTransportSecurity</key>
<dict>
    <key>NSAllowsLocalNetworking</key>
    <true/>
</dict>

Android android/app/src/main/res/xml/network_security_config.xml。<application> の android:networkSecurityConfig="@xml/network_security_config" で参照します：

<?xml version="1.0" encoding="utf-8"?>
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="false">localhost</domain>
        <domain includeSubdomains="false">127.0.0.1</domain>
    </domain-config>
</network-security-config>

アプリにすでにネットワークセキュリティ設定がある場合は、ファイルを置き換えずに domain-config を統合してください。

暗号化（encrypted: true の場合のみ）：

• Android：android/app/build.gradle の dependencies に implementation 'net.zetetic:sqlcipher-android:4.13.0'（または現行バージョン）を追加します。
• iOS（CocoaPods）：ios/App/Podfile に pod 'CapgoCapacitorFastSql/SQLCipher', :path => '../../node_modules/@capgo/capacitor-fast-sql' を追加し、pod install を実行します。SPM プロジェクトの場合は、現行の SQLCipher オプションについてプラグインの README を確認してください。
• キーを JS ソースに保存しないでください。@capgo/capacitor-native-biometric を使って保存するか、バックエンドから取得してください。

Web（アプリを Web でも公開する場合のみ）：Cross-Origin-Opener-Policy: same-origin と Cross-Origin-Embedder-Policy: require-corp を配信し、Vite に optimizeDeps.exclude: ['@sqlite.org/sqlite-wasm'] を追加します。最初の connect() より前に CapgoCapacitorFastSql.configureWeb({ ... }) を呼び出すのは任意で、ネイティブでは何もしません。

ステップ 4：既存データを保持する

ユーザーと相談して、次のいずれかを選択します。

1. 2 つのプラグインを使ったリリース（最も安全）：1 回のリリースでは古いプラグインをインストールしたままにします。初回起動時に migrated フラグがなければ、古いプラグインからテーブルを読み取り、トランザクション内で executeBatch を使って Fast SQL に書き込み、件数を確認してフラグを設定します。次のリリースで古いプラグインを削除します。
2. ファイルのコピー：最初の connect() より前に、古い .db ファイルを Fast SQL のパスにコピーします（古い community プラグインのファイル名は通常 <name>SQLite.db です。実際のパスを事前にデバイスで確認してください）。暗号化されたファイルを引き続き使えるのは、同じキーと互換性のある SQLCipher バージョンを使用する場合のみです。
3. サーバーから再同期：ローカルデータがキャッシュの場合に利用できます。ユーザーに確認してください。

ステップ 5：コードを置き換えて古いプラグインを削除する

既存のデータアクセスレイヤーの背後でインポートと呼び出しを置き換え、スキーマとマイグレーション手順は維持します。その後（オプション 1 の場合はデータを引き継ぐリリースの後）：

npm uninstall @capacitor-community/sqlite   # or the plugin in use
npx cap sync

検証

• クリーンアップ後に rg -n "@capacitor-community/sqlite|cordova-sqlite|CapacitorSQLite|SQLiteConnection" -g '!node_modules' src を実行すると、何も返りません。
• アップグレードテスト：現在のストアビルドをインストールしてデータを作成し、その上に新しいビルドをインストールします。行数が一致することを確認します。
• 両プラットフォームでスモークテストを実施します：作成、読み取り、更新、削除、トランザクションのロールバック（transaction 内で例外を発生させ、部分的な書き込みがないことを確認）、BLOB の往復（Uint8Array）。
• 暗号化 DB：間違ったキーで開けないこと、通常の sqlite3 ではファイルを読み取れないことを確認します。
• 大きなクエリの実行時間を変更前後で測定し、パフォーマンス目標を確認します。

エラー処理

エラー／症状	対処方法
iOS：http://localhost:<port> へのリクエストが失敗する。The resource could not be loaded because the App Transport Security policy requires the use of a secure connection	NSAllowsLocalNetworking を追加します
Android：net::ERR_CLEARTEXT_NOT_PERMITTED または CLEARTEXT communication to localhost not permitted by network security policy	localhost 用の network_security_config.xml を追加し、マニフェストから参照します
iOS：Encryption is not available in this build. Add SQLCipher to enable encryption.	SQLCipher の subspec をインストールするか、encrypted: false を指定します
Android：Encryption is not available. ... to your app's build.gradle to enable encryption.	アプリモジュールに net.zetetic:sqlcipher-android を追加します
Encryption key is required when encrypted is true	encrypted: true とともに encryptionKey を渡します
更新後、アプリが空のデータベースで起動する	新しいファイルパスです。ステップ 4 のデータ引き継ぎを実施します
Web：OPFS／SharedArrayBuffer のエラー	COOP／COEP ヘッダーがないか、Vite が sqlite-wasm を事前バンドルしています
query が、コードで { values } を想定している箇所にオブジェクトを返す	古い community プラグインの結果形式です。呼び出し側を更新して行配列を使います