MCPInstall

sqlite-to-fast-sql

by cap-goData & Databases

Migrates SQLite and SQL-style Capacitor storage (@capacitor-community/sqlite, cordova-sqlite-storage, @ionic/storage with a SQLite driver, TypeORM/Drizzle/Kysely capacitor drivers, and other bridge-based SQL plugins) to @capgo/capacitor-fast-sql. Use when replacing createConnection/open/query/run/executeSet calls, slow large result sets over the Capacitor bridge, adding SQLCipher encryption, keeping transactions and BLOBs, moving key-value data to KeyValueStore, preserving existing database files during the switch, or fixing Fast SQL setup errors (ATS NSAllowsLocalNetworking, Android cleartext localhost, "Encryption is not available in this build", web OPFS COOP/COEP headers). Do not use for non-SQL storage such as Preferences (capacitor-offline-first), Ionic Secure Storage or Identity Vault (ionic-enterprise-sdk-migration), generic app upgrades (capacitor-app-upgrades), or code that already wraps Fast SQL.

Installs
710
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/cap-go/capgo-skills --skill sqlite-to-fast-sql
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads sqlite-to-fast-sql automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

SQLite to Fast SQL Migration

Swap a bridge-based SQL plugin for @capgo/capacitor-fast-sql without losing user data.

When to Use

TRIGGER when:

  • package.json has @capacitor-community/sqlite, cordova-sqlite-storage, @capawesome-team/capacitor-sqlite, an ORM capacitor driver, or another SQLite plugin, and the user wants Fast SQL.
  • Large SELECTs or sync writes are slow because every row crosses the Capacitor bridge as JSON.
  • The app needs encryption, transactions, batch writes, BLOBs, or an encrypted key-value store.

Do not use for:

  • @capacitor/preferences or IndexedDB-only apps -> capacitor-offline-first.
  • @ionic-enterprise/secure-storage / Identity Vault -> ionic-enterprise-sdk-migration.
  • Apps already on Fast SQL needing schema design or sync logic -> capacitor-offline-first.

Live Project Snapshot

Detected SQL-related packages: !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'))"

How Fast SQL Differs

  • Native SQLite is reached through a token-protected HTTP server on localhost, not the Capacitor bridge, so big result sets and batches avoid bridge serialization. This is why iOS ATS and Android cleartext config are required.
  • Plugin major follows Capacitor major (v8 for Capacitor 8). Current: 8.2.x.
  • Database files: iOS Documents/<database>.db, Android <filesDir>/<database>.db. Other plugins use different paths and names, so existing data is not picked up automatically.
  • Web: official @sqlite.org/sqlite-wasm with OPFS persistence (bundled dependency, no sql.js install). Older versions used sql.js + IndexedDB; that data is not migrated automatically.
  • Encryption: SQLCipher, opt-in per platform.

Procedure

Step 1: Inventory

Read package.json and grep the data layer. Record: plugin and version, database names, schema/migration mechanism (user_version, upgrade statements, ORM migrations), use of transactions, BLOBs, encryption (and where the key comes from), JSON import/export, web support, and approximate data size. Report this before changing code.

Step 2: Map the 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/sqliteFast 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) -> rows array
db.run(sql, values) -> { changes: { changes, lastId } }db.run(sql, params) -> { rowsAffected, insertId }
db.execute(multiStatementSql)db.execute(sql) per statement, or executeBatch
db.executeSet([{ statement, values }])db.executeBatch([{ statement, params }])
beginTransaction/commitTransaction/rollbackTransaction, transaction flag on callsdb.transaction(cb) or beginTransaction() / commit() / rollback()
addUpgradeStatement + versionKeep your own PRAGMA user_version migration runner
closeConnection(name)FastSQL.disconnect(name)
importFromJson / exportToJsonNot provided; write rows with executeBatch
cordova-sqlite-storage db.executeSql(sql, params, ok, err) / db.transaction(tx => tx.executeSql(...))db.query/db.run and db.transaction(async tx => ...)

Key-value data (Ionic Storage, Preferences-like wrappers) -> KeyValueStore.open({ database, encrypted, encryptionKey, store }) with set/get/has/remove/clear/keys.

Step 3: Install and configure

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

iOS ios/App/App/Info.plist (loopback only; does not weaken ATS for other hosts):

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

Android android/app/src/main/res/xml/network_security_config.xml, referenced by android:networkSecurityConfig="@xml/network_security_config" on <application>:

<?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>

If the app already has a network security config, merge the domain-config instead of replacing the file.

Encryption (only if encrypted: true):

  • Android: implementation 'net.zetetic:sqlcipher-android:4.13.0' (or current) in android/app/build.gradle dependencies.
  • iOS (CocoaPods): pod 'CapgoCapacitorFastSql/SQLCipher', :path => '../../node_modules/@capgo/capacitor-fast-sql' in ios/App/Podfile, then pod install. For SPM projects check the plugin README for the current SQLCipher option.
  • Keep the key out of JS source: store it with @capgo/capacitor-native-biometric or fetch it from your backend.

Web (only if the app ships on web): serve Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp, and in Vite add optimizeDeps.exclude: ['@sqlite.org/sqlite-wasm']. CapgoCapacitorFastSql.configureWeb({ ... }) before the first connect() is optional and a no-op on native.

Step 4: Preserve existing data

Pick one with the user:

  1. Dual-plugin release (safest): keep the old plugin installed for one release. On first launch, if a migrated flag is missing, read tables from the old plugin, executeBatch them into Fast SQL inside a transaction, verify counts, set the flag. Remove the old plugin in the next release.
  2. File copy: copy the old .db file to Fast SQL's path before the first connect() (old community plugin files are typically named <name>SQLite.db; verify the real path on a device first). Encrypted files keep working only with the same key and a compatible SQLCipher version.
  3. Re-sync from server: acceptable when local data is a cache; confirm with the user.

Step 5: Swap code and remove the old plugin

Replace imports and calls behind the existing data-access layer; keep schema and migration steps. Then (after the carry-over release if option 1):

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

Verification

  • rg -n "@capacitor-community/sqlite|cordova-sqlite|CapacitorSQLite|SQLiteConnection" -g '!node_modules' src returns nothing after cleanup.
  • Upgrade test: install the current store build, create data, install the new build over it; row counts match.
  • Smoke test on both platforms: create, read, update, delete, transaction rollback (throw inside transaction and confirm no partial writes), BLOB round-trip (Uint8Array).
  • Encrypted DB: opening with a wrong key fails; file is unreadable with plain sqlite3.
  • Measure a large query before/after to confirm the performance goal.

Error Handling

Error / symptomFix
iOS: requests to http://localhost:<port> fail, The resource could not be loaded because the App Transport Security policy requires the use of a secure connectionAdd NSAllowsLocalNetworking
Android: net::ERR_CLEARTEXT_NOT_PERMITTED or CLEARTEXT communication to localhost not permitted by network security policyAdd the localhost network_security_config.xml and reference it in the manifest
iOS: Encryption is not available in this build. Add SQLCipher to enable encryption.Install the SQLCipher subspec or use encrypted: false
Android: Encryption is not available. ... to your app's build.gradle to enable encryption.Add net.zetetic:sqlcipher-android to the app module
Encryption key is required when encrypted is truePass encryptionKey with encrypted: true
App starts with an empty database after updateNew file path; run the Step 4 carry-over
Web: OPFS / SharedArrayBuffer errorsMissing COOP/COEP headers or Vite pre-bundling sqlite-wasm
query returns objects where code expected { values }Old community-plugin result shape; update callers to use the rows array

FAQ

What does the sqlite-to-fast-sql skill do?

Migrates SQLite and SQL-style Capacitor storage (@capacitor-community/sqlite, cordova-sqlite-storage, @ionic/storage with a SQLite driver, TypeORM/Drizzle/Kysely capacitor drivers, and other bridge-based SQL plugins) to @capgo/capacitor-fast-sql. Use when replacing createConnection/open/query/run/executeSet calls, slow large result sets over the Capacitor bridge, adding SQLCipher encryption, keeping transactions and BLOBs, moving key-value data to KeyValueStore, preserving existing database files during the switch, or fixing Fast SQL setup errors (ATS NSAllowsLocalNetworking, Android cleartext localhost, "Encryption is not available in this build", web OPFS COOP/COEP headers). Do not use for non-SQL storage such as Preferences (capacitor-offline-first), Ionic Secure Storage or Identity Vault (ionic-enterprise-sdk-migration), generic app upgrades (capacitor-app-upgrades), or code that already wraps Fast SQL.

How do I install sqlite-to-fast-sql?

Run npx skills add https://github.com/cap-go/capgo-skills --skill sqlite-to-fast-sql in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/sqlite-to-fast-sql/ (personal) or .claude/skills/sqlite-to-fast-sql/ (project).

Which AI agents can use sqlite-to-fast-sql?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is sqlite-to-fast-sql safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains sqlite-to-fast-sql?

It is published by cap-go in cap-go/capgo-skills. It has 710 recorded installs.

More from cap-go/capgo-skills

View all →

capacitor-best-practices

cap-go/capgo-skills

Review and set up Capacitor apps against current best practices (Capacitor 8.5 stable, 9 alpha via @next). Use for a Capacitor codebase review, capacitor.config.ts audit, new project setup, aligning @capacitor/core/cli/ios/android and plugin majors, plugin patterns (availability checks, checkPermissions/requestPermissions, error code handling, web fallbacks), or release prep; or on " " plugin is not implemented on ios, Could not find the web assets directory, platform has not been added yet, a dev server.url shipped to production, lost edits in android/app/src/main/assets/public, SPM vs CocoaPods, or AppDelegate/UIScene drift. Do not use for security audits (capacitor-security), performance (capacitor-performance), tests (capacitor-testing), crashes (debugging-capacitor), major upgrades (capacitor-app-upgrades), SPM migration (cocoapods-to-spm), UIScene adoption (capacitor-uiscene-migration), or live updates (capgo-live-updates).

Code Quality & Workflow2.7K installs

ionic-design

cap-go/capgo-skills

Builds and reviews Ionic Framework UI in Capacitor apps (Ionic 9 current, Ionic 8 still common) - page structure (ion-header/ion-content/ion-footer), lists, modern form syntax (label/labelPlacement on ion-input/ion-select), sheet modals, tabs + ion-router-outlet, CSS variable theming, dark palettes (palettes/dark.system.css, .ion-palette-dark), iOS vs MD mode, and Ionic 8 - 9 breaking changes (React Router 6, Vue Router 5, Angular 18-22 zoneless, removed ion-picker-legacy, boolean autocorrect, npx @ionic/migrate). Use when writing Ionic components, theming an Ionic app, fixing platform-mode styling, or upgrading @ionic/react, @ionic/vue, @ionic/angular. Do not use for Konsta UI (konsta-ui), Tailwind setup (tailwind-capacitor), raw safe-area CSS (safe-area-handling), keyboard resize (capacitor-keyboard), or Ionic Appflow/Enterprise migrations (ionic-appflow-migration, ionic-enterprise-sdk-migration).

Frontend & Design1.6K installs

capacitor-plugins

cap-go/capgo-skills

Pick, install, and wire up Capacitor plugins for native features (camera, filesystem, geolocation, biometrics, in-app purchases, social login, SQLite, calendar, contacts, health, BLE, NFC, etc.). Covers official @capacitor/ packages (Capacitor 8.5 stable, 9 alpha on next) plus the 145-package @capgo/ index, native permission keys (Info.plist, AndroidManifest, variables.gradle minSdk), npx cap sync / cap ls verification, and errors like '"Camera" plugin is not implemented on ios', 'unable to find plugin', UNIMPLEMENTED, and OS-PLUG- codes. Use for "which plugin should I use for X", adding a plugin, or a plugin call failing after install. Do not use for push setup (capacitor-push-notifications), splash assets (capacitor-splash-screen), keyboard layout (capacitor-keyboard), deep links (capacitor-deep-linking), OTA updates (capgo-live-updates), upgrading plugin source code (capacitor-plugin-upgrades), or adding SPM to a plugin (capacitor-plugin-spm-support).

Frontend & Design1.6K installs

debugging-capacitor

cap-go/capgo-skills

Diagnoses and fixes runtime bugs in Capacitor iOS/Android apps - white/blank screen on launch, startup crashes, "X" plugin is not implemented on ios/android, net::ERRCLEARTEXTNOTPERMITTED, App Transport Security blocks, CORS on capacitor://localhost, permission denials, live reload not connecting, and Capacitor 8.5+ UIScene regressions (appUrlOpen, universal links, pause/resume silent because AppDelegate callbacks stopped). Covers Safari Web Inspector, chrome://inspect, Xcode/LLDB, Android Studio, npx cap run --url (Capacitor 9) vs -l --host (8), xcrun simctl openurlprivacypush, xcrun devicectl device process launchopenURL, xctrace. Do not use for only reading device logs (ios-android-logs), the UIScene migration itself (capacitor-uiscene-migration), deep-link setup (capacitor-deep-linking), speed (capacitor-performance), crash SDKs (capacitor-native-observability), tests (capacitor-testing), or upgrades/build errors (capacitor-app-upgrades, cocoapods-to-spm).

Code Quality & Workflow1.3K installs

capacitor-testing

cap-go/capgo-skills

Testing guide for Capacitor apps and plugins. Covers web-layer unit and component tests with Vitest and mocked Capacitor plugins (vi.mock('@capacitor/core'), registerPlugin), Playwright for the web build, Appium E2E with NATIVEAPP / WEBVIEW context switching, native plugin unit tests with Swift Testing vs XCTest (what can migrate, CAPPluginCall patterns, xcodebuild test on a simulator) and Android JUnit, plus an agent-driven verification loop on simulators and devices (build, install, launch, screenshot, UI hierarchy, tap, logs) with xcrun simctl, xcrun devicectl, adb, Xcode MCP device tools, and live reload via npx cap run --url (Capacitor 9) or -l --host --port (Capacitor 8). Use when adding tests, mocking plugins, "does it work on device", verifying a UI change on a simulator, migrating XCTest to Swift Testing, or setting up test CI. Do not use for crash log capture (ios-android-logs), WebView debugging sessions (debugging-capacitor), or build pipelines (capacitor

Testing & QA1.3K installs

safe-area-handling

cap-go/capgo-skills

Fixes notch, Dynamic Island, home indicator, display cutout, and system bar overlap in Capacitor apps. Covers viewport-fit=cover + env(safe-area-inset-), the Capacitor 8 SystemBars core plugin (insetsHandling, injected --safe-area-inset- CSS variables for Android WebView < 140, removal of android.adjustMarginsForEdgeToEdge), Android 15/16 enforced edge-to-edge (overlaysWebView and backgroundColor of @capacitor/status-bar no longer work at targetSdk 36), iOS contentInset, and insets that change at runtime on rotation, iPad/foldable resizable windows. Use when headers sit under the status bar, tab bars hide behind the gesture bar, env() returns 0 on Android, or layout broke after upgrading to Capacitor 8 / targetSdk 35+. Do not use for keyboard overlap (capacitor-keyboard), Ionic/Konsta component theming (ionic-design, konsta-ui), Tailwind utility setup (tailwind-capacitor), or iOS multi-window/resizability adoption (capacitor-ios-resizability).

Mobile1.3K installs

Popular data & databases skills

View category →

supabase-postgres-best-practices

supabase/agent-skills

Postgres best practices maintained by Supabase, for Postgres running anywhere. Load this skill BEFORE writing or changing anything that lives in a Postgres database: creating or altering tables and columns (including choosing column types), schema design, migrations and declarative schema files, RLS policies and the tests that verify them, indexes, triggers, database functions, queues and scheduled jobs (pgcron, pgmq), vector/semantic search (pgvector), and restoring dumps (pgrestore) or importing data. Also load it when diagnosing slow queries, high CPU, timeouts, EXPLAIN plans, connection exhaustion, locking, bloat, or rows visible to the wrong user or tenant. This is not just a performance guide — schema, migration, security, and SQL authoring tasks need these rules too, even for a one-column change or a single query.

OfficialData & Databases462.2K installs

prisma-client-api

prisma/skills

Prisma Client API reference covering model queries, filters, operators, and client methods. Use when writing database queries, using CRUD operations, filtering data, or configuring Prisma Client. Triggers on "prisma query", "findMany", "create", "update", "delete", "$transaction".

OfficialData & Databases393.5K installs

prisma-database-setup

prisma/skills

Deprecated compatibility name for prisma-orm-setup. Use only when a user or existing integration explicitly invokes prisma-database-setup; otherwise select prisma-orm-setup.

OfficialData & Databases392.3K installs

prisma-cli

prisma/skills

Prisma ORM 7 CLI reference for existing Prisma 7 applications or explicitly selected Prisma 7 workflows. Covers prisma init, generate, migrate, db, dev, studio, and mcp. For setup, connection repair, or Prisma 8, use prisma-orm-setup; not the Prisma Platform CLI.

OfficialData & Databases390.8K installs

prisma-postgres

prisma/skills

Deprecated compatibility name for prisma-postgres-setup. Use only when a user or existing integration explicitly invokes prisma-postgres; otherwise select prisma-postgres-setup.

OfficialData & Databases384.4K installs

prisma-driver-adapter-implementation

prisma/skills

Required reference for Prisma ORM 7 SQL driver adapter work. Use when implementing or modifying adapters, adding database drivers, or touching SqlDriverAdapter, Transaction, savepoint, result mapping, or DriverAdapterError behavior. Covers current transaction lifecycle, optional savepoint hooks, original database-error preservation, and verification.

OfficialData & Databases378.9K installs