@ capgo/ 电容- fast- sql

在您的 Capacitor app 中快速运行 SQLite : 查询会通过一个本地的 HTTP 通道而不是桥, 因此大结果集和同步任务保持快速 。 用可选的加密方式替换索引数据库.

🤖 建筑与AI编码代理? 安装 Capgo 技能 所以克劳德代码,代码,光标,副驾驶,或双子座CLI知道如何安装和使用 @capgo/capacitor-fast-sql 在您的电容应用程序中: npx skills add Cap-go/capgo-skills。然后问你的经纪人: 加上@capgo/capor-fast-sql到我的Capacitor应用上 代理设置指南 • 妇女 主机磁共振

主要特点

• 快速路径数字 : connect() 打开数据库并启动本地服务器, getServerInfo() 返回其端口和直接调用符号.
• SQL 组合键数字 : execute() 运行带有参数的语句,加上批量操作.
• 交易数字 : beginTransaction(), (中文(简体) ), commitTransaction() 财务报告和审定财务报表 rollbackTransaction()。 。 。 .
• 加密:通过SQLCipher在iOS和Android上的可选加密数据库.
• 网页数字 : configureWeb() 设置正式的 SQLite Wasm 模块,当您的服务器允许时, OPFS 将持续 .
• 平台:iOS,Android和Web. iOS和Android上的原生SQLite,网络上的SQLite Wasm.

为什么是SQL快?

传统的Capacitor插件通过JavaScript桥将数据序列化,随着大型数据集的出现而变得效率低下. Fast SQL通过建立本地的HTTP服务器直接进行本土通信来解决了这个问题,使它成为:

• 本地第一同步系统 (CRDT,业务转换)
• 索引数据库替换 执行中断/受限的平台
• 大型数据集业务 需要高吞吐量
• 批量操作 数以千计的行
• 二进制数据存储 (BLOBs,文档)

文档

这里有最完整的医生: https://capgo.app/docs/plugins/fast-sql/ 互联网档案馆的存檔,存档日期2014-12-21

兼容性

说明: 此插件的主要版本沿用了Capacitor的主要版本. 使用匹配您的 Capacitor 安装的版本( 如 Capacitor 8 的插件 v8) 。 只有最新的主要版本得到积极维护.

安装

您可以使用我们的 AI 辅助设置安装插件 。 使用以下命令将 Capgo 技能添加到您的 AI 工具 :

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

然后使用下列提示:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-fast-sql` plugin in my project.

如果您更喜欢手动设置,请通过运行以下命令来安装插件,并遵循下面的平台特定指令:

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

概览

此插件直接提供本地的 SQLite 数据库访问权限, 由 : 电容-布洛布写作机. 它不使用Capacitor的标准桥(将数据串行效率低下),而是建立了一个本地的HTTP服务器,用于大数据集和同步操作的最佳性能.

关键特性

• 自定义 HTTP 协议: Bypasses Capacitor 的桥能以大数据达到25x更快的性能
• 直接原生 SQLite: 完整 SQL 支持交易、批量操作和二进制数据
• 同步亲切: 为本地同步系统(CRDT、业务转换等)所设计
• 索引 DB 替换: 为中断/受限的索引数据库执行提供可靠的替代办法
• 横线:iOS、Android和Web(使用 @sqlite.org/sqlite-wasm (英语) 与业务方案融资战略的持久性)
• 可选 RAG 矢量系统: 坚持许多命名的向量存储, 用于回收- 增强生成,而不添加本地依赖性

iOS 配置

此插件运行本地 HTTP 服务器 localhostiOS App Transport Security (ATS) 默认屏蔽清除文本 HTTP, 所以你 必须 允许您的本地网络 Info.plist数字 :

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

这只允许清晰的文本回回回地址( C)localhost 编号 : 127.0.0.1它不会削弱苯丙胺类兴奋剂的外部联系.

Android 配置

此插件运行本地 HTTP 服务器 localhost 绕过Capacitor的桥进行表演. Android 9+ 块 默认的清除文本( 非 HTTPS) 流量, 所以您 必须 允许它 localhost。 。 。 .

备选案文A, 仅限本地主机(建议):

创建 android/app/src/main/res/xml/network_security_config.xml数字 :

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

那就在你的书中提及 AndroidManifest.xml数字 :

<application
    android:networkSecurityConfig="@xml/network_security_config">
    ...
</application>

备选案文B, 允许所有清晰文本( 简单但安全性较差 ) :

<application
    android:usesCleartextTraffic="true">
    ...
</application>

加密

机器人

加密用途 SQLCipher 数据 并被选入。 将 SQLCipher 依赖添加到您的 应用程序级 build.gradle数字 :

dependencies {
    implementation 'net.zetetic:sqlcipher-android:4.13.0'
}

然后与加密连接启用 :

const db = await FastSQL.connect({
  database: 'secure',
  encrypted: true,
  encryptionKey: 'my-secret-key',
});

如果 SQLCipher 没有安装 encrypted: true ,插件返回清晰的错误消息而不是崩溃.

iOS系统

SQLCipher在iOS上是可选的. 插件没有它会构建; 加密调用会返回 Encryption is not available in this build 除非安装了 SQLCipher .

要通过 CocoaPods 加密, 请更新您的 ios/App/Podfile 之后 capacitor install编号 :cap sync 以使用 SQLCipher 子规格 :

pod 'CapgoCapacitorFastSql/SQLCipher', :path => '../../node_modules/@capgo/capacitor-fast-sql'

然后运行 pod install 输入 ios/App 目录。 如果您跳过此子规格, 请保留 encrypted: false。 。 。 .

网络平台

在网络上, 此插件使用正式 @sqlite.org/sqlite-wasm (英语) 与 财务处 坚持不懈 SQLite 直接读取并写入数据库文件,它并没有被完全装入RAM或通过索引数据库镜像.

OPFS要工作,您的网络服务器必须发送 Cross-Origin 孤立头:

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

与 Vite 连接 :

import { defineConfig } from 'vite';

export default defineConfig({
  server: {
    headers: {
      'Cross-Origin-Opener-Policy': 'same-origin',
      'Cross-Origin-Embedder-Policy': 'require-corp',
    },
  },
  optimizeDeps: {
    exclude: ['@sqlite.org/sqlite-wasm'],
  },
});

可选的网络配置( 第一次访问前) connect():

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

await CapgoCapacitorFastSql.configureWeb({
  useOpfs: true,
});

const db = await FastSQL.connect({ database: 'myapp' });

configureWeb() 是iOS和Android上的禁用程序 无条件打电话是安全的.

说明: 以前由 sql.js 存储在索引数据库中的现有数据库不会被自动迁移. 必要时在升级后重新播种或导入数据.

使用量

基本示例

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

// Connect to database
const db = await FastSQL.connect({ database: 'myapp' });

// Create table
await db.execute(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE
  )
`);

// Insert data
const result = await db.run(
  'INSERT INTO users (name, email) VALUES (?, ?)',
  ['John Doe', '[email protected]']
);
console.log('Inserted row ID:', result.insertId);

// Query data
const users = await db.query('SELECT * FROM users WHERE name LIKE ?', ['John%']);
console.log('Users:', users);

// Close connection
await FastSQL.disconnect('myapp');

交易示例

const db = await FastSQL.connect({ database: 'myapp' });

try {
  await db.transaction(async (tx) => {
    await tx.run('INSERT INTO accounts (name, balance) VALUES (?, ?)', ['Alice', 1000]);
    await tx.run('INSERT INTO accounts (name, balance) VALUES (?, ?)', ['Bob', 500]);
    await tx.run('UPDATE accounts SET balance = balance - 100 WHERE name = ?', ['Alice']);
    await tx.run('UPDATE accounts SET balance = balance + 100 WHERE name = ?', ['Bob']);
  });
  console.log('Transaction successful!');
} catch (error) {
  console.error('Transaction failed:', error);
}

批量操作

const db = await FastSQL.connect({ database: 'myapp' });

const results = await db.executeBatch([
  { statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 1'] },
  { statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 2'] },
  { statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 3'] },
]);

关键值存储(以移动为重点的)

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

const kv = await KeyValueStore.open({
  database: 'myapp',
  encrypted: true,
  encryptionKey: 'super-secret-key',
});

await kv.set('session', { token: 'abc123', expiresAt: 1710000000 });
const session = await kv.get('session');
await kv.remove('session');

RAG 矢量存储器(可选)

FastSQLVectorStore 提供不受依赖的矢量相容辅助器 @react-native-rag/op-sqlite。它将嵌入到 SQLite 中作为二进制 Float32 向量存储,并在 TypeScript 中计算同位素相似性,所以它在这个插件工作的任何地点都有效.

每个商店都由 store 选项,因此一个数据库可以按需要持有尽可能多的独立矢量存储:

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

const docs = await FastSQLVectorStore.open({
  database: 'rag',
  store: 'docs',
  embeddings,
});

const tickets = await FastSQLVectorStore.open({
  database: 'rag',
  store: 'tickets',
  embeddings,
});

await docs.add({
  document: 'Capgo ships instant updates for Capacitor apps.',
  metadata: { source: 'docs' },
});

const results = await docs.query({
  queryText: 'How do instant updates work?',
  nResults: 3,
});

await docs.close();
await tickets.close();

您也可以使用没有嵌入提供者的预计算嵌入:

const store = await FastSQLVectorStore.open({
  database: 'rag',
  store: 'offline-embeddings',
  embeddingDimension: 384,
});

await store.add({
  id: 'intro',
  document: 'Local RAG entry',
  embedding: [0.12, 0.08, 0.31 /* ...384 values */],
});

const matches = await store.query({
  queryEmbedding: [0.11, 0.09, 0.29 /* ...384 values */],
  nResults: 5,
});

注:网页支持仅用于最小测试。 主要焦点是iOS/Android.

API 密码

• connect(...)
• disconnect(...)
• getServerInfo(...)
• execute(...)
• beginTransaction(...)
• commitTransaction(...)
• rollbackTransaction(...)
• getPluginVersion()
• configureWeb(...)
• 接口
• 类型异名
• 数字

用于高性能 SQLite 数据库访问的快速 SQL 插件 .

此插件使用基于 HTTP 的自定义协议来高效传输数据 , 绕过Capacitor的标准桥,以配合同步操作提高性能.

连接(...)

connect(options: SQLConnectionOptions) => Promise<{ port: number; token: string; database: string; persistent?: boolean; binaryProtocolVersion?: number; }>

初始化数据库连接并启动 HTTP 服务器 .

回返情况: Promise<{ port: number; token: string; database: string; persistent?: boolean; binaryProtocolVersion?: number; }>

自: 0.0.1 资源

断开(...)

disconnect(options: { database: string; }) => Promise<void>

关闭数据库连接并停止HTTP服务器.

自: 0.0.1 资源

获取ServerInfo(...)

getServerInfo(options: { database: string; }) => Promise<{ port: number; token: string; persistent?: boolean; binaryProtocolVersion?: number; }>

获取 HTTP 服务器端口和指使符进行直接通信.

回返情况: Promise<{ port: number; token: string; persistent?: boolean; binaryProtocolVersion?: number; }>

自: 0.0.1 资源

执行(...)

execute(options: { database: string; statement: string; params?: SQLValue[]; }) => Promise<SQLResult>

通过 Capacitor 桥执行 SQL 查询(用于简单的查询) . 为了在大型数据集中更好的性能,直接通过SQLConnection类使用HTTP协议.

回返情况: Promise<SQLResult>

自: 0.0.1 资源

开始交易(...)

beginTransaction(options: { database: string; isolationLevel?: IsolationLevel; }) => Promise<void>

开始数据库交易 .

自: 0.0.1 资源

执行交易(...)

commitTransaction(options: { database: string; }) => Promise<void>

提交当前交易 .

自: 0.0.1 资源

回滚变换(...)

rollbackTransaction(options: { database: string; }) => Promise<void>

倒转当前交易.

自: 0.0.1 资源

获取 PluginVersion ()

getPluginVersion() => Promise<{ version: string; binaryProtocolVersion?: number; }>

获取本地 Capacitor 插件版本 .

回返情况: Promise<{ version: string; binaryProtocolVersion?: number; }>

自: 0.0.1 资源

配置Web (...)

configureWeb(config: WebConfig) => Promise<void>

为正式的SQLite Wasm模块配置网络专用选项.

叫这个 在此之前 首个 connect() 如果您需要禁用 OPFS 调用 或提供定制工人。 这种方法是iOS和Android上的禁用.

自: 0.0.1 资源

接口

SQLC 选项

数据库连接选项

SQL 结果

SQL 查询执行的结果

SQLRow 图像

SQL 行结果 - 按列名索引的值

Uint8 阵列

一个8位无符号整数的打出数组。 内容初始化为0. 如果 无法分配请求的字节数 .

矩阵类似

矩阵缓冲键

允许 矩阵缓冲 arrayBufferView 和相关类型矩阵的缓冲类型.

矩阵缓冲

代表二进制数据的原始缓冲,用于存储数据 不同键入数组。 无法直接读取或写入矩阵缓冲器, 但是可以传递到一个被键入的数组或 DataView 对象来解释原始 视需要进行缓冲.

网络配置

官方SQLite Wasm模块的Web平台配置. 使用方式 configureWeb() 第一次选举之前 connect()。 。 。 .

OPFS的持久性需要您网络服务器上的 Cross-Origin 隔离头: Cross-Origin-Opener-Policy: same-origin 财务报告和审定财务报表 Cross-Origin-Embedder-Policy: require-corp。 。 。 .

类型异名

本地SQL 运输

原生HTTP数据编码. JSON仍然是兼容默认.

'http-json' | 'http-binary'

质量

插件支持的 SQL 值类型

string | number | boolean | null | Uint8Array

矩阵缓冲像

ArrayBufferTypes[keyof ArrayBufferTypes]

Sqlite 网络工人

浏览器 Worker 实例或返回一个的厂家 . 曾经覆盖默认的 SQLite Wasm 工人 .

Worker | (() => Worker)

数字

隔离级别