Comenzando con SQL rápido

1. Instalar el paquete

   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. Sincronización con proyectos nativos

   npm

   npx cap sync

   pnpm

   pnpm cap sync

   yarn

   yarn cap sync

   bun

   bunx cap sync

3. Configurar plataformas

   iOS

   Permitir el acceso a la red local en Info.plist:

   ios/App/App/Info.plist

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

   Android

   Agregue una excepción de texto sin cifrar para el tráfico de host local:

   android/app/src/main/AndroidManifest.xml

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

   Web

   Instale sql.js como respaldo de almacenamiento web:

   npm install sql.js

¿Por qué SQL rápido?

Fast SQL avoids heavy bridge serialization by using a local HTTP transport to native SQLite, which is much faster for large result sets and sync-style writes.

Uso básico

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étodos de conexión principales

• execute(statement, params?) -> devuelve el resultado SQL completo
• query(statement, params?) -> devuelve rows
• run(statement, params?) -> devuelve { rowsAffected, insertId }
• executeBatch(operations) -> devuelve una serie de resultados

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);

Transacciones

ayudante de devolución de llamada

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]);
});

control explícito

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;
}

Niveles de aislamiento admitidos:

• ReadUncommitted
• ReadCommitted
• RepeatableRead
• Serializable

Datos binarios (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

Cifrado y modos de solo lectura

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,
});

En Android, el modo cifrado utiliza SQLCipher; incluir dependencia en la aplicación build.gradle.

Almacén de valores clave

KeyValueStore es un contenedor conveniente para datos de clave/valor móviles.

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();

Ciclo de vida de la conexión

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

Manejo de errores

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

Patrones SQL comunes

Comprobar si existe la tabla

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

const tableExists = result.length > 0;

Obtener esquema de tabla

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

Contar filas

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

Paginación

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]
);

Consejos de rendimiento

1. Utilice Transacciones para operaciones múltiples: significativamente más rápido que las confirmaciones individuales
2. Utilice operaciones por lotes para inserciones masivas: más eficientes que los bucles
3. Crear índices en columnas consultadas con frecuencia
4. Utilice declaraciones preparadas con parámetros (?): evita la inyección de SQL y mejora el rendimiento
5. Utilice el protocolo HTTP directamente para conjuntos de resultados muy grandes
6. Cerrar conexiones cuando no esté en uso para liberar recursos

Próximos pasos

Consulte el tutorial completo para conocer patrones avanzados que incluyen:

• Arquitectura del servicio de base de datos.
• Sistemas de migración
• Sincronizar motores
• Consultas complejas y uniones.
• Optimización del rendimiento

Documentación relacionada

• Migrar desde Ionic Secure Storage
• Solución de migración de complementos empresariales de Ionic