sqlite-to-fast-sql

---
name: sqlite-to-fast-sql
description: Guides the agent through migrating SQLite and SQL-style Capacitor plugins to @capgo/capacitor-fast-sql. Use when replacing bridge-based SQL plugins, adding encryption, preserving transactions, or moving key-value storage onto Fast SQL. Do not use for non-SQL storage, generic app upgrades, or plugins that already wrap Fast SQL.
allowed-tools:
  - Bash(node -e *)
  - Bash(npm *)
  - Bash(npx cap *)
---

# SQLite to Fast SQL Migration

Migrate bridge-based SQLite or SQL plugins to `@capgo/capacitor-fast-sql`.

## When to Use This Skill

- User wants to replace an existing SQLite or SQL plugin
- User needs better performance for large result sets or sync-style writes
- User wants encrypted local storage, transactions, batch writes, or BLOB support
- User wants a key-value wrapper backed by Fast SQL instead of a legacy storage plugin

## 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'))"`

## Why Fast SQL

Fast SQL is the preferred migration target because it avoids heavy bridge serialization by using a local HTTP transport to native SQLite. That makes it much faster for large result sets and sync-heavy write patterns.

Fast SQL also provides:

- transactions with explicit or callback control
- batch execution for multiple statements
- BLOB support for binary data
- encryption and read-only modes
- `KeyValueStore` for lightweight key-value access on top of SQLite
- web fallback support through SQL.js

## Migration Procedure

### Step 1: Inspect the Current SQL Plugin

Start from the injected package snapshot, then read `package.json` directly if the current SQL plugin set still needs clarification.

Document whether the app uses:

- raw SQL queries
- transactions
- BLOB data
- migrations/schema bootstrap
- key-value wrappers
- encrypted storage

### Step 2: Map the Current API Surface

Map the old plugin calls to Fast SQL equivalents:

- connection setup -> `FastSQL.connect(...)`
- reads -> `db.query(...)`
- single-statement writes -> `db.run(...)`
- multi-statement work -> `db.executeBatch(...)`
- transactional work -> `db.transaction(...)` or explicit `beginTransaction` / `commit` / `rollback`
- key-value storage -> `KeyValueStore.open(...)`

### Step 3: Install Fast SQL

Install the new package with the repository's package manager and sync native projects.

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

If the app ships web support, install `sql.js` for the web fallback when needed.

### Step 4: Update Code

Replace old plugin imports and APIs with Fast SQL.

Prefer `db.executeBatch(...)` for repeated writes, `db.transaction(...)` for atomic changes, and `KeyValueStore` for simple local key-value data.

Preserve the existing schema and migration steps unless the old plugin forced a different format.

### Step 5: Reconfigure Native Platforms

Apply the Fast SQL platform setup required by the app:

- iOS local network access when the plugin needs localhost traffic
- Android cleartext network configuration for localhost traffic
- SQLCipher dependency when encrypted mode is enabled on Android

### Step 6: Remove the Old Plugin

Remove the legacy SQL package from `package.json`, reinstall dependencies, and sync again.

Then run the app's normal database smoke tests or migration verification checks.

## Error Handling

- If encrypted storage is required, keep `encrypted: true` and provide a strong key before shipping.
- If the old plugin exposed transactions, use Fast SQL transaction APIs rather than emulating them with ad hoc queries.
- If the app depends on large result sets, prefer batch queries and avoid bridge-heavy wrappers.
- If the app already has a well-defined schema migration path, keep it and only swap the storage engine.