SuperAPI AI 工具集
合作ENAI 行业资讯收藏
Skill 广场sqlite-to-fast-sql

sqlite-to-fast-sql

数据与分析

查看项目

更新于 10-15 00:22

技能介绍

用途

sqlite-to-fast-sql 用于把基于 Capacitor 桥接的 SQLite 存储方案迁移到 @capgo/capacitor-fast-sql，目标是在不丢失用户数据的前提下完成替换。

适用触发条件：package.json 中存在 @capacitor-community/sqlite、cordova-sqlite-storage、@capawesome-team/capacitor-sqlite、某个 ORM 的 Capacitor 驱动或其他 SQLite 插件，且用户希望改用 Fast SQL；大型 SELECT 或同步写入因每行数据都经 Capacitor 桥接以 JSON 传输而变慢；应用需要加密、事务、批量写入、BLOB 或加密键值存储。

不适用：仅使用 @capacitor/preferences 或 IndexedDB 的应用应改用 capacitor-offline-first；@ionic-enterprise/secure-storage 或 Identity Vault 应改用 ionic-enterprise-sdk-migration；已在 Fast SQL 上、需要 schema 设计或同步逻辑的应用应改用 capacitor-offline-first。

主要能力

Fast SQL 通过本地受令牌保护的 HTTP 服务器访问原生 SQLite，而不是 Capacitor 桥接，因此大结果集和批量操作可避免桥接序列化。插件主版本跟随 Capacitor 主版本（Capacitor 8 对应 v8），当前为 8.2.x。数据库文件位置：iOS 为 Documents/<database>.db，Android 为 <filesDir>/<database>.db；其他插件使用不同路径和名称，因此现有数据不会自动被识别。Web 端使用官方 @sqlite.org/sqlite-wasm 与 OPFS 持久化（作为捆绑依赖，无需安装 sql.js）；旧版本使用 sql.js + IndexedDB，该数据不会自动迁移。加密使用 SQLCipher，按平台选择性启用。

使用方式

技能按以下步骤执行：

  1. 清点：读取 package.json 并检索数据层，记录插件与版本、数据库名称、schema/迁移机制（user_version、升级语句、ORM 迁移）、事务、BLOB、加密（及密钥来源）、JSON 导入导出、Web 支持、大致数据量，并在改代码前报告。

  2. 映射 API：例如 FastSQL.connect({ database: 'app' }) 对应旧插件的连接创建；db.query(sql, params) 返回行数组；db.run(sql, params) 返回 { rowsAffected, insertId }；db.execute 执行单条语句，executeBatch 执行批量；db.transaction(cb) 或 beginTransaction()/commit()/rollback() 处理事务；FastSQL.disconnect(name) 关闭连接。旧插件的 addUpgradeStatement + version 需改为自行维护 PRAGMA user_version 迁移运行器；importFromJson/exportToJson 不再提供，需用 executeBatch 写入行。键值数据（Ionic Storage、类似 Preferences 的封装）改用 KeyValueStore.open({ database, encrypted, encryptionKey, store })，提供 set/get/has/remove/clear/keys。

  3. 安装与配置：npm install @capgo/capacitor-fast-sql 后执行 npx cap sync。iOS 需在 ios/App/App/Info.plist 添加 NSAppTransportSecurity 下的 NSAllowsLocalNetworking（仅回环，不削弱其他主机的 ATS）。Android 需在 android/app/src/main/res/xml/network_security_config.xml 中允许 localhost 与 127.0.0.1 明文，并在 <application> 上通过 android:networkSecurityConfig 引用；若已有配置则合并 domain-config 而非替换文件。加密（仅当 encrypted: true）时，Android 在 android/app/build.gradle 添加 net.zetetic:sqlcipher-android:4.13.0（或当前版本）；iOS 在 ios/App/Podfile 添加 pod 'CapgoCapacitorFastSql/SQLCipher' 后执行 pod install，SPM 项目需查看插件 README 的当前 SQLCipher 选项。密钥不应放在 JS 源码中，可用 @capgo/capacitor-native-biometric 存储或从后端获取。Web 端需提供 Cross-Origin-Opener-Policy: same-origin 与 Cross-Origin-Embedder-Policy: require-corp，并在 Vite 中设置 optimizeDeps.exclude: ['@sqlite.org/sqlite-wasm']；首次 connect() 前可选调用 CapgoCapacitorFastSql.configureWeb({ ... })，在原生端为空操作。

  4. 保留现有数据：与用户选择一种方案。双插件发布（最安全）：保留旧插件一个版本，首次启动时若缺少迁移标志，则从旧插件读取表，在事务中 executeBatch 写入 Fast SQL，校验行数后设置标志，下一版本移除旧插件。文件复制：在首次 connect() 前把旧 .db 文件复制到 Fast SQL 路径（旧社区插件文件通常名为 <name>SQLite.db，需先在设备上确认真实路径）；加密文件仅在相同密钥和兼容 SQLCipher 版本下可用。从服务器重新同步：适用于本地数据仅为缓存的情况，需与用户确认。

  5. 替换代码并移除旧插件：在现有数据访问层后替换导入与调用，保留 schema 与迁移步骤；若采用方案 1，在过渡版本之后执行 npm uninstall @capacitor-community/sqlite（或实际使用的插件）与 npx cap sync。

验证

清理后 rg -n "@capacitor-community/sqlite|cordova-sqlite|CapacitorSQLite|SQLiteConnection" -g '!node_modules' src 应无结果。升级测试：安装当前商店版本并创建数据，再覆盖安装新版本，行数应一致。双平台冒烟测试：增删改查、事务回滚（在事务内抛错并确认无部分写入）、BLOB 往返（Uint8Array）。加密数据库：错误密钥打开应失败，文件用普通 sqlite3 应不可读。测量大查询前后耗时以确认性能目标。

错误处理

常见问题与修复：iOS 请求 http://localhost:<port> 失败并提示 ATS 需要安全连接时，添加 NSAllowsLocalNetworking；Android 出现 net::ERR_CLEARTEXT_NOT_PERMITTED 或明文通信被策略阻止时，添加 localhost 的 network_security_config.xml 并在清单中引用；iOS 提示构建中无加密时，安装 SQLCipher subspec 或使用 encrypted: false；Android 提示加密不可用时，在应用模块添加 net.zetetic:sqlcipher-android；encrypted 为 true 时提示需要密钥，则传入 encryptionKey；更新后应用以空数据库启动，说明文件路径已变，需执行第 4 步数据迁移；Web 出现 OPFS/SharedArrayBuffer 错误，通常是缺少 COOP/COEP 头或 Vite 预打包了 sqlite-wasm；query 返回对象而代码期望 { values }，是旧社区插件结果结构，需更新调用方使用行数组。

适用场景与限制

适用于需要从桥接式 SQLite 插件迁移到 Fast SQL 的 Capacitor 应用，尤其是大数据集、批量写入、加密、事务或 BLOB 场景。限制包括：现有数据不会自动迁移，必须执行数据保留步骤；加密文件需相同密钥与兼容 SQLCipher 版本；Web 端旧 sql.js + IndexedDB 数据不自动迁移；JSON 导入导出不再提供；需配置 iOS ATS 与 Android 明文网络策略；Web 端需 COOP/COEP 头。