Tauri 中的 SQLite 数据库操作详解 – wiki基地

作者： /

拥抱本地持久化：Tauri 应用中的 SQLite 数据库操作深度解析

在现代桌面应用开发中，数据持久化是不可或缺的一环。无论是存储用户偏好、缓存离线数据，还是处理核心业务逻辑所需的数据，选择一个合适的本地数据库解决方案至关重要。对于使用 Tauri 构建跨平台桌面应用的开发者来说，SQLite 无疑是一个极具吸引力的选择。

SQLite 是一个轻量级、无服务器、自包含、高可靠的事务性 SQL 数据库引擎。它以文件形式存储数据，无需独立的数据库服务器进程，这使得它非常适合嵌入到桌面应用程序中。结合 Tauri 利用 Rust 的强大能力和 Web 技术的灵活性，使用 SQLite 能够轻松实现高效、可靠的本地数据管理。

本文将深入探讨如何在 Tauri 应用中集成和操作 SQLite 数据库。我们将从环境搭建开始，逐步讲解数据库的创建、基本的 CRUD（创建、读取、更新、删除）操作、高级特性如预处理语句和事务，以及如何在 Rust 后端和 Web 前端之间无缝地进行数据交互。

文章目录

  1. 引言：Tauri 与 SQLite 的契合

    • Tauri 应用的架构特点
    • 为什么选择 SQLite 作为本地数据库
    • 本文将涵盖的内容

  2. 环境准备：集成 Tauri SQL 插件

    • Rust 后端配置 (Cargo.toml, main.rs, tauri.conf.json)
    • 前端配置 (package.json)

  3. 数据库连接与初始化

    • 理解数据库路径
    • 使用 Tauri 的路径 API
    • 连接数据库实例 (Database::open)

  4. Schema 管理：创建表结构

    • 执行 SQL 语句 (execute)
    • 示例：创建一个简单的用户表

  5. 基本数据操作 (CRUD)

    • 创建 (Create)：插入数据 (execute)
      • 单条插入
      • 安全地使用参数绑定
    • 读取 (Read)：查询数据 (select)
      • 获取所有数据
      • 根据条件过滤 (WHERE)
      • 排序 (ORDER BY)
      • 限制结果数量 (LIMIT, OFFSET)
      • 处理查询结果的数据类型映射
    • 更新 (Update)：修改数据 (execute)
      • 根据条件更新
    • 删除 (Delete)：移除数据 (execute)
      • 根据条件删除

  6. 高级数据库特性

    • 预处理语句 (Prepared Statements): 提高安全性与性能
      • 为什么需要预处理语句
      • 使用参数绑定防止 SQL 注入
      • 重复执行同一语句的效率提升
    • 事务 (Transactions): 保证操作的原子性
      • ACID 特性简介
      • 开启、提交、回滚事务 (begin, commit, rollback)
      • 示例：原子性地完成多步操作
    • 数据库迁移 (Migrations): 管理 Schema 变更
      • 为什么需要迁移
      • 使用 tauri-plugin-sql 的迁移功能 (add_migration, run_migrations)
      • 编写迁移脚本

  7. 前端与后端交互：通过 Tauri Commands

    • 设计 Rust 命令 (#[tauri::command])
    • 在命令中执行数据库操作
    • 从 JavaScript/TypeScript 调用 Rust 命令 (invoke)
    • 传递参数与处理返回值
    • 前端数据展示与交互示例

  8. 错误处理

    • Rust 中的 Result
    • 前端 invoke 调用中的错误捕获
    • 处理常见的数据库错误

  9. 最佳实践与注意事项

    • 数据库文件存放位置建议
    • 异步操作的重要性
    • 性能优化（索引、查询优化）
    • 数据备份与恢复（简要提及）

  10. 总结

1. 引言：Tauri 与 SQLite 的契合

Tauri 是一个用于构建跨平台二进制文件的框架，它允许开发者结合任何编译到 WRY（一个 WebView 抽象层）的编译型语言（如 Rust）与任何前端框架（如 React, Vue, Angular, Svelte）来创建桌面应用。Rust 负责处理耗时、敏感或需要访问操作系统底层 API 的任务，而 Web 前端则负责用户界面。

在这种架构下，应用程序通常需要在本地存储数据。SQLite 的特性与 Tauri 的需求高度契合：

  • 轻量级、无需服务器： SQLite 数据库就是一个文件，易于部署和管理，不需要用户安装额外的数据库软件。这非常适合作为应用的一部分分发。
  • 高性能： 对于大多数桌面应用的本地数据访问需求，SQLite 提供了足够的性能。
  • 可靠性 (ACID)： SQLite 支持事务，确保数据操作的原子性、一致性、隔离性和持久性，即使在应用崩溃或断电的情况下也能保证数据完整性。
  • 易于集成： Rust 生态系统提供了优秀的 SQLite 驱动和高级抽象库，使得在 Tauri 的 Rust 后端集成 SQLite 变得简单。
  • 跨平台： SQLite 本身是跨平台的，其数据库文件格式在不同操作系统上兼容（尽管需要注意文件路径的兼容性）。

因此，SQLite 是 Tauri 应用中实现本地数据持久化的一个非常自然且强大的选择。

本文将围绕 tauri-plugin-sql 这个官方推荐的插件展开，它封装了底层 Rust SQLite 驱动，并提供了方便的 API 供 Tauri 命令使用。

2. 环境准备：集成 Tauri SQL 插件

要在 Tauri 应用中使用 SQLite，我们需要在 Rust 后端和 JavaScript/TypeScript 前端都添加相应的依赖并进行配置。

Rust 后端配置

首先，在 Tauri 项目的根目录下的 Cargo.toml 文件中，找到 dependencies 部分，添加 tauri-plugin-sql 依赖。请查阅插件的最新版本信息进行添加：

“`toml

Cargo.toml

[dependencies]
tauri = { version = “…”, features = […] }

添加 sql 插件依赖

tauri-plugin-sql = { git = “https://github.com/tauri-apps/plugins-authority”, branch = “v2” } # 使用 v2 分支或其他稳定分支

其他依赖…

“`

注意： tauri-plugin-sql 插件当前（v2）依赖于 Tauri 2.x 版本。如果你的项目使用 Tauri 1.x 版本，可能需要查找兼容 1.x 的插件版本或使用底层库如 rusqlite 或 sqlx 并手动集成到命令中。本文主要基于 tauri-plugin-sql 的 v2 版本进行讲解。

接下来，在你的 Tauri 项目的 src/main.rs 文件中，需要初始化并注册这个插件。找到构建 Tauri App 的地方（通常在 tauri::Builder::default() 后面）：

“`rust
// src/main.rs

fn main() {
tauri::Builder::default()
// 添加并配置 sql 插件
.plugin(tauri_plugin_sql::Builder::default().build())
// 添加你的自定义命令（如果需要，数据库操作将在这些命令中完成）
// .invoke_handler(tauri::generate_handler![your_command_functions])
.run(tauri::generate_context!())
.expect(“error while running tauri application”);
}
“`

最后，在 src-tauri/tauri.conf.json 文件中，需要在 plugins 部分启用并配置 sql 插件。你可以指定数据库文件的存放位置等配置。一个常见的做法是使用 Tauri 提供的特殊协议 sqlite: 来指定路径。例如，sqlite:path/to/your/database.db 会在应用的数据目录下创建一个名为 your/database.db 的数据库文件。

“`json
// src-tauri/tauri.conf.json

{
“plugins”: {
“sql”: {
“default”: “sqlite:path/to/your/app.db” // 配置默认数据库路径
// 可以在这里配置多个数据库连接，使用不同的名称
// “another_db”: “sqlite:other/data.sqlite”
}
}
// 其他配置…
}
“`

这里的 "sqlite:path/to/your/app.db" 是一个相对路径，tauri-plugin-sql 会解析这个路径，通常会将其放在应用的特定数据目录下（例如 AppData on Windows, Library/Application Support on macOS, ~/.config on Linux），具体位置由 Tauri 决定并是跨平台兼容的。

前端配置

在前端项目中，你需要安装 tauri-plugin-sql 对应的 JavaScript/TypeScript 客户端库。打开终端，在你的前端项目根目录下运行：

“`bash

使用 npm

npm install @tauri-apps/plugin-sql

或使用 yarn

yarn add @tauri-apps/plugin-sql

或使用 pnpm

pnpm add @tauri-apps/plugin-sql
“`

这个库提供了从前端调用 Rust 后端 SQL 插件 API 的接口。

3. 数据库连接与初始化

在 Rust 后端，当你使用 tauri-plugin-sql 插件并配置了 default 路径后，插件会在应用启动时自动处理数据库的打开或创建。你可以通过插件提供的 API 获取数据库实例的引用。

理解数据库路径

SQLite 数据库的核心是一个文件。在 Tauri 应用中，为了确保跨平台兼容性并遵循操作系统规范，数据库文件通常应该存放在应用的数据目录中，而不是应用的可执行文件旁边。

tauri-plugin-sql 使用 sqlite: 前缀来标识 SQLite 数据库路径，并会自动将其解析到合适的用户数据目录。例如，sqlite:app_data/myapp.db 可能会被解析为 C:\Users\YourUser\AppData\Roaming\com.yourcompany.yourapp\app_data\myapp.db (Windows) 或 /Users/YourUser/Library/Application Support/com.yourcompany.yourapp/app_data/myapp.db (macOS)。

使用 Tauri 的路径 API

虽然插件会自动解析配置文件中的路径，但在 Rust 命令中需要动态获取路径或操作文件时，可以使用 Tauri 内置的 path 插件来获取标准目录路径：

“`rust
// 引入路径插件
use tauri_plugin_path::PathExt;

// 在某个命令函数中

[tauri::command]

async fn get_db_path(app_handle: tauri::AppHandle) -> Result {
// 获取应用数据目录
let app_data_dir = app_handle.path().app_data_dir().map_err(|e| e.to_string())?;
// 构造完整的数据库文件路径（如果不是使用插件的默认路径方式）
// let db_file_path = app_data_dir.join(“my_custom_db.sqlite”);
// Ok(db_file_path.to_string_lossy().into_owned())

// 如果使用插件的默认配置，你通常不需要在这里手动构造文件路径
// 而是通过插件 API 获取数据库连接或执行操作
Ok("Database initialization handled by plugin configuration.".into())

}
“`

这个例子只是说明如何获取路径，实际使用 tauri-plugin-sql 时，你通常直接通过插件 API 获取数据库连接。

连接数据库实例 (Database::open)

虽然插件在启动时处理默认数据库的打开，但如果你需要在 Rust 代码中直接获取 Database 实例来执行操作（例如在命令函数中），你可以通过 Tauri AppHandle 或 Window 获取插件的状态。然而，tauri-plugin-sql 通常提供了一种更直接的方式：通过注入 Database 实例到命令函数参数中。

要使用这种方式，你需要在你的 Rust 命令函数签名中添加一个类型为 State<'_, tauri_plugin_sql::Database> 的参数。这个参数会由 Tauri 自动注入，提供对数据库实例的访问。

“`rust
// src/main.rs (或其他包含命令的模块)

use tauri::State;
use tauri_plugin_sql::Database; // 引入 Database 类型

// 示例命令函数，接受数据库状态参数

[tauri::command]

async fn create_user_table(db: State<‘_, Database>) -> Result<(), String> {
// 在这里使用 db 实例执行数据库操作
// 例如：db.execute(“CREATE TABLE IF NOT EXISTS users (id INTEGER PRIMARY KEY, name TEXT)”, &[]).await.map_err(|e| e.to_string())?;
println!(“Database instance received in command.”);
Ok(())
}

// 别忘了在 main 函数中将这个命令加入到 invoke_handler
/
fn main() {
tauri::Builder::default()
.plugin(tauri_plugin_sql::Builder::default().build())
.invoke_handler(tauri::generate_handler![create_user_table]) // 添加你的命令
.run(tauri::generate_context!())
.expect(“error while running tauri application”);
}
/
“`

通过 State<'_, Database> 注入，你可以在任何需要执行数据库操作的命令函数中方便地访问到数据库连接实例。

4. Schema 管理：创建表结构

数据库创建后，通常第一步是定义数据结构，即创建表。这通过执行 CREATE TABLE 语句完成。在应用首次运行时执行 schema 创建是一个常见模式。

执行 SQL 语句 (execute)

tauri-plugin-sql 插件的 Database 实例提供了 execute 方法来执行不返回结果的 SQL 语句，例如 CREATE TABLE, INSERT, UPDATE, DELETE, DROP TABLE 等。

“`rust
// 在上面定义的 create_user_table 命令函数中：

[tauri::command]

async fn create_user_table(db: State<‘_, Database>) -> Result<(), String> {
let create_table_sql = r#”
CREATE TABLE IF NOT EXISTS users (
id INTEGER PRIMARY KEY AUTOINCREMENT,
name TEXT NOT NULL,
email TEXT UNIQUE,
created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);
“#;

db.execute(create_table_sql, &[]) // execute 方法的第二个参数是参数绑定，这里没有参数，传入空切片
    .await
    .map_err(|e| e.to_string())?;

println!("'users' table created or already exists.");
Ok(())

}
“`

这里的 CREATE TABLE IF NOT EXISTS 语句是惯用的 SQLite 语法，它会在表不存在时创建，存在时则跳过，这避免了重复创建表的错误。AUTOINCREMENT 会自动为 id 字段生成唯一的递增整数。

你可以在应用启动时，或者在某个初始化命令中调用这个 create_user_table 命令，确保数据库 Schema 存在。

5. 基本数据操作 (CRUD)

现在表已经创建，我们可以进行数据的增删改查操作了。

创建 (Create)：插入数据 (execute)

使用 INSERT INTO 语句向表中添加新行。同样使用 execute 方法。

“`rust

[tauri::command]

async fn insert_user(db: State<‘_, Database>, name: String, email: String) -> Result {
let insert_sql = “INSERT INTO users (name, email) VALUES (?, ?)”;
// 使用参数绑定 (? 或 :name, $name, @name) 传递值
// tauri-plugin-sql 支持位置参数 (?) 和命名参数 (:name)
// 参数必须放入一个 Vec 中
let params = vec![
tauri_plugin_sql::Value::Text(name),
tauri_plugin_sql::Value::Text(email),
];

// execute 方法返回插入、更新或删除的行数（或者 -1 如果不支持）
// 对于 INSERT，它通常返回受影响的行数 (1)，但我们更关心最后插入的行的 ID
// 插件提供了 last_insert_row_id() 方法，但在 execute 后获取需要额外逻辑
// 更推荐使用 select 语句结合 LAST_INSERT_ROWID() 或通过合适的 API（如果插件提供）
// 插件的 execute 方法返回值是一个 usize，表示影响的行数
// 为了获取 last_insert_row_id，我们可以执行一个单独的 SELECT 查询
// 或者查看插件文档是否有直接获取 ID 的方法。
// 经查阅，插件的 execute 方法返回值是 Result<usize, Error>.
// 要获取 ID，可以执行 SELECT last_insert_rowid(); 作为单独的查询。
// 或者，如果插件提供更高层次的 API，例如 query_and_fetch_one。
// 我们先使用 execute，然后演示如何获取 ID。

db.execute(insert_sql, params.as_slice())
    .await
    .map_err(|e| e.to_string())?;

// 获取最后插入行的 ID
let last_id_sql = "SELECT last_insert_rowid()";
let result = db.select(last_id_sql, &[]).await.map_err(|e| e.to_string())?;

// result 是一个 Vec<tauri_plugin_sql::Row>
// 我们期望只有一行，一列 (last_insert_rowid())
if let Some(row) = result.into_iter().next() {
    if let Some(tauri_plugin_sql::Value::Integer(id)) = row.get(0) {
        Ok(*id)
    } else {
        Err("Could not retrieve last insert row id as Integer.".to_string())
    }
} else {
    Err("Could not retrieve last insert row id.".to_string())
}

}
“`

关于参数绑定： 使用参数绑定 (? 或 :param) 而不是直接将值拼接到 SQL 字符串中是至关重要的。这可以有效地防止 SQL 注入攻击，并让数据库更有效地缓存执行计划，提高性能。tauri-plugin-sql 要求参数以 &[tauri_plugin_sql::Value] 切片的形式提供。tauri_plugin_sql::Value 枚举覆盖了常见的 SQL 数据类型。

读取 (Read)：查询数据 (select)

使用 SELECT 语句从表中检索数据。tauri-plugin-sql 插件提供了 select 方法来执行返回结果集的查询。

“`rust

[tauri::command]

async fn get_all_users(db: State<‘_, Database>) -> Result, String> {
// 为了方便从数据库行映射到 Rust struct 和前端类型，我们定义一个 User struct
#[derive(Debug, serde::Serialize, serde::Deserialize)]
struct User {
id: i64,
name: String,
email: String,
created_at: String, // 或者 chrono::NaiveDateTime if using chrono
}

let select_sql = "SELECT id, name, email, created_at FROM users";
let result = db.select(select_sql, &[]).await.map_err(|e| e.to_string())?;

// 结果是一个 Vec<tauri_plugin_sql::Row>
// 我们需要将每一行映射到 User struct
let users: Vec<User> = result.into_iter().map(|row| {
    User {
        // 获取列值，使用 get(index) 或 get("column_name")
        // 需要处理 Option 和 Value 类型转换
        id: row.get(0).and_then(|v| v.as_integer()).unwrap_or_default(),
        name: row.get(1).and_then(|v| v.as_text()).unwrap_or_default().into(),
        email: row.get(2).and_then(|v| v.as_text()).unwrap_or_default().into(),
        created_at: row.get(3).and_then(|v| v.as_text()).unwrap_or_default().into(), // SQLite stores TIMESTAMP as TEXT or REAL typically
    }
}).collect();

Ok(users)

}

[tauri::command]

async fn get_user_by_id(db: State<‘_, Database>, user_id: i64) -> Result, String> {
#[derive(Debug, serde::Serialize, serde::Deserialize)]
struct User {
id: i64,
name: String,
email: String,
created_at: String,
}

let select_sql = "SELECT id, name, email, created_at FROM users WHERE id = ?";
let params = vec![tauri_plugin_sql::Value::Integer(user_id)];

let result = db.select(select_sql, params.as_slice()).await.map_err(|e| e.to_string())?;

// result 可能是空（没找到）或包含一行
if let Some(row) = result.into_iter().next() {
     let user = User {
        id: row.get(0).and_then(|v| v.as_integer()).unwrap_or_default(),
        name: row.get(1).and_then(|v| v.as_text()).unwrap_or_default().into(),
        email: row.get(2).and_then(|v| v.as_text()).unwrap_or_default().into(),
        created_at: row.get(3).and_then(|v| v.as_text()).unwrap_or_default().into(),
    };
    Ok(Some(user))
} else {
    Ok(None) // 没有找到匹配的用户
}

}
“`

select 方法返回 Result<Vec<Row>, Error>。Row 类型代表数据库中的一行数据，你可以通过索引或列名访问其中的列值。列值是 tauri_plugin_sql::Value 枚举类型，你需要根据实际存储的数据类型使用相应的方法（如 as_integer(), as_text(), as_real(), as_blob()) 进行类型转换。需要注意的是，这些方法返回 Option<&T>，表示值可能为 NULL 或类型不匹配，所以需要进行错误处理（如 unwrap_or_default() 或链式 and_then）。

为了将数据库结果方便地传回前端，我们通常将 Row 映射到可序列化 (using serde::Serialize) 的 Rust 结构体。

更新 (Update)：修改数据 (execute)

使用 UPDATE 语句修改现有数据。同样使用 execute 方法。

“`rust

[tauri::command]

async fn update_user_email(db: State<‘_, Database>, user_id: i64, new_email: String) -> Result {
let update_sql = “UPDATE users SET email = ? WHERE id = ?”;
let params = vec![
tauri_plugin_sql::Value::Text(new_email),
tauri_plugin_sql::Value::Integer(user_id),
];

db.execute(update_sql, params.as_slice())
    .await
    .map_err(|e| e.to_string())

}
“`

execute 返回受影响的行数 (usize)。

删除 (Delete)：移除数据 (execute)

使用 DELETE FROM 语句删除数据。同样使用 execute 方法。

“`rust

[tauri::command]

async fn delete_user(db: State<‘_, Database>, user_id: i64) -> Result {
let delete_sql = “DELETE FROM users WHERE id = ?”;
let params = vec![tauri_plugin_sql::Value::Integer(user_id)];

db.execute(delete_sql, params.as_slice())
    .await
    .map_err(|e| e.to_string())

}
“`

execute 返回受影响的行数 (usize)。

6. 高级数据库特性

掌握了基本的 CRUD 操作后，我们可以进一步利用 SQLite 的高级特性来提升应用的健壮性和性能。

预处理语句 (Prepared Statements)

预处理语句是一种将 SQL 命令与它的参数分离的技术。它提供两个主要优势：

  1. 安全性： 最重要的是防止 SQL 注入。通过参数绑定传递的值不会被解释为 SQL 代码的一部分，即使值中包含恶意 SQL 片段，也不会被执行。
  2. 性能： 对于重复执行的语句（例如在一个循环中插入多条数据），数据库只需解析和规划一次查询，后续执行时只需绑定新的参数，这比每次都重新解析整个 SQL 字符串更高效。

tauri-plugin-sql 的 execute 和 select 方法都支持参数绑定 (?, :name)，这实际上就是在内部使用了预处理语句。上面基本操作中的示例已经演示了如何使用参数绑定，这是推荐的做法。

永远不要通过字符串格式化直接将用户输入或其他动态数据拼接到 SQL 语句中，例如：

rust
// 这是一个非常不安全且效率低下的做法！！！
// let dangerous_sql = format!("SELECT * FROM users WHERE name = '{}'", user_input_name);
// db.select(&dangerous_sql, &[]).await;

应始终使用参数绑定：

rust
// 安全且推荐的做法
let safe_sql = "SELECT * FROM users WHERE name = ?";
let params = vec![tauri_plugin_sql::Value::Text(user_input_name)];
db.select(safe_sql, params.as_slice()).await;

事务 (Transactions)

事务是一组数据库操作，它们被视为单个工作单元。事务具有 ACID 特性：

  • 原子性 (Atomicity): 事务中的所有操作要么全部成功，要么全部失败回滚，不会出现部分成功的情况。
  • 一致性 (Consistency): 事务将数据库从一个一致状态转换到另一个一致状态。
  • 隔离性 (Isolation): 并发执行的事务之间互不影响。
  • 持久性 (Durability): 一旦事务提交，其更改就是永久的，即使系统故障也不会丢失。

在需要执行多个相互依赖的数据库操作时，应该使用事务。例如，从一个账户扣钱并给另一个账户加钱的操作，必须在同一个事务中，确保两步都成功或都失败。

tauri-plugin-sql 的 Database 实例提供了 begin, commit, rollback 方法来控制事务：

“`rust

[tauri::command]

async fn transfer_funds(db: State<‘_, Database>, from_account_id: i64, to_account_id: i64, amount: f64) -> Result<(), String> {
// 开启事务
db.begin().await.map_err(|e| e.to_string())?;

let result: Result<(), String> = (async move {
    // 1. 从来源账户扣除金额
    let deduct_sql = "UPDATE accounts SET balance = balance - ? WHERE id = ?";
    let deduct_params = vec![
        tauri_plugin_sql::Value::Real(amount),
        tauri_plugin_sql::Value::Integer(from_account_id),
    ];
    let affected_rows = db.execute(deduct_sql, deduct_params.as_slice()).await.map_err(|e| e.to_string())?;
    if affected_rows == 0 {
        return Err("Source account not found or insufficient funds?".to_string()); // 简单的错误检查
    }

    // 2. 向目标账户增加金额
    let add_sql = "UPDATE accounts SET balance = balance + ? WHERE id = ?";
    let add_params = vec![
        tauri_plugin_sql::Value::Real(amount),
        tauri_plugin_sql::Value::Integer(to_account_id),
    ];
    let affected_rows = db.execute(add_sql, add_params.as_slice()).await.map_err(|e| e.to_string())?;
     if affected_rows == 0 {
        return Err("Target account not found?".to_string()); // 简单的错误检查
    }

    // 如果所有操作都成功，返回 Ok(())
    Ok(())
}).await; // 使用 async move 块捕获 db 变量

// 根据操作结果决定提交或回滚
match result {
    Ok(_) => {
        // 提交事务
        db.commit().await.map_err(|e| e.to_string())?;
        println!("Transaction committed successfully.");
        Ok(())
    },
    Err(e) => {
        // 回滚事务
        let _ = db.rollback().await; // 忽略回滚错误，因为我们已经在处理原始错误
        eprintln!("Transaction rolled back due to error: {}", e);
        Err(e) // 返回原始错误
    }
}

}
“`

在这个例子中，我们先调用 db.begin() 开始一个事务。然后执行扣款和加款两个操作。如果在任何一步发生错误（例如 SQL 错误，或者我们手动检查到账户不存在/余额不足并返回 Err），我们捕获这个错误，调用 db.rollback() 撤销事务中的所有更改，并向上返回错误。只有当所有操作都成功执行后，我们才调用 db.commit() 使更改永久生效。

数据库迁移 (Migrations)

随着应用功能的迭代，数据库 Schema 往往需要变更：添加新表、修改现有表结构（添加/删除列、修改约束）、创建索引等。数据库迁移是一种自动化管理这些 Schema 变更过程的方式，确保数据库结构从一个版本安全地升级到另一个版本。

tauri-plugin-sql 插件内置了对数据库迁移的支持。你需要定义一系列迁移脚本（通常是 SQL 文件或字符串），每个脚本代表一个版本变更。插件会在应用启动时检查当前的数据库版本，并按顺序执行所有未执行的迁移脚本，将数据库升级到最新版本。

  1. 定义迁移脚本:
    在你的 Tauri 项目中创建一个目录来存放迁移脚本，例如 src-tauri/migrations。每个迁移脚本通常以版本号和描述命名，例如 1_create_users_table.sql, 2_add_status_to_users.sql。

    src-tauri/migrations/1_create_users_table.sql:

    sql
    -- 1_create_users_table.sql
    CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
    );

    src-tauri/migrations/2_add_status_to_users.sql:

    sql
    -- 2_add_status_to_users.sql
    ALTER TABLE users ADD COLUMN status TEXT DEFAULT 'active';
    -- 或者可以插入一些默认数据等
    -- INSERT INTO settings (key, value) VALUES ('db_version', '2');

  2. 在 Rust 中添加迁移:
    在 main.rs 中构建 SQL 插件时，使用 add_migration 方法添加你的迁移脚本。迁移脚本内容可以直接是字符串，或者从文件中读取。

    “`rust
    // src/main.rs

    fn main() {
    tauri::Builder::default()
    .plugin(
    tauri_plugin_sql::Builder::default()
    .add_migration(
    // 唯一的版本号
    1,
    // 迁移脚本的 SQL 内容
    r#”
    CREATE TABLE users (
    id INTEGER PRIMARY KEY AUTOINCREMENT,
    name TEXT NOT NULL,
    email TEXT UNIQUE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
    );
    “#
    )
    .add_migration(
    2,
    r#”
    ALTER TABLE users ADD COLUMN status TEXT DEFAULT ‘active’;
    “#
    )
    // 可以根据需要添加更多迁移
    .build()
    )
    // … 其他配置和命令
    .run(tauri::generate_context!())
    .expect(“error while running tauri application”);
    }
    “`

  3. 运行迁移:
    当应用启动时，tauri-plugin-sql 插件会自动检查数据库中是否有专门的迁移记录表（通常是 _migrations 或类似名称），比较记录的版本和你在代码中添加的迁移版本。然后，它会自动按版本顺序执行所有未执行的迁移脚本。

    你不需要显式地调用 run_migrations 方法（除非你想在特定时机手动触发）。插件的默认行为是在数据库连接后自动运行迁移。

迁移功能是管理数据库 Schema 演进的强大工具，强烈建议在任何实际应用中使用它。

7. 前端与后端交互：通过 Tauri Commands

Tauri 的核心交互模式是通过 Commands。前端（JavaScript/TypeScript）通过 invoke 调用定义在 Rust 后端的 #[tauri::command] 函数。数据库操作应该封装在这些 Rust 命令中，而不是直接从前端尝试访问数据库文件（这是不可能的，也是不安全的）。

设计 Rust 命令

如前面示例所示，数据库操作都放在了标记为 #[tauri::command] 的异步函数中。这些函数接受前端传递的参数（通过函数参数定义），并返回一个 Result<T, String>，其中 T 是要返回给前端的数据类型（需要实现 serde::Serialize），String 是错误信息。

确保你的命令函数接受 State<'_, Database> 参数来访问数据库实例。

从 JavaScript/TypeScript 调用 Rust 命令 (invoke)

在前端代码中，使用 @tauri-apps/api/core（Tauri v2）或 @tauri-apps/api（Tauri v1）中的 invoke 函数来调用 Rust 命令。

首先，导入 invoke 函数：

“`typescript
// src/main.ts 或某个组件文件

import { invoke } from ‘@tauri-apps/api/core’; // For Tauri v2
// import { invoke } from ‘@tauri-apps/api’; // For Tauri v1
“`

然后，调用你的 Rust 命令，将命令名称作为第一个参数，将传递给 Rust 函数的参数作为第二个对象参数：

“`typescript
// 假设你在 Rust 中定义了 insert_user 命令
// #[tauri::command] async fn insert_user(db: State<‘_, Database>, name: String, email: String) -> Result

async function addNewUser(name: string, email: string) {
try {
// invoke 的第一个参数是 Rust 命令的字符串名称
// 第二个参数是一个对象，键是 Rust 函数参数名，值是对应参数的值
const userId = await invoke(‘insert_user’, { name: name, email: email });
console.log(‘New user inserted with ID:’, userId);
// 可以在这里更新 UI 或执行其他操作
} catch (error) {
console.error(‘Failed to insert user:’, error);
// 处理错误，例如向用户显示错误消息
}
}

// 假设你在 Rust 中定义了 get_all_users 命令
// #[tauri::command] async fn get_all_users(db: State<‘_, Database>) -> Result, String>
// User struct 在 Rust 中定义并实现了 Serialize

interface User {
id: number;
name: string;
email: string;
created_at: string;
}

async function fetchAllUsers() {
try {
const users: User[] = await invoke(‘get_all_users’);
console.log(‘Fetched users:’, users);
// 可以在这里将用户数据显示在列表中
} catch (error) {
console.error(‘Failed to fetch users:’, error);
}
}

// 示例调用
// addNewUser(‘Alice’, ‘[email protected]’);
// fetchAllUsers();
“`

invoke 是一个异步函数，它返回一个 Promise。如果 Rust 命令返回 Ok(value)，Promise 会解析为 value (经过 Tauri 序列化和反序列化)。如果 Rust 命令返回 Err(error_message)，Promise 会被拒绝，拒绝的原因是 error_message。

通过这种方式，前端与数据库的交互是安全的（绕过直接文件访问），并利用了 Rust 的能力（类型安全、错误处理、性能）。

8. 错误处理

健壮的应用必须妥善处理数据库操作可能发生的错误。数据库错误可能包括：

  • SQL 语法错误
  • 违反约束（唯一性、非空、外键等）
  • 文件读写问题
  • 事务死锁
  • 迁移失败

在 Rust 中，数据库操作通常返回 Result<T, E>。tauri-plugin-sql 的方法也遵循这个模式，返回 Result<Something, tauri_plugin_sql::Error>。我们通常将这个 tauri_plugin_sql::Error 转换为 String 或自定义的错误类型，然后在 #[tauri::command] 函数中返回 Result<T, String>。

“`rust
// 示例：insert_user 命令中的错误处理

[tauri::command]

async fn insert_user(db: State<‘_, Database>, name: String, email: String) -> Result {
let insert_sql = “INSERT INTO users (name, email) VALUES (?, ?)”;
let params = vec![
tauri_plugin_sql::Value::Text(name),
tauri_plugin_sql::Value::Text(email),
];

// 使用 ? 运算符将 Result<usize, Error> 转换为 Result<usize, String>
db.execute(insert_sql, params.as_slice())
    .await
    .map_err(|e| e.to_string())?; // 如果 execute 失败，这里的 ? 会返回 Err(e.to_string())

// 获取最后插入行的 ID... （省略上面的获取 ID 逻辑，它也需要错误处理）
let last_id_sql = "SELECT last_insert_rowid()";
let result = db.select(last_id_sql, &[]).await.map_err(|e| e.to_string())?;

if let Some(row) = result.into_iter().next() {
    if let Some(tauri_plugin_sql::Value::Integer(id)) = row.get(0) {
        Ok(*id)
    } else {
        // 处理获取 ID 结果非预期的错误
        Err("Database returned unexpected value type for last_insert_rowid.".to_string())
    }
} else {
    // 处理获取 ID 查询没有返回行的错误
    Err("Database did not return last_insert_rowid.".to_string())
}

}
“`

在前端，调用 invoke 的 Promise 会在 Rust 命令返回 Err 时被拒绝。你可以使用 try...catch 块来捕获这些错误，并向用户提供反馈。

typescript
// 前端调用代码中的错误处理
async function addNewUser(name: string, email: string) {
try {
const userId = await invoke('insert_user', { name: name, email: email });
console.log('New user inserted with ID:', userId);
// 成功提示
} catch (error) {
console.error('Failed to insert user:', error);
// 向用户显示错误消息，例如：
// displayErrorMessage(`Failed to add user: ${error}`);
// 可以根据错误字符串内容进行更精细的处理，例如判断是否是唯一约束错误
}
}

通过返回 Result<T, String>，我们可以将 Rust 后端的错误信息传递到前端，方便调试和用户提示。

9. 最佳实践与注意事项

  • 数据库文件位置： 始终使用 Tauri 的路径 API 或 tauri-plugin-sql 的路径配置将数据库文件存放在用户数据目录中。不要将数据库文件放在应用资源目录或可执行文件同级，这可能导致权限问题或在应用更新时数据丢失。
  • 异步操作： 数据库 I/O 操作是异步的。tauri-plugin-sql 的方法（execute, select, begin, commit, rollback）都是 async 函数，需要在 async 上下文中使用 await 调用。Tauri 命令天然支持 async 函数，所以这通常不是问题。确保你的命令函数是 async fn。
  • 性能优化：
    • 索引： 为经常用于 WHERE 子句和 JOIN 条件的列创建索引，可以显著提高查询速度。使用 CREATE INDEX index_name ON table_name (column_name); 语句。将索引创建放在迁移脚本中。
    • 查询优化： 避免 SELECT *，只选择需要的列。优化 JOIN 操作。考虑分页查询（使用 LIMIT 和 OFFSET）。
    • 批量操作： 如果需要执行大量 INSERT, UPDATE, DELETE 操作，将它们放在一个事务中可以提高性能，减少磁盘 I/O 开销。某些库也支持批量插入语法。
  • 数据备份与恢复： 对于存储重要用户数据的应用，考虑提供数据备份和恢复功能。SQLite 数据库就是一个文件，备份就是复制文件，恢复就是替换文件。这可以通过 Tauri 的文件系统 API 在 Rust 后端实现。
  • 并发： SQLite 支持并发读，但在写操作时会锁定整个数据库文件（写锁）。对于大多数单用户桌面应用这通常不是问题。如果在极端并发写入场景下遇到问题，可能需要更复杂的策略（如 WAL 模式，或考虑其他数据库）。tauri-plugin-sql 已经默认启用了 WAL (Write-Ahead Logging)，这提高了并发读取性能，但写入仍然是独占的。
  • 数据类型： 理解 SQLite 的灵活数据类型系统（动态类型）以及如何在 Rust 和前端之间映射数据类型。SQLite 不强制列的数据类型，但建议在 CREATE TABLE 语句中指定类型提示，并注意在 Rust 中从 tauri_plugin_sql::Value 进行类型转换时的安全性。

10. 总结

通过本文的详细讲解，你应该对如何在 Tauri 应用中使用 tauri-plugin-sql 插件操作 SQLite 数据库有了全面的认识。我们覆盖了：

  • 在 Tauri 项目中集成 SQL 插件的环境配置。
  • 数据库文件的自动管理和路径处理。
  • 使用 execute 方法创建表结构、插入、更新和删除数据。
  • 使用 select 方法查询数据并将结果映射到 Rust 结构体。
  • 利用参数绑定实现安全高效的预处理语句。
  • 通过事务保证多步操作的原子性。
  • 使用内置的迁移功能管理数据库 Schema 的版本变更。
  • 通过 Tauri Commands 实现前端与后端数据库逻辑的交互。
  • 以及如何进行基本的错误处理和一些最佳实践建议。

SQLite 是一个强大而方便的嵌入式数据库，与 Tauri 的结合为构建具有 robust 本地数据能力的桌面应用提供了优秀的解决方案。掌握这些技术，你就能为你的 Tauri 应用构建坚实可靠的数据存储层。

希望这篇详细的文章能帮助你在 Tauri 开发中顺利地集成和使用 SQLite 数据库！祝你开发愉快！

发表评论

您的邮箱地址不会被公开。 必填项已用 * 标注

滚动至顶部