Premiers pas avec Fast SQL

1. Installez le package

   npm

   npm i @capgo/capacitor-fast-sql

   pnpm

   pnpm add @capgo/capacitor-fast-sql

   yarn

   yarn add @capgo/capacitor-fast-sql

   bun

   bun add @capgo/capacitor-fast-sql

2. Synchronisation avec les projets natifs

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Configurer les plateformes

   iOS

   Autoriser l’accès au réseau local dans Info.plist :

   ios/App/App/Info.plist

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

   Android

   Ajoutez une exception en texte clair pour le trafic localhost :

   android/app/src/main/AndroidManifest.xml

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

   ###Web Installez sql.js pour le stockage Web de secours :

   npm install sql.js

Pourquoi Fast SQL ?

Fast SQL évite une sérialisation lourde des ponts en utilisant un transport HTTP local vers SQLite natif, ce qui est beaucoup plus rapide pour les jeux de résultats volumineux et les écritures de style synchronisation.

Utilisation de base

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

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

await db.execute(`
  CREATE TABLE IF NOT EXISTS users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE,
    created_at INTEGER DEFAULT (strftime('%s', 'now'))
  )
`);

await db.run('INSERT INTO users (name, email) VALUES (?, ?)', ['John', 'john@example.com']);
const users = await db.query('SELECT * FROM users');

Méthodes de connexion principales

• execute(statement, params?) -> renvoie le résultat SQL complet
• query(statement, params?) -> renvoie rows
• run(statement, params?) -> renvoie { rowsAffected, insertId }
• executeBatch(operations) -> renvoie un tableau de résultats

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

const rows = await db.query('SELECT * FROM users WHERE email LIKE ?', ['john%']);

const batch: SQLBatchOperation[] = [
  { statement: 'INSERT INTO users (name, email) VALUES (?, ?)', params: ['Alice', 'alice@acme.dev'] },
  { statement: 'INSERT INTO users (name, email) VALUES (?, ?)', params: ['Bob', 'bob@acme.dev'] },
];
await db.executeBatch(batch);

Transactions

assistant de rappel

await db.transaction(async (tx) => {
  await tx.run('UPDATE accounts SET balance = balance - 100 WHERE id = ?', [1]);
  await tx.run('UPDATE accounts SET balance = balance + 100 WHERE id = ?', [2]);
});

contrôle explicite

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

await db.beginTransaction(IsolationLevel.Serializable);
try {
  await db.run('UPDATE wallets SET points = points - 1 WHERE user_id = ?', [42]);
  await db.commit();
} catch (error) {
  await db.rollback();
  throw error;
}

Niveaux d’isolement pris en charge :

• ReadUncommitted
• ReadCommitted
• RepeatableRead
• Serializable

Données binaires (BLOB)

const imageData = new Uint8Array([0xFF, 0xD8, 0xFF, 0xE0]);
await db.run('INSERT INTO assets (name, data) VALUES (?, ?)', ['avatar', imageData]);

const rows = await db.query('SELECT data FROM assets WHERE name = ?', ['avatar']);
const retrieved = rows[0].data; // Uint8Array

Modes de cryptage et de lecture seule

const secureDb = await FastSQL.connect({
  database: 'secure_db',
  encrypted: true,
  encryptionKey: 'replace-with-a-strong-key',
});

const readOnlyDb = await FastSQL.connect({
  database: 'public_db',
  readOnly: true,
});

Sur Android, le mode chiffré utilise SQLCipher ; inclure la dépendance dans l’application build.gradle.

KeyValueStore

KeyValueStore est un wrapper pratique pour les données clé/valeur mobiles.

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

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

await kv.set('session', { token: 'abc', expiresAt: Date.now() + 3600_000 });
const session = await kv.get('session');
await kv.has('session');
await kv.keys();
await kv.remove('session');
await kv.clear();
await kv.close();

Cycle de vie de la connexion

await FastSQL.disconnect('myapp');
await FastSQL.disconnectAll();
const openDatabases = FastSQL.getOpenDatabases();
const same = FastSQL.getConnection('myapp');

Gestion des erreurs

try {
  await FastSQL.connect({ database: 'myapp' });
  await db.query('SELECT * FROM unknown_table');
} catch (error) {
  console.error('Fast SQL error:', error);
}

Modèles SQL courants

Vérifiez si la table existe

const result = await db.query(
  "SELECT name FROM sqlite_master WHERE type='table' AND name=?",
  ['users']
);

const tableExists = result.length > 0;

Obtenir le schéma de la table

const schema = await db.query('PRAGMA table_info(users)');
console.log('Columns:', schema);

Compter les lignes

const result = await db.query('SELECT COUNT(*) as count FROM users');
const count = result[0].count;

Pagination

const pageSize = 20;
const page = 1;
const offset = (page - 1) * pageSize;

const users = await db.query(
  'SELECT * FROM users ORDER BY created_at DESC LIMIT ? OFFSET ?',
  [pageSize, offset]
);

## Conseils sur les performances

1. Utilisez les transactions pour plusieurs opérations - beaucoup plus rapidement que les validations individuelles
2. Utilisez les opérations par lots pour les insertions en masse - plus efficaces que les boucles
3. Créer des index sur les colonnes fréquemment interrogées
4. Utiliser les instructions préparées avec des paramètres (?) - empêche l’injection SQL et améliore les performances
5. Utilisez directement le protocole HTTP pour les très grands ensembles de résultats
6. Fermer les connexions lorsque vous ne vous en servez pas pour libérer des ressources

Prochaines étapes

Consultez le tutoriel complet pour connaître les modèles avancés, notamment :

• Architecture des services de base de données
• Systèmes migratoires
• Synchroniser les moteurs
• Requêtes et jointures complexes
• Optimisation des performances

Documentation connexe

• Migrer depuis Ionic Secure Storage
• Solution de migration de plugins d’entreprise Ionic