SQL

GitHub npm crates.io

API 参考

此插件提供了一个接口，用于前端通过 sqlx 与 SQL 数据库进行通信。它支持 SQLite、MySQL 和 PostgreSQL 驱动，并通过 Cargo 功能启用。

支持的平台

此插件需要 Rust 版本至少为 **1.77.2**

平台	级别	备注
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 访客绑定

   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 客户端绑定提供。

SQLite

路径是相对于 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 ...');

语法

我们使用 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 以及迁移类型（Up 或 Down）。

迁移示例

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![
        // 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(),
        )
        ...
}

应用迁移

要在插件初始化时应用迁移，请将连接字符串添加到 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",
  ]
}

默认权限

默认权限

此权限集配置了 SQL 插件可用的数据库操作类型。

已授予权限

所有读取相关操作都已启用。还允许加载或关闭连接。

此默认权限集包括以下内容

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

权限表

标识符	描述
sql:allow-close	启用 close 命令，不带任何预配置范围。
sql:deny-close	拒绝 close 命令，不带任何预配置范围。
sql:allow-execute	启用 execute 命令，不带任何预配置范围。
sql:deny-execute	拒绝 execute 命令，不带任何预配置范围。
sql:allow-load	启用 load 命令，不带任何预配置范围。
sql:deny-load	拒绝 load 命令，不带任何预配置范围。
sql:allow-select	启用 select 命令，不带任何预配置范围。
sql:deny-select	拒绝 select 命令，不带任何预配置范围。