SQL

GitHubnpmcrates.io

Referencia de API

Plugin que proporciona una interfaz para que el frontend se comunique con bases de datos SQL a través de sqlx. Soporta los controladores SQLite, MySQL y PostgreSQL, habilitados mediante una característica de Cargo.

Plataformas Soportadas

Este plugin requiere una versión de Rust de al menos 1.77.2

Plataforma	Nivel	Notas
windows
linux
macos
android
ios

Configuración

Instala el plugin SQL para comenzar.

Automático

Usa el gestor de paquetes de tu proyecto para agregar la dependencia:

npm

npm run tauri add sql

yarn

yarn run tauri add sql

pnpm

pnpm tauri add sql

deno

deno task tauri add sql

bun

bun tauri add sql

cargo

cargo tauri add sql

Manual

1. Ejecuta el siguiente comando en la carpeta src-tauri para agregar el plugin a las dependencias del proyecto en Cargo.toml:

   cargo add tauri-plugin-sql

2. Modifica lib.rs para inicializar el plugin:

   src-tauri/src/lib.rs

   #[cfg_attr(mobile, tauri::mobile_entry_point)]
       pub fn run() {
       tauri::Builder::default()
           .plugin(tauri_plugin_sql::Builder::default().build())
           .run(tauri::generate_context!())
           .expect("error while running tauri application");
   }

3. Instala los bindings de JavaScript utilizando tu gestor de paquetes de JavaScript preferido:

   npm

   npm install @tauri-apps/plugin-sql

   yarn

   yarn add @tauri-apps/plugin-sql

   pnpm

   pnpm add @tauri-apps/plugin-sql

   deno

   deno add npm:@tauri-apps/plugin-sql

   bun

   bun add @tauri-apps/plugin-sql

Después de instalar el plugin, debes seleccionar el motor de base de datos compatible. Los motores disponibles son Sqlite, MySQL y PostgreSQL. Ejecuta el siguiente comando en la carpeta src-tauri para habilitar tu motor preferido:

SQLite

cargo add tauri-plugin-sql --features sqlite

MySQL

cargo add tauri-plugin-sql --features mysql

PostgreSQL

cargo add tauri-plugin-sql --features postgres

Uso

Todas las API del plugin están disponibles a través de los enlaces de invitado de JavaScript:

SQLite

La ruta es relativa a tauri::api::path::BaseDirectory::AppConfig.

import Database from '@tauri-apps/plugin-sql';
// when using `"withGlobalTauri": true`, you may use
// const Database = window.__TAURI__.sql;

const db = await Database.load('sqlite:test.db');
await db.execute('INSERT INTO ...');

MySQL

import Database from '@tauri-apps/plugin-sql';
// when using `"withGlobalTauri": true`, you may use
// const Database = window.__TAURI__.sql;

const db = await Database.load('mysql://user:password@host/test');
await db.execute('INSERT INTO ...');

PostgreSQL

import Database from '@tauri-apps/plugin-sql';
// when using `"withGlobalTauri": true`, you may use
// const Database = window.__TAURI__.sql;

const db = await Database.load('postgres://user:password@host/test');
await db.execute('INSERT INTO ...');

Sintaxis

Usamos sqlx como la librería subyacente y adoptamos su sintaxis de consulta.

SQLite

Usa la sintaxis “$#” al sustituir datos de consulta

const result = await db.execute(
  'INSERT into todos (id, title, status) VALUES ($1, $2, $3)',
  [todos.id, todos.title, todos.status]
);

const result = await db.execute(
  'UPDATE todos SET title = $1, status = $2 WHERE id = $3',
  [todos.title, todos.status, todos.id]
);

MySQL

Usa “?” al sustituir datos de consulta

const result = await db.execute(
  'INSERT into todos (id, title, status) VALUES (?, ?, ?)',
  [todos.id, todos.title, todos.status]
);

const result = await db.execute(
  'UPDATE todos SET title = ?, status = ? WHERE id = ?',
  [todos.title, todos.status, todos.id]
);

PostgreSQL

Usa la sintaxis “$#” al sustituir datos de consulta

const result = await db.execute(
  'INSERT into todos (id, title, status) VALUES ($1, $2, $3)',
  [todos.id, todos.title, todos.status]
);

const result = await db.execute(
  'UPDATE todos SET title = $1, status = $2 WHERE id = $3',
  [todos.title, todos.status, todos.id]
);

Migraciones

Este plugin admite migraciones de bases de datos, lo que te permite gestionar la evolución del esquema de la base de datos a lo largo del tiempo.

Definiendo migraciones

Las migraciones se definen en Rust utilizando la estructura Migration. Cada migración debe incluir un número de versión único, una descripción, el SQL a ejecutar y el tipo de migración (Up o Down).

Ejemplo de una migración:

use tauri_plugin_sql::{Migration, MigrationKind};

let migration = Migration {
    version: 1,
    description: "create_initial_tables",
    sql: "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);",
    kind: MigrationKind::Up,
};

O si quieres usar SQL desde un archivo, puedes incluirlo usando include_str!:

use tauri_plugin_sql::{Migration, MigrationKind};

let migration = Migration {
    version: 1,
    description: "create_initial_tables",
    sql: include_str!("../drizzle/0000_graceful_boomer.sql"),
    kind: MigrationKind::Up,
};

Añadiendo migraciones al Plugin Builder

Las migraciones se registran con la estructura Builder proporcionada por el plugin. Usa el método add_migrations para añadir tus migraciones al plugin para una conexión de base de datos específica.

Ejemplo de adición de migraciones:

src-tauri/src/main.rs

use tauri_plugin_sql::{Builder, Migration, MigrationKind};

fn main() {
    let migrations = vec![
        // Define your migrations here
        Migration {
            version: 1,
            description: "create_initial_tables",
            sql: "CREATE TABLE users (id INTEGER PRIMARY KEY, name TEXT);",
            kind: MigrationKind::Up,
        }
    ];

    tauri::Builder::default()
        .plugin(
            tauri_plugin_sql::Builder::default()
                .add_migrations("sqlite:mydatabase.db", migrations)
                .build(),
        )
        ...
}

Aplicando migraciones

Para aplicar las migraciones cuando se inicializa el plugin, añade la cadena de conexión al archivo tauri.conf.json:

src-tauri/tauri.conf.json

{
  "plugins": {
    "sql": {
      "preload": ["sqlite:mydatabase.db"]
    }
  }
}

Alternativamente, el load() del lado del cliente también ejecuta las migraciones para una cadena de conexión dada:

import Database from '@tauri-apps/plugin-sql';
const db = await Database.load('sqlite:mydatabase.db');

Asegúrate de que las migraciones estén definidas en el orden correcto y sean seguras de ejecutar múltiples veces.

Nota

Todas las migraciones se ejecutan dentro de una transacción, garantizando la atomicidad. Si alguna migración falla, se revierte toda la transacción, dejando la base de datos en un estado consistente.

Gestión de migraciones

• Control de versiones: Cada migración debe tener un número de versión único. Esto es crucial para garantizar que las migraciones se apliquen en el orden correcto.
• Idempotencia: Escribe las migraciones de forma que puedan volverse a ejecutar de manera segura sin causar errores ni consecuencias no deseadas.
• Pruebas: Prueba minuciosamente las migraciones para asegurarte de que funcionen como se espera y no comprometan la integridad de tu base de datos.

Permisos

De forma predeterminada, todos los comandos y alcances (scopes) potencialmente peligrosos del plugin están bloqueados y no se puede acceder a ellos. Debes modificar los permisos en tu configuración de capabilities para habilitarlos.

Consulta la Visión General de Capacidades para obtener más información y la guía paso a paso para usar permisos de plugins.

src-tauri/capabilities/default.json

{
  "permissions": [
    ...,
    "sql:default",
    "sql:allow-execute",
  ]
}

Permiso Predeterminado

Permisos por defecto

Este conjunto de permisos configura qué tipo de operaciones de base de datos están disponibles desde el plugin sql.

Permisos concedidos

Todas las operaciones relacionadas con la lectura están habilitadas. También permite cargar o cerrar una conexión.

Este conjunto de permisos predeterminado incluye lo siguiente:

• allow-close
• allow-load
• allow-select

Tabla de Permisos

Identificador	Descripción
sql:allow-close	Habilita el comando close sin ningún alcance preconfigurado.
sql:deny-close	Deniega el comando close sin ningún ámbito preconfigurado.
sql:allow-execute	Habilita el comando execute sin ningún scope preconfigurado.
sql:deny-execute	Deniega el comando execute sin ningún scope preconfigurado.
sql:allow-load	Habilita el comando load sin ningún ámbito preconfigurado.
sql:deny-load	Deniega el comando load sin ningún ámbito preconfigurado.
sql:allow-select	Habilita el comando select sin ningún ámbito preconfigurado.
sql:deny-select	Deniega el comando select sin ningún ámbito preconfigurado.