2026年の@capacitor-コミュニティ/SQLiteへの代替

主な代替 @capacitor-community/sqlite Capacitor 8 は @capgo/capacitor-fast-sql:CapacitorコミュニティのSQLite代替の代替として、iOS、Android、Web向けのネイティブSQLiteプラグインがあります。このプラグインは、SQLCipherをオプションとして保持し、Capacitorブリッジではなく、ローカルHTTPチャンネルを介してクエリデータを送信します。このガイドでは、2つの代替を比較し、コミュニティプラグインに留まる場合と、どの時点で移行するかを説明し、codeとユーザーの既存のデータベースを移行する手順を説明します。

チームはなぜ代替を探しているか

@capacitor-community/sqlite CapacitorのデフォルトのSQLiteプラグインとしてCapacitorは数年間維持されてきました(2026年8月に8.1.1がリリースされました)。 人々が移行する理由は特定のものです:

1. Bridgeシリアライズ すべての結果はCapacitorブリッジを通じてJSON形式で送信されます。 小規模なクエリでは問題ありませんが、syncまたはsearchのために数千行をロードすると、問題が発生します。
2. SQLCipherは常に含まれます。 The plugin depends on SQLCipher on iOS and Android even if you never encrypt. That adds native size and means your binary contains encryption code you have to account for in export compliance answers.
3. Webストレージモデル。 ウェブではsql.jsコンポーネントを使用し、メモリ内に保存し、IndexedDBに保存する必要があります。 jeep-sqlite 保存する必要があります。 すべてのデータベースはメモリ内に保存されます。 saveToStore()大きな__CAPGO_KEEP_0__サーフェイス。
4. A large API surface. __CAPGO_KEEP_0__
5. 各アプリごとにパスフレーズ 暗号化はプラグインが保持する単一の秘密鍵を使用し、すべてのアプリの暗号化されたデータベースで共有されます。setEncryptionSecret比較

プラットフォーム

CapacitorコミュニティのSQLite代替

CapacitorコミュニティのSQLite代替

• コミュニティプラグインに残るべき時 実用性を優先する。残るべき時: build,
• あなたが利用 TypeORM TypeORMのcapacitorドライバーはコミュニティプラグインに対して書かれています。詳細は TypeORMとCapacitor),
• TypeORMに依存している JSONのインポート/エクスポートまたは同期テーブル そして、再構築しない
• あなたのクエリは小さく、現在のアプリはうまく動作している

Fast SQLがより適切な選択肢である場合

移動する場合は

• あなたが大量のデータを読み込むか書き込む場合 (同期エンジン、オフラインカタログ、検索インデックス、CRDTログ)
• あなたがキーシェアリングまたはキーストアからキーを取得して、特定のデータベースのみを暗号化したい場合
• SQLCipherを必要としないアプリに含めないでください
• 実際のSQLiteファイルをWeb上でOPFSを使用して取得したい
• CapacitorコミュニティのSQLite代替の場合、簡単なAPI接続、クエリ、実行、トランザクションが必要です。

Fast SQL自体のフルウォークスルーについては How to use SQLite in a Capacitor app.

ステップ1:古いプラグインの横にFast SQLをインストールする

コンテキスト:ページ/エリア:Capgoのページ。役割:UIラベル。見られる場所:about.astroページ。メッセージキー`about_how_step_label` (About How Step Label)。

bun add @capgo/capacitor-fast-sql
bunx cap sync

コミュニティプラグインを1つのリリースでインストールしておくことで既存のデータを移行できる

• iOS: NSAppTransportSecurity iOS NSAllowsLocalNetworking = true in Info.plist.
• Android: a network_security_config.xml が許可する localhost と 127.0.0.1、マニフェストから参照されている
• 暗号化: net.zetetic:sqlcipher-android AndroidアプリモジュールとiOSの CapgoCapacitorFastSql/SQLCipher ポッド内で encrypting SQLite in Capacitor.
• Web: Cross-Origin-Opener-Policy: same-origin と Cross-Origin-Embedder-Policy: require-corp Web

ステップ2：APIをマップする

データベースを開く

前:

import { CapacitorSQLite, SQLiteConnection } from '@capacitor-community/sqlite';

const sqlite = new SQLiteConnection(CapacitorSQLite);
const db = await sqlite.createConnection('app', false, 'no-encryption', 1, false);
await db.open();

後:

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

const db = await FastSQL.connect({ database: 'app', walMode: true, performancePresets: true });

FastSQL.connect() 既存の接続を返します。データベースがすでに開いている場合、ダンスはありません。 isConnection / retrieveConnection メソッドマッピング

コミュニティプラグイン

必要ない、OPFSは書き込みを永続化する

Before:

const res = await db.query('SELECT * FROM notes WHERE pinned = ?', [1]);
const notes = res.values ?? [];

const { changes } = await db.run('INSERT INTO notes (title) VALUES (?)', ['Hello']);
const id = changes?.lastId;

After:

const notes = await db.query('SELECT * FROM notes WHERE pinned = ?', [1]);

const { insertId } = await db.run('INSERT INTO notes (title) VALUES (?)', ['Hello']);

両プラグインは、列名でキー化されたオブジェクトとして行を返します。

Multi-statement execute

コミュニティ execute() 受け入れられるのは、複数のステートメントがセミコロンで区切られた文字列です。 ;Fast SQLは、1回の呼び出しごとに1つのステートメントを準備します。SQLを分割するか、または、より良い方は、ステートメントを配列として保持してください。

const schema = [
  'CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL)',
  'CREATE INDEX IF NOT EXISTS idx_notes_title ON notes (title)',
];

await db.executeBatch(schema.map((statement) => ({ statement })));

セミコロンで区切るのではなく ; 単純な split(';') もしも、トリガー本体またはセミコロンで終わる文字列リテラルを含むステートメントが存在する場合

アップグレードステートメントをユーザーバージョンに

コミュニティプラグインは、スキーマバージョンを PRAGMA user_version バージョン番号が同じの場合、既存のユーザーのデータベースは、ステップ3のファイル移行後にすでに正しいバージョンです。

import type { SQLConnection } from '@capgo/capacitor-fast-sql';

// Same content as your old upgrade statements, index 0 = version 1
const versions: string[][] = [
  ['CREATE TABLE IF NOT EXISTS notes (id INTEGER PRIMARY KEY AUTOINCREMENT, title TEXT NOT NULL)'],
  ['ALTER TABLE notes ADD COLUMN pinned INTEGER NOT NULL DEFAULT 0'],
];

export async function migrate(db: SQLConnection) {
  const [{ user_version }] = await db.query('PRAGMA user_version');
  for (let v = Number(user_version); v < versions.length; v++) {
    await db.transaction(async (tx) => {
      for (const statement of versions[v]) await tx.execute(statement);
      await tx.execute(`PRAGMA user_version = ${v + 1}`);
    });
  }
}

実際の状況を確認してください。 user_version 既存のインストール上で実行してから、この情報に頼るのはやめましょう。ログを古いプラグインから現在のリリースで取得するかもしれません。

事前設定されたデータベース

コミュニティプラグインの copyFromAssets() 初回起動時にバンドルされたデータベースのコピーを実行します。Fast SQLでは、ファイルをプラグインが検索する場所に置いて、接続する前にファイルを置くようにしてください。Fast SQLは <name>.db ファイルを Documents iOSではファイルを files アプリの Directory.Data ファイルを @capacitor/filesystem:

import { Directory, Filesystem } from '@capacitor/filesystem';
import { FastSQL } from '@capgo/capacitor-fast-sql';

async function openCatalog() {
  const exists = await Filesystem.stat({ path: 'catalog.db', directory: Directory.Data })
    .then(() => true)
    .catch(() => false);

  if (!exists) {
    const blob = await (await fetch('/assets/catalog.db')).blob();
    const base64 = await new Promise<string>((resolve) => {
      const reader = new FileReader();
      reader.onloadend = () => resolve((reader.result as string).split(',')[1]);
      reader.readAsDataURL(blob);
    });
    await Filesystem.writeFile({ path: 'catalog.db', data: base64, directory: Directory.Data });
  }
  return FastSQL.connect({ database: 'catalog', readOnly: true });
}

ディレクトリに保存します。両方とも

ステップ3：既存ユーザーデータの移行

アップデートしたユーザーは、コミュニティプラグインによって作成されたデータベースを持っています。別のパスと別の名前で存在します。

オプションA:ファイルをコピー(暗号化されていないデータベース)

最速、すべてを保持:インデックス、トリガー user_version.

import { CapacitorSQLite, SQLiteConnection } from '@capacitor-community/sqlite';
import { Directory, Filesystem } from '@capacitor/filesystem';
import { Preferences } from '@capacitor/preferences';

export async function moveCommunityDatabase(name: string): Promise<void> {
  const done = await Preferences.get({ key: `sqlite-moved:${name}` });
  if (done.value === '1') return;

  const sqlite = new SQLiteConnection(CapacitorSQLite);
  const exists = (await sqlite.isDatabase(name)).result;
  if (exists) {
    const conn = await sqlite.createConnection(name, false, 'no-encryption', 1, false);
    await conn.open();
    await conn.execute('PRAGMA wal_checkpoint(TRUNCATE)', false).catch(() => undefined);
    const { url } = await conn.getUrl();
    await sqlite.closeConnection(name, false);

    if (url) {
      await Filesystem.copy({ from: url, to: `${name}.db`, toDirectory: Directory.Data });
    }
  }
  await Preferences.set({ key: `sqlite-moved:${name}`, value: '1' });
}

最初の呼び出し前に呼び出してください。 FastSQL.connect({ database: name }). 便利なメモ:

• getUrl() (iOSとAndroid)データベースファイルのURLを返します。完全なURLを渡す場合、 file:// URLの指定がなければ directory ファイルシステム プラグインは、サンドボックス内にある任意のパスから読み取ることを許可します。
• 接続を閉じてチェックポイントを実行することで、最近の書き込みがファイル内に残っていないことを確認します。 -wal file.
• オプション B: JavaScript で行うコピー (暗号化されたデータベース、またはスキーマの変更) delete() 方法を実行する前に、コミュニティ プラグインを削除することを確認してください。

使用

そして

import { CapacitorSQLite, SQLiteConnection } from '@capacitor-community/sqlite';
import { FastSQL } from '@capgo/capacitor-fast-sql';
import { Preferences } from '@capacitor/preferences';

export async function copyRows(name: string, target: { encryptionKey?: string }) {
  // Record which destination mode was migrated, so a later call with a different target fails loudly
  const mode = target.encryptionKey ? 'encrypted' : 'plain';
  const done = await Preferences.get({ key: `sqlite-copied:${name}` });
  if (done.value === mode) return;
  if (done.value) throw new Error(`${name} was already copied as ${done.value}, not ${mode}`);

  const sqlite = new SQLiteConnection(CapacitorSQLite);
  const src = await sqlite.createConnection(name, true, 'secret', 1, false);
  await src.open();

  try {
    const dst = await FastSQL.connect({
      database: name,
      encrypted: Boolean(target.encryptionKey),
      encryptionKey: target.encryptionKey,
    });

    const objects = ((await src.query(
      `SELECT type, name, sql FROM sqlite_master
       WHERE sql IS NOT NULL AND name NOT LIKE 'sqlite_%'`,
    )).values ?? []) as { type: string; name: string; sql: string }[];
    const tables = objects.filter((o) => o.type === 'table');
    const others = objects.filter((o) => o.type !== 'table');
    const version = (await src.query('PRAGMA user_version')).values?.[0]?.user_version ?? 0;

    await dst.transaction(async (tx) => {
      for (const t of tables) await tx.execute(t.sql);
      for (const t of tables) {
        const rows = (await src.query(`SELECT * FROM "${t.name}"`)).values ?? [];
        if (!rows.length) continue;
        const cols = Object.keys(rows[0]);
        const statement = `INSERT INTO "${t.name}" (${cols.map((c) => `"${c}"`).join(', ')}) VALUES (${cols.map(() => '?').join(', ')})`;
        await tx.executeBatch(rows.map((r) => ({ statement, params: cols.map((c) => r[c]) })));
      }
      for (const o of others) await tx.execute(o.sql);
      await tx.execute(`PRAGMA user_version = ${Number(version)}`);
    });

    // Only mark the copy as done once the transaction has committed
    await Preferences.set({ key: `sqlite-copied:${name}`, value: mode });
  } finally {
    await sqlite.closeConnection(name, false);
  }
}

Use 'no-encryption' and false in createConnection ソースが暗号化されていない場合、コミュニティ プラグインは iosIsEncryption / androidIsEncryption in capacitor.config 暗号化モードの場合は、すでに使用している場合はそれを利用できます。大量のテーブルがある場合は、ページをスクロールしてください。 WHERE rowid > ? ORDER BY rowid LIMIT 5000.

両方のプラグインはSQLCipher 4のデフォルトを使用しているため、暗号化されたファイルは同じパスフレーズでFast SQLで直接開くことができます。コミュニティプラグインは内部でパスフレーズを管理し、行のコピーはその詳細に依存しないため、行のコピーはその詳細に依存しない。

ステップ 4: 旧のプラグインを削除する

リリース 1 または 2 回後にマイグレーションが実装された後:

bun remove @capacitor-community/sqlite jeep-sqlite
bunx cap sync

削除 sql-wasm.wasm アセットと設定から削除する必要があります。また、プラグインを削除すると、SQLCipherの依存関係も削除されます。Fast SQLの暗号化に参加しない場合は、iOSとAndroidのバイナリサイズが小さくなります。 jeep-sqlite セットアップ main.tsしかし、Fast SQLを追加するリリースはネイティブの変更であり、ストアビルドが必要です。ネイティブビルドを先に配信してください。

code ビルド Capgo ライブアップデート__CAPGO_KEEP_0__ Capgo クラウドで作成できます。Macを持っていない場合は、Xcode 26以上が必要です (App Storeのアップロードは2026年4月以降に必要です)。

トラブルシューティング

iOSでは、すべてのクエリが失敗します。 NSAllowsLocalNetworking アプリの Info.plist、またはアプリを再構築しなかったため

Android: CLEARTEXT communication to localhost not permitted. localhostをネットワークセキュリティ設定に追加してください。既存のSSLピン設定があれば、統合してください。 domain-config 部分的なスキーマのみが作成されました。

スキーマの一部のみが作成されました。 Androidでは、 が何も返さない場合があります。 execute()__CAPGO_KEEP_0__

INSERT ... RETURNING __CAPGO_KEEP_0__ In Fast SQL 8.2、Android は、文が始まる "or" 以外のステートメントに対して、行を返します。 SELECT, PRAGMA or EXPLAIN. Use insertId Pass run().

代わりに Pass 1/0 代わりに true/false コピーしたデータベースは空です。

コミュニティ プラグインは、カスタム 、またはソース名が異なる場合、URL を返します。 iosDatabaseLocation古いプラグインから Web データは失われました。 getUrl().

or コミュニティ プラグインは IndexedDB を通じてウェブ データを保存しました。 jeep-sqliteFast SQL は OPFS を使用します。ウェブ クライアントを再同期するか、古いプラグインのエクスポートとインポートを実行して、行を Fast SQL にインポートしてください。 exportToJson その他のオプション

SQLite をバックアップする文字列 キー値 ストアが必要な場合は、

• @capgo/capacitor-data-storage-sqlite key-value ストレージの詳細は __CAPGO_KEEP_0__ を参照してください。 key-value storage in Capacitor.
• Kysely: Kysely Drizzle Drizzle Fast SQL の完全な __CAPGO_KEEP_0__ は

The full Fast SQL API is in the プラグイン ドキュメント そしてプラグインの ページ.