@capgo/capacitor-fast-sql 8.2.12 → 8.2.13
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
# @capgo/capacitor-fast-sql
|
|
1
|
+
# @capgo/capacitor-fast-sql
|
|
2
2
|
|
|
3
3
|
Run SQLite fast in your Capacitor app: queries go through a local HTTP channel instead of the bridge, so large result sets and sync jobs stay quick. A practical replacement for IndexedDB, with optional encryption.
|
|
4
4
|
|
|
@@ -8,10 +8,9 @@ Run SQLite fast in your Capacitor app: queries go through a local HTTP channel i
|
|
|
8
8
|
<p><b>Capgo</b>: push fixes to your Capacitor users in minutes, build signed iOS and Android apps without a Mac, and roll back in one click.</p>
|
|
9
9
|
<h2><a href="https://capgo.app/register/?ref=plugin_fast_sql">➡️ Get started for free</a></h2>
|
|
10
10
|
<p>14-day unlimited free trial. No credit card required</p>
|
|
11
|
-
<p><a href="https://capgo.app/consulting/?ref=plugin_fast_sql">Missing a feature? We'll build the plugin for you 💪</a></p>
|
|
12
11
|
</div>
|
|
13
|
-
|
|
14
|
-
> 🤖 **Building with an AI coding agent?** Install [Capgo skills](https://capgo.app/skills/?ref=plugin_fast_sql) so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use `@capgo/capacitor-fast-sql` in your Capacitor app: `npx skills add Cap-go/capgo-skills`. Then ask your agent: *"Add @capgo/capacitor-fast-sql to my Capacitor app and wire it up."* [Agent setup guides](https://capgo.app/agents/?ref=plugin_fast_sql) · [Hosted MCP](https://capgo.app/docs/ai/mcp/?ref=plugin_fast_sql)
|
|
12
|
+
|
|
13
|
+
> 🤖 **Building with an AI coding agent?** Install [Capgo skills](https://capgo.app/skills/?ref=plugin_fast_sql) so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use `@capgo/capacitor-fast-sql` in your Capacitor app: `npx skills add Cap-go/capgo-skills`. Then ask your agent: *"Add @capgo/capacitor-fast-sql to my Capacitor app and wire it up."* [Agent setup guides](https://capgo.app/agents/?ref=plugin_fast_sql) · [Hosted MCP](https://capgo.app/docs/ai/mcp/?ref=plugin_fast_sql)
|
|
15
14
|
|
|
16
15
|
<p align="center">
|
|
17
16
|
<img src="https://raw.githubusercontent.com/Cap-go/capacitor-fast-sql/main/assets/github-social-preview.png" alt="@capgo/capacitor-fast-sql for Capacitor apps" width="300" />
|
|
@@ -26,151 +25,151 @@ Run SQLite fast in your Capacitor app: queries go through a local HTTP channel i
|
|
|
26
25
|
- **Web**: `configureWeb()` sets up the official SQLite Wasm module, with OPFS persistence when your server allows it.
|
|
27
26
|
- **Platforms**: iOS, Android and Web. Native SQLite on iOS and Android, SQLite Wasm on web.
|
|
28
27
|
|
|
29
|
-
## Why Fast SQL?
|
|
30
|
-
|
|
31
|
-
Traditional Capacitor plugins serialize data through the JavaScript bridge, which becomes inefficient with large datasets. Fast SQL solves this by establishing a local HTTP server for direct native communication, making it ideal for:
|
|
32
|
-
|
|
33
|
-
- **Local-first sync systems** (CRDTs, operational transforms)
|
|
34
|
-
- **IndexedDB replacement** on platforms with broken/limited implementations
|
|
35
|
-
- **Large dataset operations** requiring high throughput
|
|
36
|
-
- **Batch operations** with thousands of rows
|
|
37
|
-
- **Binary data storage** (BLOBs, files)
|
|
38
|
-
|
|
39
|
-
## Documentation
|
|
40
|
-
|
|
41
|
-
The most complete doc is available here: https://capgo.app/docs/plugins/fast-sql/
|
|
42
|
-
|
|
43
|
-
## Compatibility
|
|
44
|
-
|
|
45
|
-
| Plugin version | Capacitor compatibility | Maintained |
|
|
46
|
-
| -------------- | ----------------------- | ---------- |
|
|
47
|
-
| v8.\*.\* | v8.\*.\* | ✅ |
|
|
48
|
-
| v7.\*.\* | v7.\*.\* | On demand |
|
|
49
|
-
| v6.\*.\* | v6.\*.\* | ❌ |
|
|
50
|
-
| v5.\*.\* | v5.\*.\* | ❌ |
|
|
51
|
-
|
|
52
|
-
> **Note:** The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
|
|
53
|
-
|
|
54
|
-
## Install
|
|
55
|
-
|
|
56
|
-
You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:
|
|
57
|
-
|
|
58
|
-
```bash
|
|
59
|
-
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
|
|
60
|
-
```
|
|
61
|
-
|
|
62
|
-
Then use the following prompt:
|
|
63
|
-
|
|
64
|
-
```text
|
|
65
|
-
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-fast-sql` plugin in my project.
|
|
66
|
-
```
|
|
67
|
-
|
|
68
|
-
If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:
|
|
69
|
-
|
|
70
|
-
```bash
|
|
71
|
-
npm install @capgo/capacitor-fast-sql
|
|
72
|
-
npx cap sync
|
|
73
|
-
```
|
|
74
|
-
|
|
75
|
-
## Overview
|
|
76
|
-
|
|
77
|
-
This plugin provides direct native SQLite database access with a custom communication protocol inspired by [capacitor-blob-writer](https://github.com/diachedelic/capacitor-blob-writer). Instead of using Capacitor's standard bridge (which serializes data inefficiently), it establishes a local HTTP server for optimal performance with large datasets and sync operations.
|
|
78
|
-
|
|
79
|
-
### Key Features
|
|
80
|
-
|
|
81
|
-
- **Custom HTTP Protocol**: Bypasses Capacitor's bridge for up to 25x faster performance with large data
|
|
82
|
-
- **Direct Native SQLite**: Full SQL support with transactions, batch operations, and binary data
|
|
83
|
-
- **Sync-Friendly**: Designed for local sync systems (CRDTs, operational transforms, etc.)
|
|
84
|
-
- **IndexedDB Replacement**: Provides reliable alternative to broken/limited IndexedDB implementations
|
|
28
|
+
## Why Fast SQL?
|
|
29
|
+
|
|
30
|
+
Traditional Capacitor plugins serialize data through the JavaScript bridge, which becomes inefficient with large datasets. Fast SQL solves this by establishing a local HTTP server for direct native communication, making it ideal for:
|
|
31
|
+
|
|
32
|
+
- **Local-first sync systems** (CRDTs, operational transforms)
|
|
33
|
+
- **IndexedDB replacement** on platforms with broken/limited implementations
|
|
34
|
+
- **Large dataset operations** requiring high throughput
|
|
35
|
+
- **Batch operations** with thousands of rows
|
|
36
|
+
- **Binary data storage** (BLOBs, files)
|
|
37
|
+
|
|
38
|
+
## Documentation
|
|
39
|
+
|
|
40
|
+
The most complete doc is available here: https://capgo.app/docs/plugins/fast-sql/
|
|
41
|
+
|
|
42
|
+
## Compatibility
|
|
43
|
+
|
|
44
|
+
| Plugin version | Capacitor compatibility | Maintained |
|
|
45
|
+
| -------------- | ----------------------- | ---------- |
|
|
46
|
+
| v8.\*.\* | v8.\*.\* | ✅ |
|
|
47
|
+
| v7.\*.\* | v7.\*.\* | On demand |
|
|
48
|
+
| v6.\*.\* | v6.\*.\* | ❌ |
|
|
49
|
+
| v5.\*.\* | v5.\*.\* | ❌ |
|
|
50
|
+
|
|
51
|
+
> **Note:** The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
|
|
52
|
+
|
|
53
|
+
## Install
|
|
54
|
+
|
|
55
|
+
You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:
|
|
56
|
+
|
|
57
|
+
```bash
|
|
58
|
+
npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
Then use the following prompt:
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-fast-sql` plugin in my project.
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:
|
|
68
|
+
|
|
69
|
+
```bash
|
|
70
|
+
npm install @capgo/capacitor-fast-sql
|
|
71
|
+
npx cap sync
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## Overview
|
|
75
|
+
|
|
76
|
+
This plugin provides direct native SQLite database access with a custom communication protocol inspired by [capacitor-blob-writer](https://github.com/diachedelic/capacitor-blob-writer). Instead of using Capacitor's standard bridge (which serializes data inefficiently), it establishes a local HTTP server for optimal performance with large datasets and sync operations.
|
|
77
|
+
|
|
78
|
+
### Key Features
|
|
79
|
+
|
|
80
|
+
- **Custom HTTP Protocol**: Bypasses Capacitor's bridge for up to 25x faster performance with large data
|
|
81
|
+
- **Direct Native SQLite**: Full SQL support with transactions, batch operations, and binary data
|
|
82
|
+
- **Sync-Friendly**: Designed for local sync systems (CRDTs, operational transforms, etc.)
|
|
83
|
+
- **IndexedDB Replacement**: Provides reliable alternative to broken/limited IndexedDB implementations
|
|
85
84
|
- **Cross-Platform**: iOS, Android, and Web (using [@sqlite.org/sqlite-wasm](https://github.com/sqlite/sqlite-wasm) with OPFS persistence)
|
|
86
|
-
- **Optional RAG VectorStore**: Persist many named vector stores for retrieval-augmented generation without adding a native dependency
|
|
87
|
-
|
|
88
|
-
## iOS Configuration
|
|
89
|
-
|
|
90
|
-
This plugin runs a local HTTP server on `localhost`. iOS App Transport Security (ATS) blocks cleartext HTTP by default, so you **must** allow local networking in your `Info.plist`:
|
|
91
|
-
|
|
92
|
-
```xml
|
|
93
|
-
<key>NSAppTransportSecurity</key>
|
|
94
|
-
<dict>
|
|
95
|
-
<key>NSAllowsLocalNetworking</key>
|
|
96
|
-
<true/>
|
|
97
|
-
</dict>
|
|
98
|
-
```
|
|
99
|
-
|
|
100
|
-
This only permits cleartext to loopback addresses (`localhost` / `127.0.0.1`), it does not weaken ATS for external connections.
|
|
101
|
-
|
|
102
|
-
## Android Configuration
|
|
103
|
-
|
|
104
|
-
This plugin runs a local HTTP server on `localhost` to bypass Capacitor's bridge for performance. Android 9+ blocks cleartext (non-HTTPS) traffic by default, so you **must** allow it for `localhost`.
|
|
105
|
-
|
|
106
|
-
**Option A, Scoped to localhost only (recommended):**
|
|
107
|
-
|
|
108
|
-
Create `android/app/src/main/res/xml/network_security_config.xml`:
|
|
109
|
-
|
|
110
|
-
```xml
|
|
111
|
-
<?xml version="1.0" encoding="utf-8"?>
|
|
112
|
-
<network-security-config>
|
|
113
|
-
<domain-config cleartextTrafficPermitted="true">
|
|
114
|
-
<domain includeSubdomains="false">localhost</domain>
|
|
115
|
-
<domain includeSubdomains="false">127.0.0.1</domain>
|
|
116
|
-
</domain-config>
|
|
117
|
-
</network-security-config>
|
|
118
|
-
```
|
|
119
|
-
|
|
120
|
-
Then reference it in your `AndroidManifest.xml`:
|
|
121
|
-
|
|
122
|
-
```xml
|
|
123
|
-
<application
|
|
124
|
-
android:networkSecurityConfig="@xml/network_security_config">
|
|
125
|
-
...
|
|
126
|
-
</application>
|
|
127
|
-
```
|
|
128
|
-
|
|
129
|
-
**Option B, Allow all cleartext (simpler but less secure):**
|
|
130
|
-
|
|
131
|
-
```xml
|
|
132
|
-
<application
|
|
133
|
-
android:usesCleartextTraffic="true">
|
|
134
|
-
...
|
|
135
|
-
</application>
|
|
136
|
-
```
|
|
137
|
-
|
|
138
|
-
## Encryption
|
|
139
|
-
|
|
140
|
-
### Android
|
|
141
|
-
|
|
142
|
-
Encryption uses [SQLCipher](https://www.zetetic.net/sqlcipher/) and is opt-in. Add the SQLCipher dependency to your **app-level** `build.gradle`:
|
|
143
|
-
|
|
144
|
-
```gradle
|
|
145
|
-
dependencies {
|
|
146
|
-
implementation 'net.zetetic:sqlcipher-android:4.13.0'
|
|
147
|
-
}
|
|
148
|
-
```
|
|
149
|
-
|
|
150
|
-
Then connect with encryption enabled:
|
|
151
|
-
|
|
152
|
-
```typescript
|
|
153
|
-
const db = await FastSQL.connect({
|
|
154
|
-
database: 'secure',
|
|
155
|
-
encrypted: true,
|
|
156
|
-
encryptionKey: 'my-secret-key',
|
|
157
|
-
});
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
If SQLCipher is not installed and `encrypted: true` is passed, the plugin returns a clear error message instead of crashing.
|
|
161
|
-
|
|
162
|
-
### iOS
|
|
163
|
-
|
|
164
|
-
SQLCipher is optional on iOS. The plugin builds without it; encryption calls will return `Encryption is not available in this build` unless SQLCipher is installed.
|
|
165
|
-
|
|
166
|
-
To enable encryption via CocoaPods, update your `ios/App/Podfile` after `capacitor install`/`cap sync` to use the SQLCipher subspec:
|
|
167
|
-
|
|
168
|
-
```ruby
|
|
169
|
-
pod 'CapgoCapacitorFastSql/SQLCipher', :path => '../../node_modules/@capgo/capacitor-fast-sql'
|
|
170
|
-
```
|
|
171
|
-
|
|
172
|
-
Then run `pod install` in the `ios/App` directory. If you skip this subspec, keep `encrypted: false`.
|
|
173
|
-
|
|
85
|
+
- **Optional RAG VectorStore**: Persist many named vector stores for retrieval-augmented generation without adding a native dependency
|
|
86
|
+
|
|
87
|
+
## iOS Configuration
|
|
88
|
+
|
|
89
|
+
This plugin runs a local HTTP server on `localhost`. iOS App Transport Security (ATS) blocks cleartext HTTP by default, so you **must** allow local networking in your `Info.plist`:
|
|
90
|
+
|
|
91
|
+
```xml
|
|
92
|
+
<key>NSAppTransportSecurity</key>
|
|
93
|
+
<dict>
|
|
94
|
+
<key>NSAllowsLocalNetworking</key>
|
|
95
|
+
<true/>
|
|
96
|
+
</dict>
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
This only permits cleartext to loopback addresses (`localhost` / `127.0.0.1`), it does not weaken ATS for external connections.
|
|
100
|
+
|
|
101
|
+
## Android Configuration
|
|
102
|
+
|
|
103
|
+
This plugin runs a local HTTP server on `localhost` to bypass Capacitor's bridge for performance. Android 9+ blocks cleartext (non-HTTPS) traffic by default, so you **must** allow it for `localhost`.
|
|
104
|
+
|
|
105
|
+
**Option A, Scoped to localhost only (recommended):**
|
|
106
|
+
|
|
107
|
+
Create `android/app/src/main/res/xml/network_security_config.xml`:
|
|
108
|
+
|
|
109
|
+
```xml
|
|
110
|
+
<?xml version="1.0" encoding="utf-8"?>
|
|
111
|
+
<network-security-config>
|
|
112
|
+
<domain-config cleartextTrafficPermitted="true">
|
|
113
|
+
<domain includeSubdomains="false">localhost</domain>
|
|
114
|
+
<domain includeSubdomains="false">127.0.0.1</domain>
|
|
115
|
+
</domain-config>
|
|
116
|
+
</network-security-config>
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
Then reference it in your `AndroidManifest.xml`:
|
|
120
|
+
|
|
121
|
+
```xml
|
|
122
|
+
<application
|
|
123
|
+
android:networkSecurityConfig="@xml/network_security_config">
|
|
124
|
+
...
|
|
125
|
+
</application>
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
**Option B, Allow all cleartext (simpler but less secure):**
|
|
129
|
+
|
|
130
|
+
```xml
|
|
131
|
+
<application
|
|
132
|
+
android:usesCleartextTraffic="true">
|
|
133
|
+
...
|
|
134
|
+
</application>
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## Encryption
|
|
138
|
+
|
|
139
|
+
### Android
|
|
140
|
+
|
|
141
|
+
Encryption uses [SQLCipher](https://www.zetetic.net/sqlcipher/) and is opt-in. Add the SQLCipher dependency to your **app-level** `build.gradle`:
|
|
142
|
+
|
|
143
|
+
```gradle
|
|
144
|
+
dependencies {
|
|
145
|
+
implementation 'net.zetetic:sqlcipher-android:4.13.0'
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
Then connect with encryption enabled:
|
|
150
|
+
|
|
151
|
+
```typescript
|
|
152
|
+
const db = await FastSQL.connect({
|
|
153
|
+
database: 'secure',
|
|
154
|
+
encrypted: true,
|
|
155
|
+
encryptionKey: 'my-secret-key',
|
|
156
|
+
});
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
If SQLCipher is not installed and `encrypted: true` is passed, the plugin returns a clear error message instead of crashing.
|
|
160
|
+
|
|
161
|
+
### iOS
|
|
162
|
+
|
|
163
|
+
SQLCipher is optional on iOS. The plugin builds without it; encryption calls will return `Encryption is not available in this build` unless SQLCipher is installed.
|
|
164
|
+
|
|
165
|
+
To enable encryption via CocoaPods, update your `ios/App/Podfile` after `capacitor install`/`cap sync` to use the SQLCipher subspec:
|
|
166
|
+
|
|
167
|
+
```ruby
|
|
168
|
+
pod 'CapgoCapacitorFastSql/SQLCipher', :path => '../../node_modules/@capgo/capacitor-fast-sql'
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
Then run `pod install` in the `ios/App` directory. If you skip this subspec, keep `encrypted: false`.
|
|
172
|
+
|
|
174
173
|
## Web Platform
|
|
175
174
|
|
|
176
175
|
On the web, this plugin uses the official [@sqlite.org/sqlite-wasm](https://github.com/sqlite/sqlite-wasm) build with [OPFS](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API/Origin_private_file_system) for persistence. SQLite reads and writes the database file directly, it is not loaded entirely into RAM or mirrored through IndexedDB.
|
|
@@ -215,147 +214,147 @@ const db = await FastSQL.connect({ database: 'myapp' });
|
|
|
215
214
|
`configureWeb()` is a no-op on iOS and Android, it is safe to call unconditionally.
|
|
216
215
|
|
|
217
216
|
> **Note:** Existing databases previously stored in IndexedDB by sql.js are not migrated automatically. Re-seed or import data after upgrading if needed.
|
|
218
|
-
|
|
219
|
-
## Usage
|
|
220
|
-
|
|
221
|
-
### Basic Example
|
|
222
|
-
|
|
223
|
-
```typescript
|
|
224
|
-
import { FastSQL } from '@capgo/capacitor-fast-sql';
|
|
225
|
-
|
|
226
|
-
// Connect to database
|
|
227
|
-
const db = await FastSQL.connect({ database: 'myapp' });
|
|
228
|
-
|
|
229
|
-
// Create table
|
|
230
|
-
await db.execute(`
|
|
231
|
-
CREATE TABLE IF NOT EXISTS users (
|
|
232
|
-
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
233
|
-
name TEXT NOT NULL,
|
|
234
|
-
email TEXT UNIQUE
|
|
235
|
-
)
|
|
236
|
-
`);
|
|
237
|
-
|
|
238
|
-
// Insert data
|
|
239
|
-
const result = await db.run(
|
|
240
|
-
'INSERT INTO users (name, email) VALUES (?, ?)',
|
|
241
|
-
['John Doe', 'john@example.com']
|
|
242
|
-
);
|
|
243
|
-
console.log('Inserted row ID:', result.insertId);
|
|
244
|
-
|
|
245
|
-
// Query data
|
|
246
|
-
const users = await db.query('SELECT * FROM users WHERE name LIKE ?', ['John%']);
|
|
247
|
-
console.log('Users:', users);
|
|
248
|
-
|
|
249
|
-
// Close connection
|
|
250
|
-
await FastSQL.disconnect('myapp');
|
|
251
|
-
```
|
|
252
|
-
|
|
253
|
-
### Transaction Example
|
|
254
|
-
|
|
255
|
-
```typescript
|
|
256
|
-
const db = await FastSQL.connect({ database: 'myapp' });
|
|
257
|
-
|
|
258
|
-
try {
|
|
259
|
-
await db.transaction(async (tx) => {
|
|
260
|
-
await tx.run('INSERT INTO accounts (name, balance) VALUES (?, ?)', ['Alice', 1000]);
|
|
261
|
-
await tx.run('INSERT INTO accounts (name, balance) VALUES (?, ?)', ['Bob', 500]);
|
|
262
|
-
await tx.run('UPDATE accounts SET balance = balance - 100 WHERE name = ?', ['Alice']);
|
|
263
|
-
await tx.run('UPDATE accounts SET balance = balance + 100 WHERE name = ?', ['Bob']);
|
|
264
|
-
});
|
|
265
|
-
console.log('Transaction successful!');
|
|
266
|
-
} catch (error) {
|
|
267
|
-
console.error('Transaction failed:', error);
|
|
268
|
-
}
|
|
269
|
-
```
|
|
270
|
-
|
|
271
|
-
### Batch Operations
|
|
272
|
-
|
|
273
|
-
```typescript
|
|
274
|
-
const db = await FastSQL.connect({ database: 'myapp' });
|
|
275
|
-
|
|
276
|
-
const results = await db.executeBatch([
|
|
277
|
-
{ statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 1'] },
|
|
278
|
-
{ statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 2'] },
|
|
279
|
-
{ statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 3'] },
|
|
280
|
-
]);
|
|
281
|
-
```
|
|
282
|
-
|
|
283
|
-
### Key-Value Storage (Mobile-focused)
|
|
284
|
-
|
|
285
|
-
```typescript
|
|
286
|
-
import { KeyValueStore } from '@capgo/capacitor-fast-sql';
|
|
287
|
-
|
|
288
|
-
const kv = await KeyValueStore.open({
|
|
289
|
-
database: 'myapp',
|
|
290
|
-
encrypted: true,
|
|
291
|
-
encryptionKey: 'super-secret-key',
|
|
292
|
-
});
|
|
293
|
-
|
|
294
|
-
await kv.set('session', { token: 'abc123', expiresAt: 1710000000 });
|
|
295
|
-
const session = await kv.get('session');
|
|
296
|
-
await kv.remove('session');
|
|
297
|
-
```
|
|
298
|
-
|
|
299
|
-
### RAG Vector Stores (Optional)
|
|
300
|
-
|
|
301
|
-
`FastSQLVectorStore` provides a dependency-free VectorStore-compatible helper inspired by `@react-native-rag/op-sqlite`. It stores embeddings in SQLite as binary Float32 vectors and computes cosine similarity in TypeScript, so it works anywhere this plugin works.
|
|
302
|
-
|
|
303
|
-
Each store is namespaced by the `store` option, so one database can hold as many independent vector stores as you need:
|
|
304
|
-
|
|
305
|
-
```typescript
|
|
306
|
-
import { FastSQLVectorStore } from '@capgo/capacitor-fast-sql';
|
|
307
|
-
|
|
308
|
-
const docs = await FastSQLVectorStore.open({
|
|
309
|
-
database: 'rag',
|
|
310
|
-
store: 'docs',
|
|
311
|
-
embeddings,
|
|
312
|
-
});
|
|
313
|
-
|
|
314
|
-
const tickets = await FastSQLVectorStore.open({
|
|
315
|
-
database: 'rag',
|
|
316
|
-
store: 'tickets',
|
|
317
|
-
embeddings,
|
|
318
|
-
});
|
|
319
|
-
|
|
320
|
-
await docs.add({
|
|
321
|
-
document: 'Capgo ships instant updates for Capacitor apps.',
|
|
322
|
-
metadata: { source: 'docs' },
|
|
323
|
-
});
|
|
324
|
-
|
|
325
|
-
const results = await docs.query({
|
|
326
|
-
queryText: 'How do instant updates work?',
|
|
327
|
-
nResults: 3,
|
|
328
|
-
});
|
|
329
|
-
|
|
330
|
-
await docs.close();
|
|
331
|
-
await tickets.close();
|
|
332
|
-
```
|
|
333
|
-
|
|
334
|
-
You can also use precomputed embeddings without an embeddings provider:
|
|
335
|
-
|
|
336
|
-
```typescript
|
|
337
|
-
const store = await FastSQLVectorStore.open({
|
|
338
|
-
database: 'rag',
|
|
339
|
-
store: 'offline-embeddings',
|
|
340
|
-
embeddingDimension: 384,
|
|
341
|
-
});
|
|
342
|
-
|
|
343
|
-
await store.add({
|
|
344
|
-
id: 'intro',
|
|
345
|
-
document: 'Local RAG entry',
|
|
346
|
-
embedding: [0.12, 0.08, 0.31 /* ...384 values */],
|
|
347
|
-
});
|
|
348
|
-
|
|
349
|
-
const matches = await store.query({
|
|
350
|
-
queryEmbedding: [0.11, 0.09, 0.29 /* ...384 values */],
|
|
351
|
-
nResults: 5,
|
|
352
|
-
});
|
|
353
|
-
```
|
|
354
|
-
|
|
355
|
-
> Note: Web support is intended for minimal testing only. The primary focus is iOS/Android.
|
|
356
|
-
|
|
357
|
-
## API
|
|
358
|
-
|
|
217
|
+
|
|
218
|
+
## Usage
|
|
219
|
+
|
|
220
|
+
### Basic Example
|
|
221
|
+
|
|
222
|
+
```typescript
|
|
223
|
+
import { FastSQL } from '@capgo/capacitor-fast-sql';
|
|
224
|
+
|
|
225
|
+
// Connect to database
|
|
226
|
+
const db = await FastSQL.connect({ database: 'myapp' });
|
|
227
|
+
|
|
228
|
+
// Create table
|
|
229
|
+
await db.execute(`
|
|
230
|
+
CREATE TABLE IF NOT EXISTS users (
|
|
231
|
+
id INTEGER PRIMARY KEY AUTOINCREMENT,
|
|
232
|
+
name TEXT NOT NULL,
|
|
233
|
+
email TEXT UNIQUE
|
|
234
|
+
)
|
|
235
|
+
`);
|
|
236
|
+
|
|
237
|
+
// Insert data
|
|
238
|
+
const result = await db.run(
|
|
239
|
+
'INSERT INTO users (name, email) VALUES (?, ?)',
|
|
240
|
+
['John Doe', 'john@example.com']
|
|
241
|
+
);
|
|
242
|
+
console.log('Inserted row ID:', result.insertId);
|
|
243
|
+
|
|
244
|
+
// Query data
|
|
245
|
+
const users = await db.query('SELECT * FROM users WHERE name LIKE ?', ['John%']);
|
|
246
|
+
console.log('Users:', users);
|
|
247
|
+
|
|
248
|
+
// Close connection
|
|
249
|
+
await FastSQL.disconnect('myapp');
|
|
250
|
+
```
|
|
251
|
+
|
|
252
|
+
### Transaction Example
|
|
253
|
+
|
|
254
|
+
```typescript
|
|
255
|
+
const db = await FastSQL.connect({ database: 'myapp' });
|
|
256
|
+
|
|
257
|
+
try {
|
|
258
|
+
await db.transaction(async (tx) => {
|
|
259
|
+
await tx.run('INSERT INTO accounts (name, balance) VALUES (?, ?)', ['Alice', 1000]);
|
|
260
|
+
await tx.run('INSERT INTO accounts (name, balance) VALUES (?, ?)', ['Bob', 500]);
|
|
261
|
+
await tx.run('UPDATE accounts SET balance = balance - 100 WHERE name = ?', ['Alice']);
|
|
262
|
+
await tx.run('UPDATE accounts SET balance = balance + 100 WHERE name = ?', ['Bob']);
|
|
263
|
+
});
|
|
264
|
+
console.log('Transaction successful!');
|
|
265
|
+
} catch (error) {
|
|
266
|
+
console.error('Transaction failed:', error);
|
|
267
|
+
}
|
|
268
|
+
```
|
|
269
|
+
|
|
270
|
+
### Batch Operations
|
|
271
|
+
|
|
272
|
+
```typescript
|
|
273
|
+
const db = await FastSQL.connect({ database: 'myapp' });
|
|
274
|
+
|
|
275
|
+
const results = await db.executeBatch([
|
|
276
|
+
{ statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 1'] },
|
|
277
|
+
{ statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 2'] },
|
|
278
|
+
{ statement: 'INSERT INTO logs (message) VALUES (?)', params: ['Log 3'] },
|
|
279
|
+
]);
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
### Key-Value Storage (Mobile-focused)
|
|
283
|
+
|
|
284
|
+
```typescript
|
|
285
|
+
import { KeyValueStore } from '@capgo/capacitor-fast-sql';
|
|
286
|
+
|
|
287
|
+
const kv = await KeyValueStore.open({
|
|
288
|
+
database: 'myapp',
|
|
289
|
+
encrypted: true,
|
|
290
|
+
encryptionKey: 'super-secret-key',
|
|
291
|
+
});
|
|
292
|
+
|
|
293
|
+
await kv.set('session', { token: 'abc123', expiresAt: 1710000000 });
|
|
294
|
+
const session = await kv.get('session');
|
|
295
|
+
await kv.remove('session');
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
### RAG Vector Stores (Optional)
|
|
299
|
+
|
|
300
|
+
`FastSQLVectorStore` provides a dependency-free VectorStore-compatible helper inspired by `@react-native-rag/op-sqlite`. It stores embeddings in SQLite as binary Float32 vectors and computes cosine similarity in TypeScript, so it works anywhere this plugin works.
|
|
301
|
+
|
|
302
|
+
Each store is namespaced by the `store` option, so one database can hold as many independent vector stores as you need:
|
|
303
|
+
|
|
304
|
+
```typescript
|
|
305
|
+
import { FastSQLVectorStore } from '@capgo/capacitor-fast-sql';
|
|
306
|
+
|
|
307
|
+
const docs = await FastSQLVectorStore.open({
|
|
308
|
+
database: 'rag',
|
|
309
|
+
store: 'docs',
|
|
310
|
+
embeddings,
|
|
311
|
+
});
|
|
312
|
+
|
|
313
|
+
const tickets = await FastSQLVectorStore.open({
|
|
314
|
+
database: 'rag',
|
|
315
|
+
store: 'tickets',
|
|
316
|
+
embeddings,
|
|
317
|
+
});
|
|
318
|
+
|
|
319
|
+
await docs.add({
|
|
320
|
+
document: 'Capgo ships instant updates for Capacitor apps.',
|
|
321
|
+
metadata: { source: 'docs' },
|
|
322
|
+
});
|
|
323
|
+
|
|
324
|
+
const results = await docs.query({
|
|
325
|
+
queryText: 'How do instant updates work?',
|
|
326
|
+
nResults: 3,
|
|
327
|
+
});
|
|
328
|
+
|
|
329
|
+
await docs.close();
|
|
330
|
+
await tickets.close();
|
|
331
|
+
```
|
|
332
|
+
|
|
333
|
+
You can also use precomputed embeddings without an embeddings provider:
|
|
334
|
+
|
|
335
|
+
```typescript
|
|
336
|
+
const store = await FastSQLVectorStore.open({
|
|
337
|
+
database: 'rag',
|
|
338
|
+
store: 'offline-embeddings',
|
|
339
|
+
embeddingDimension: 384,
|
|
340
|
+
});
|
|
341
|
+
|
|
342
|
+
await store.add({
|
|
343
|
+
id: 'intro',
|
|
344
|
+
document: 'Local RAG entry',
|
|
345
|
+
embedding: [0.12, 0.08, 0.31 /* ...384 values */],
|
|
346
|
+
});
|
|
347
|
+
|
|
348
|
+
const matches = await store.query({
|
|
349
|
+
queryEmbedding: [0.11, 0.09, 0.29 /* ...384 values */],
|
|
350
|
+
nResults: 5,
|
|
351
|
+
});
|
|
352
|
+
```
|
|
353
|
+
|
|
354
|
+
> Note: Web support is intended for minimal testing only. The primary focus is iOS/Android.
|
|
355
|
+
|
|
356
|
+
## API
|
|
357
|
+
|
|
359
358
|
<docgen-index>
|
|
360
359
|
|
|
361
360
|
* [`connect(...)`](#connect)
|
|
@@ -371,8 +370,8 @@ const matches = await store.query({
|
|
|
371
370
|
* [Type Aliases](#type-aliases)
|
|
372
371
|
* [Enums](#enums)
|
|
373
372
|
|
|
374
|
-
</docgen-index>
|
|
375
|
-
|
|
373
|
+
</docgen-index>
|
|
374
|
+
|
|
376
375
|
<docgen-api>
|
|
377
376
|
<!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
|
|
378
377
|
|
|
@@ -700,4 +699,4 @@ Used to override the default SQLite Wasm worker.
|
|
|
700
699
|
| **`RepeatableRead`** | <code>'REPEATABLE READ'</code> |
|
|
701
700
|
| **`Serializable`** | <code>'SERIALIZABLE'</code> |
|
|
702
701
|
|
|
703
|
-
</docgen-api>
|
|
702
|
+
</docgen-api>
|
|
@@ -19,7 +19,7 @@ import java.util.Map;
|
|
|
19
19
|
@CapacitorPlugin(name = "CapgoCapacitorFastSql")
|
|
20
20
|
public class CapgoCapacitorFastSqlPlugin extends Plugin {
|
|
21
21
|
|
|
22
|
-
private final String pluginVersion = "8.2.
|
|
22
|
+
private final String pluginVersion = "8.2.13";
|
|
23
23
|
|
|
24
24
|
private Map<String, DatabaseConnection> databases = new HashMap<>();
|
|
25
25
|
private SQLHTTPServer server;
|
|
@@ -10,7 +10,7 @@ import SQLite3
|
|
|
10
10
|
*/
|
|
11
11
|
@objc(CapgoCapacitorFastSqlPlugin)
|
|
12
12
|
public class CapgoCapacitorFastSqlPlugin: CAPPlugin, CAPBridgedPlugin {
|
|
13
|
-
private let pluginVersion: String = "8.2.
|
|
13
|
+
private let pluginVersion: String = "8.2.13"
|
|
14
14
|
public let identifier = "CapgoCapacitorFastSqlPlugin"
|
|
15
15
|
public let jsName = "CapgoCapacitorFastSql"
|
|
16
16
|
public let pluginMethods: [CAPPluginMethod] = [
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@capgo/capacitor-fast-sql",
|
|
3
|
-
"version": "8.2.
|
|
3
|
+
"version": "8.2.13",
|
|
4
4
|
"description": "High-performance native SQLite plugin with custom protocol for efficient sync operations and IndexedDB replacement",
|
|
5
5
|
"main": "dist/plugin.cjs.js",
|
|
6
6
|
"module": "dist/esm/index.js",
|
|
@@ -81,7 +81,7 @@
|
|
|
81
81
|
"rimraf": "^6.1.0",
|
|
82
82
|
"rollup": "^4.53.2",
|
|
83
83
|
"swiftlint": "^2.0.0",
|
|
84
|
-
"typescript": "^
|
|
84
|
+
"typescript": "^6.0.3"
|
|
85
85
|
},
|
|
86
86
|
"peerDependencies": {
|
|
87
87
|
"@capacitor/core": ">=8.0.0"
|