@capacitor-community/sqlite 대안 2026

__CAPGO_KEEP_0__의 주요 대체 옵션은 @capacitor-community/sqlite : Capacitor 8의 native SQLite 플러그인으로, SQLCipher는 선택 사항이며 쿼리 데이터는 Capacitor 브리지 대신 로컬 HTTP 채널을 통해 전송됩니다. 이 가이드는 두 가지를 공정하게 비교하고, __CAPGO_KEEP_1__을 유지할 때와 사용자 데이터베이스를 마이그레이션하는 방법을 안내합니다. @capgo/capacitor-fast-sql: a native SQLite plugin for iOS, Android and the web that keeps SQLCipher optional and sends query data over a local HTTP channel instead of the Capacitor bridge. This guide compares the two honestly, says when to stay on the community plugin, and walks through migrating both your code and your users’ existing databases.

팀들은 왜 대안을 찾고 있나요?

@capacitor-community/sqlite has been the default SQLite plugin for Capacitor for years and it is still maintained (8.1.1 shipped in August 2026). The reasons people move are specific:

1. Bridge 직렬화. 모든 결과는 JSON 형식으로 Capacitor 브리지를 통해 전달됩니다. 이는 작은 쿼리에는 문제가 없지만, sync 또는 search를 위해 수천 개의 행을 로드할 때는 유의미합니다.
2. SQLCipher는 항상 포함됩니다. 플러그인은 iOS 및 Android에서 SQLCipher에 의존하기 때문에, 암호화를 사용하지 않더라도 native 크기가 증가하고, 이에 대한 암호화 code을 수출 규제 답변에 고려해야 합니다.
3. 웹 스토리지 모델. 웹에서 사용하는 __CAPGO_KEEP_0__은 sql.js입니다. 메모리에 저장되고, IndexedDB에 저장할 때 호출됩니다. jeep-sqlite __CAPGO_KEEP_0__이 큰 표면. saveToStore()연결 wrapper, 일관성 검사, 읽기 전용 및 비준수 연결, sync 테이블, JSON import 및 export. 강력하지만, 'SQL 실행'에 대해 많은 것을 배워야 합니다.
4. API __CAPGO_KEEP_0__
5. 한 앱당 암호 한 개. 암호화는 플러그인에 저장된 단일 비밀을 사용하며, 앱 내의 모든 암호화된 데이터베이스가 공유합니다.setEncryptionSecret비교

플랫폼

커뮤니티 플러그인에 머물 때

실용성을 고려해라. 머물 수 있는 경우:

• 전자 제품을 전자 빌드,
• 사용합니다 TypeORM (capacitor 드라이버는 커뮤니티 플러그인에 대해 작성되었습니다. TypeORM과 Capacitor),
• TypeORM JSON import/export 또는 sync 테이블에 의존하고 그것들을 다시 빌드하지 않으려면
• 현재 앱이 잘 작동하는 경우에

작은 쿼리만 사용할 때

이동 하시겠습니까?

• 이동하세요:
• 대량 데이터를 로드하거나 쓰거나 (sync 엔진, 오프라인 카탈로그, 검색 인덱스, CRDT 로그),
• SQLCipher을 필요하지 않는 앱에 넣고 싶지 않다면
• 웹에서 실제 SQLite 파일을 OPFS를 통해 사용하고 싶다면 메모리 복사본 대신
• API 앱에서 간단한 연결, 쿼리, 실행, 트랜잭션을 원한다면

Fast SQL에 대한 전체_walkthrough을 보려면 Capacitor 앱에서 SQLite 사용 방법.

Step 1: Fast SQL을旧 플러그인과 함께 설치

커뮤니티 플러그인을 설치한 릴리스를 유지하여 기존 데이터를 마이그레이션할 수 있습니다.

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

기존 데이터를 마이그레이션할 수 있도록 커뮤니티 플러그인을 한 릴리즈 동안 유지하세요.

• iOS: NSAppTransportSecurity iOS NSAllowsLocalNetworking = true > Info.plist.
• in : network_security_config.xml 이것은 localhost 그리고 127.0.0.1,
• 암호화 : net.zetetic:sqlcipher-android 안드로이드 앱 모듈과 CapgoCapacitorFastSql/SQLCipher iOS의 encrypting SQLite in Capacitor.
• Web : Cross-Origin-Opener-Policy: same-origin 그리고 Cross-Origin-Embedder-Policy: require-corp OPFS의

2단계: API을 매핑하세요

__CAPGO_KEEP_0__

Before:

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();

After:

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

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

FastSQL.connect() __CAPGO_KEEP_3__ isConnection / retrieveConnection dance.

메소드 매핑

or

이전:

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;

이후:

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

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

두 플러그인은 열거된 열 이름으로 열거된 행을 반환합니다.

멀티-Statement Execute

커뮤니티 execute() 여러 statement 들이 쉼표로 구분된 문자열을 받습니다. ;분리하지 마십시오.

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 })));

문재적인 분리 ; trigger body 또는 세미콜론이 포함된 문자열 리터럴이 포함된 statement이 있는 경우 split(';') 업그레이드 statement을 사용자 버전으로 업그레이드하십시오.

커뮤니티 플러그인은 schema 버전을

사용자 버전으로 저장합니다. 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 iOS에서 Documents 앱의 files 디렉토리에서 Android에서 Directory.Data iOS에서 @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단계: 기존 사용자 데이터를 이전하십시오

업데이트한 사용자들이 사용하는 앱에는 커뮤니티 플러그인이 만든 데이터베이스가 있습니다. 그것은 다른 경로와 이름을 가지고 있습니다:

Option 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 Filesystem 플러그인은 샌드박스 내의 임의 경로에서 읽을 수 있도록 합니다.
• 연결을 닫고 체크포인트를 먼저 하여 최근에 작성된 쓰기 내용이 파일에 남아 있지 않도록 합니다. -wal 파일입니다.
• 새로운 릴리즈까지 파일을 유지하고 나중에 커뮤니티 연결의 메서드를 사용하여 자신감이 생긴 후 삭제하세요. 그런 다음 커뮤니티 플러그인을 제거하세요. delete() B: 자바스크립트에서 행을 복사 (암호화된 데이터베이스 또는 스키마 변경)

Option B: 자바스크립트에서 행 복사 (암호화된 데이터베이스, 또는 스키마 변경)

사용

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 and createConnection 만약 원본이 암호화되지 않았다면. 커뮤니티 플러그인은 iosIsEncryption / androidIsEncryption and capacitor.config Live Update WHERE rowid > ? ORDER BY rowid LIMIT 5000.

Cloudflare

Capacitor

GitHub

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

Capgo sql-wasm.wasm code jeep-sqlite API main.tsSDK

데이터 마이그레이션 code은 자바스크립트이므로 배포할 수 있습니다. Capgo 실시간 업데이트bun Capgo 빌드 cloud에서 만들 수 있습니다. Mac을 항상 가지고 있지 않다면 (App Store 업로드는 2026년 4월 이후 Xcode 26 이상이 필요합니다).

문제 해결

iOS에서 쿼리가 모두 실패합니다. NSAllowsLocalNetworking 앱의 Info.plist또는 앱이 다시 빌드되지 않았습니다.

Android: CLEARTEXT communication to localhost not permitted. localhost를 네트워크 보안 구성에 추가하세요. SSL 핀닝을 위해 이미 하나가 있으면 합쳐주세요. domain-config 만들어진 스키마의 일부만입니다.

여러 statement를 포함한 문자열을 전달했습니다. 배열로 분리하세요. execute()Android에서 아무것도 반환하지 않습니다.

INSERT ... RETURNING Troubleshooting Fast SQL 8.2 에서 Android는 다음 조건을 충족하는 statement만 결과를 반환합니다. SELECT, PRAGMA or EXPLAIN. Use insertId . 사용 run().

from Pass 1/0 Pass true/false 대신 query parameters에서

in Android는 read-query parameters를 text로 바인딩합니다. iosDatabaseLocationThe copied database is empty. getUrl().

community plugin은 사용자 지정 커뮤니티 플러그인은 IndexedDB를 통해 웹 데이터를 저장했습니다. jeep-sqlite, Fast SQL은 OPFS를 사용합니다. 백엔드에서 웹 클라이언트를 다시同步하거나, 이전 플러그인의 exportToJson 와 Fast SQL로 행을导入합니다.

다른 옵션

• @capgo/capacitor-data-storage-sqlite 실제로 문자열 키-값 저장소가 필요하다면 SQLite에 의해 백업됩니다. __CAPGO_KEEP_0__ Capacitor 키-값 저장소.
• Kysely: Kysely Drizzle Drizzle Fast SQL의 전체 __CAPGO_KEEP_0__은

Fast SQL API는 전체적으로 플러그인 문서 그리고 플러그인 페이지 플러그인 페이지.