# Fast SQL Platform Setup

Load when installing `@capgo/capacitor-fast-sql` (8.x for Capacitor 8). For migrating from another SQLite plugin, use `sqlite-to-fast-sql` instead.

The plugin runs a local HTTP server on `localhost` to move query results without the Capacitor bridge, so both platforms must allow cleartext to loopback.

## iOS (`ios/App/App/Info.plist`)

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

Merge into an existing `NSAppTransportSecurity` dict; do not add a second one. This only permits loopback cleartext.

## Android

`android/app/src/main/res/xml/network_security_config.xml`:

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

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

If the app already has a network security config (e.g. for pinning), add the `domain-config` to it instead of replacing it. Avoid `android:usesCleartextTraffic="true"`; it opens cleartext to every host.

## Web fallback

Uses sql.js (WASM). By default it loads from a CDN; for offline PWA builds bundle it and call before the first connect:

```ts
import { CapgoCapacitorFastSql } from '@capgo/capacitor-fast-sql';
await CapgoCapacitorFastSql.configureWeb({ sqlJsUrl: '/assets/sql-wasm.js', wasmUrl: '/assets/sql-wasm.wasm' });
```

## API cheat sheet

```ts
import { FastSQL, KeyValueStore } from '@capgo/capacitor-fast-sql';

const db = await FastSQL.connect({ database: 'app' });           // SQLConnection
const rows = await db.query('SELECT * FROM todos WHERE done = ?', [0]);
const { rowsAffected, insertId } = await db.run('DELETE FROM todos WHERE id = ?', [id]);
await db.executeBatch([{ statement: 'INSERT ...', params: [...] }]);
await db.transaction(async (tx) => { await tx.run('...'); });

const kv = await KeyValueStore.open({ database: 'app', store: 'settings' });
await kv.set('lastSync', 1730000000);
const v = await kv.get('lastSync');
```

Options: `encrypted` + `encryptionKey` (iOS/Android; Android needs the SQLCipher dependency per plugin README), `readOnly`. Load the encryption key from secure storage, never hardcode it.

Check the installed version's `SQLBatchOperation` type in `node_modules/@capgo/capacitor-fast-sql/dist/esm/definitions.d.ts` before writing batch code.

## Migrations

Keep a `PRAGMA user_version` integer and apply ordered migration steps inside a transaction at startup:

```ts
const [{ user_version }] = await db.query('PRAGMA user_version');
if (Number(user_version) < 1) {
  await db.transaction(async (tx) => {
    await tx.run('CREATE TABLE todos (id TEXT PRIMARY KEY, text TEXT, done INTEGER, updated_at INTEGER, dirty INTEGER, deleted INTEGER DEFAULT 0)');
    await tx.run('PRAGMA user_version = 1');
  });
}
```

Live updates can ship new JS against an old on-device schema; migrations must run on every app start and be forward-only.