Diesel 的安装与数据库迁移

发表于 更新于 分类于 ，

Diesel 所需 Rust 版本 >= 1.65

安装至项目

修改 Cargo.toml

Cargo.toml
1
2
3
[dependencies]
diesel = { version = "2.1.0", features = ["postgres"] }
dotenvy = "0.15"

安装 CLI

Diesel 提供了用于管理项目的命令行工具，可以通过 cargo 安装。

1
cargo install diesel_cli

但是，你可能会遇到这样的问题：

note: ld: library not found for -lmysqlclient
clang: error: linker command failed with exit code 1 (use -v to see invocation)

这是系统缺乏相关的用于操作数据库的链接库导致的，这里阐述使用 Sqlite 的时候的解决方法。

  1. 在报错的终端搜索 LIBPATH，复制其值；

  2. 打开 LIBPATH 所在的目录，我们需要把链接库放在这里；

  3. 对于 Sqlite，我们可以在 Cargo.toml 的 [dependencies] 块中加入：

    1
    rusqlite = { version = "0.31.0", features = ["bundled"] }

  4. 编译项目，然后在编译目录下的 build 文件夹找到 libsqlite3-sys-* 文件夹，* 表示一串哈希字符串。可能会包含多个这样的文件夹。找到其中包含的 out/libsqlite3.a 文件，把 libsqlite3.a 复制到前面打开的 LIBPATH 中。

  5. 再次安装CLI，由于我们只添加了 sqlite 库，所以我们需要指定 features

    1
    cargo install diesel_cli --no-default-features --features sqlite

    对于其它数据库，features 需要如下填写

    数据库 features
    MySQL mysql
    PostgreSQL postgres
    SQLite sqlite

    diesel/.github/workflows/ci.yml at master · diesel-rs/diesel

项目初步设置

首先，我们需要在项目根目录下创建一个 .env 文件，在其中写入数据库的地址：

1
DATABASE_URL=postgres://username:password@localhost/diesel_demo

对于SQLite 数据库，示例如下：

1
DATABASE_URL=sqlite://database.db

Windows 下不建议使用 echo 指令，因为操作系统可能不会以 UTF8 格式写入文件，导致文件无法读取

然后，我们就可以使用 CLI 让 Diesel 帮我们初始化项目，包括：

  • 创建数据库
  • 创建数据库迁移文件夹（用于生成数据库结构）

创建第一个表

对于表的创建，Diesel 需要同时拥有过该表的迁移和 Schema，但 Diesel 可以根据其一生成另一。

  • 手动定义 迁移，Diesel 在迁移时自动生成 Schema
  • 手动定义 Schema，Diesel 在迁移时自动生成 迁移

创建第一个表（SQL）

我们可以使用 Diesel 的数据库迁移功能来创建数据库结构，并对数据库的结构进行版本控制。首先，我们需要生成迁移文件：

1
diesel migration generate create_posts

其中 create_posts 即为迁移的名称，最终会以 时间_crewate_posts 方式生成文件夹，并生成 up.sql 和 down.sql 分别用于构建和撤销数据库结构。

举例来说，我们可以在 up.sql 中写入：

up.sql
1
2
3
4
5
6
CREATE TABLE posts (
  id SERIAL PRIMARY KEY,
  title VARCHAR NOT NULL,
  body TEXT NOT NULL,
  published BOOLEAN NOT NULL DEFAULT FALSE
)

在 down.sql 中删除改表：

down.sql
1
DROP TABLE posts

创建迁移后，我们可以开始迁移（根据 up.sql）

1
diesel migration run

也可以撤销已经进行的迁移（根据 down.sql）

1
diesel migration redo

创建第一个表 (schema)

使用 SQL 创建迁移可以最大程度地保留灵活性，但是 Diesel 也支持使用 schema 来进行迁移，我们将在 schema 文件中定义表及其对应的 Rust 类型，Diesel 会自动推断其在数据库中的类型。

创建 schema.rs 文件，并写入表结构，如:

1
2
3
4
5
6
7
8
diesel::table! {
    posts (id) {
        id -> Int4,
        title -> Varchar,
        body -> Text,
        published -> Bool,
    }
}

然后，我们还需要生成迁移文件：

1
diesel migration generate --diff-schema create_posts

有了迁移文件后，一切就如前文所述的一样运行迁移即可。

生产环境下运行迁移

我们不能要求用户安装 Diesel CLI 并运行迁移指令，Diesel 提供了在代码中运行迁移的方法，这个方法是：

  1. 使用在 diesel_migrations crate 中的 embed_migrations! 宏，这样迁移文件会包含在最终的二进制文件中；
  2. 使用 connection.run_pending_migrations(MIGRATIONS) 代码进行迁移。

示例：

Cargo.toml
1
diesel_migrations = { version = "2.1.0", features = ["sqlite"]}
main.rs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
use diesel::sqlite::SqliteConnection;
use diesel::prelude::*;
use dotenvy::dotenv;
use std::env;
use diesel_migrations::{embed_migrations, EmbeddedMigrations, MigrationHarness};

pub fn establish_connection() -> SqliteConnection {
    dotenv().ok();
    let database_url = env::var("DATABASE_URL").expect("DATABASE_URL must be set");
    SqliteConnection::establish(&database_url)
        .unwrap_or_else(|_| panic!("Error connecting to {}", database_url))
}

fn main() {
    let conn = &mut establish_connection();
    const MIGRATIONS: EmbeddedMigrations = embed_migrations!();
    let _ = conn.run_pending_migrations(MIGRATIONS);

	// ...
}

embed_migrations in diesel_migrations - Rust (docs.rs)

注意，若不引入 diesel_migrations::MigrationHarness trait，则无法使用 run_pending_migrations 方法。