SQL

GitHubnpmcrates.io

API Reference

插件提供了一个接口，让前端可以通过 sqlx 与 SQL 数据库进行通信。它支持 SQLite、MySQL 和 PostgreSQL 驱动程序，通过 Cargo 特性来启用。

支持的平台

This plugin requires a Rust version of at least 1.77.2

Platform	Level	Notes
windows
linux
macos
android
ios

安装

安装 SQL 插件以开始使用。

自动

使用项目的包管理器添加依赖：

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

手动

1. 在 src-tauri 目录下运行以下命令，将插件添加到 Cargo.toml 的项目依赖中：

   cargo add tauri-plugin-sql

2. 修改 lib.rs 以初始化插件：

   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. 使用你偏好的 JavaScript 包管理器安装 JavaScript Guest 绑定：

   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

安装插件后，你必须选择支持的数据库引擎。 可用的引擎包括 SQLite、MySQL 和 PostgreSQL。 在 src-tauri 目录下运行以下命令以启用你偏好的引擎：

SQLite

cargo add tauri-plugin-sql --features sqlite

MySQL

cargo add tauri-plugin-sql --features mysql

PostgreSQL

cargo add tauri-plugin-sql --features postgres

用法

所有插件的 API 都可以通过 JavaScript Guest 绑定使用：

SQLite

路径相对于 tauri::api::path::BaseDirectory::AppConfig。

import Database from '@tauri-apps/plugin-sql';
// 当使用 `"withGlobalTauri": true` 时，你可以使用
// 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';
// 当使用 `"withGlobalTauri": true` 时，你可以使用
// 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';
// 当使用 `"withGlobalTauri": true` 时，你可以使用
// const Database = window.__TAURI__.sql;

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

语法

我们使用 sqlx 作为底层库并采用它们的查询语法。

SQLite

在替换查询数据时使用 “$#” 语法

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

在替换查询数据时使用 “?” 语法

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

在替换查询数据时使用 “$#” 语法

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

迁移

这个插件支持数据库迁移，允许你管理数据库模式随时间的变化。

定义迁移

迁移在 Rust 中使用 Migration 结构体定义。每个迁移都应该包含唯一的版本号、描述、要执行的 SQL 和迁移类型（向上或向下）。

迁移示例：

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

如果你想使用文件中的 SQL，可以通过 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,
};

向插件构建器添加迁移

迁移使用插件提供的 Builder 结构体注册。使用 add_migrations 方法将迁移添加到特定数据库连接的插件中。

添加迁移示例：

src-tauri/src/main.rs

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

fn main() {
    let migrations = vec![
        // 在此定义你的迁移
        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(),
        )
        ...
}

应用迁移

要在插件初始化时应用迁移，请将连接字符串添加到 tauri.conf.json 文件中：

src-tauri/tauri.conf.json

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

或者，客户端的 load() 方法也会对给定的连接字符串运行迁移：

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

确保迁移按正确的顺序定义，并且可以安全地多次运行。

注意

所有迁移都在事务中执行，确保原子性。如果任何迁移失败，整个事务将回滚，使数据库保持一致状态。

迁移管理

• 版本控制：每个迁移必须有一个唯一的版本号。这对于确保迁移按正确的顺序应用至关重要。
• 幂等性：编写迁移时，要确保它们能够安全地重新运行，而不会导致错误或意外后果。
• 测试：彻底测试迁移，确保它们按预期工作，并且不会损害数据库的完整性。

权限

默认情况下，所有潜在危险的插件命令和作用域都被阻止，无法访问。你必须在 capabilities 配置中修改权限以启用它们。

有关更多信息，请参阅权限概述以及使用插件权限的分步指南。

src-tauri/capabilities/default.json

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

Default Permission

Default Permissions

This permission set configures what kind of database operations are available from the sql plugin.

Granted Permissions

All reading related operations are enabled. Also allows to load or close a connection.

This default permission set includes the following:

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

Permission Table

Identifier	Description
sql:allow-close	Enables the close command without any pre-configured scope.
sql:deny-close	Denies the close command without any pre-configured scope.
sql:allow-execute	Enables the execute command without any pre-configured scope.
sql:deny-execute	Denies the execute command without any pre-configured scope.
sql:allow-load	Enables the load command without any pre-configured scope.
sql:deny-load	Denies the load command without any pre-configured scope.
sql:allow-select	Enables the select command without any pre-configured scope.
sql:deny-select	Denies the select command without any pre-configured scope.