需要替换桥接式 SQLite/SQL 插件并迁移到…

当需要替换桥接式 SQLite/SQL 插件，并改善大结果集/同步写入性能，或需要加密、事务、批量写入、BLOB、键值存储与 Web fallback 时，按此迁移到 Fast SQL。

适用场景

解决思路

1. 先确认选择 Fast SQL 作为迁移目标：它通过本地 HTTP transport 连接原生 SQLite，避免重桥接序列化，因此更适合大结果集和同步密集型写入；并确认目标版本提供显式/回调事务、批量执行、BLOB、加密和只读模式、`KeyValueStore` 以及通过 SQL.js 的 Web fallback。
2. 先使用注入的 package snapshot；如果当前 SQL 插件集合仍需澄清，直接读取 `package.json`。运行检测命令：`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','@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'))"`，并记录应用是否使用原始 SQL 查询、事务、BLOB 数据、迁移/schema 初始化、键值包装器、加密存储。
3. 映射旧插件调用到 Fast SQL 等价 API：connection setup -> `FastSQL.connect(...)`；reads -> `db.query(...)`；single-statement writes -> `db.run(...)`；multi-statement work -> `db.executeBatch(...)`；transactional work -> `db.transaction(...)` 或显式 `beginTransaction` / `commit` / `rollback`；key-value storage -> `KeyValueStore.open(...)`。
4. 安装 Fast SQL：用仓库的包管理器安装 `@capgo/capacitor-fast-sql`，并同步原生项目：`npm install @capgo/capacitor-fast-sql`；`npx cap sync`。如果应用发布 Web 支持，则在需要时安装 `sql.js` 作为 Web fallback。
5. 更新代码：用 Fast SQL 替换旧插件 imports 和 APIs。对重复写入优先用 `db.executeBatch(...)`；对原子变更用 `db.transaction(...)`；对简单本地键值数据用 `KeyValueStore`。除非旧插件强制了不同格式，否则保留现有 schema 和迁移步骤。
6. 重新配置原生平台：iOS 在插件需要 localhost 流量时配置本地网络访问；Android 为 localhost 流量配置 cleartext network；Android 启用加密模式时加入 SQLCipher 依赖。
7. 移除旧插件：从 `package.json` 删除旧 SQL 包，重新安装依赖，并再次同步。然后运行应用正常的数据库 smoke tests 或迁移验证检查。
8. 如果要求加密存储，保留 `encrypted: true`，并在发布前提供强密钥。
9. 如果旧插件暴露事务，使用 Fast SQL 事务 API，而不是用临时查询模拟事务。
10. 如果应用依赖大结果集，优先批量查询，避免桥接层很重的包装器。
11. 如果应用已有定义良好的 schema 迁移路径，保留它，只替换存储引擎。

适用边界 · 注意事项

• 不要用于非 SQL 存储。
• 不要用于通用应用升级。
• 不要用于已经包装 Fast SQL 的插件。