Rusqlcipher

Rusqlcipher 是一个用于从 Rust 使用 SQLCipher 的便捷包装器。它试图提供一个类似于 rust-postgres 的接口。查看完整的 API 文档。

extern crate rusqlcipher;
extern crate time;

use time::Timespec;
use rusqlcipher::Connection;

#[derive(Debug)]
struct Person {
    id: i32,
    name: String,
    time_created: Timespec,
    data: Option<Vec<u8>>
}

fn main() {
    let conn = Connection::open_in_memory().unwrap();

    conn.execute("CREATE TABLE person (
                  id              INTEGER PRIMARY KEY,
                  name            TEXT NOT NULL,
                  time_created    TEXT NOT NULL,
                  data            BLOB
                  )", &[]).unwrap();
    let me = Person {
        id: 0,
        name: "Steven".to_string(),
        time_created: time::get_time(),
        data: None
    };
    conn.execute("INSERT INTO person (name, time_created, data)
                  VALUES (?1, ?2, ?3)",
                 &[&me.name, &me.time_created, &me.data]).unwrap();

    let mut stmt = conn.prepare("SELECT id, name, time_created, data FROM person").unwrap();
    let person_iter = stmt.query_map(&[], |row| {
        Person {
            id: row.get(0),
            name: row.get(1),
            time_created: row.get(2),
            data: row.get(3)
        }
    }).unwrap();

    for person in person_iter {
        println!("Found person {:?}", person.unwrap());
    }
}

SQLCipher

本作品基于 rusqlite 和 SQLCipher。此包已预编译 SQLCipher 以使用 OpenSSL 1.1.0 或更高版本，并替换了 libsqlcipher-sys/sqlite3/ 中的以下三个文件：sqlite3.c、sqlite3.h、sqlite3ext.h。有关编译 openssl 的信息，请参阅 openssl-sys。SQLCipher 已修改为使用 HMAC-SHA256 而不是默认的 HMAC-SHA1。

支持的 SQLite 版本

基本的 rusqlcipher 包支持 SQLite 版本 3.6.8 或更高版本。如果您需要支持旧版本，请提交问题。某些 cargo 功能需要更高版本的 SQLite；请参见下文详情。

可选功能

Rusqlite 提供了几个在 Cargo 特性 之后的特性。它们是

• load_extension 允许加载基于动态库的 SQLite3 扩展。
• backup 允许使用 SQLite 的在线备份 API。注意：此功能需要 SQLite 3.6.11 或更高版本。
• functions 允许您将 Rust 闭包加载到 SQLite 连接中以供查询使用。注意：此功能需要 SQLite 3.7.3 或更高版本。
• trace 允许钩入 SQLite 的跟踪和性能分析 API。注意：此功能需要 SQLite 3.6.23 或更高版本。
• blob 提供了对 SQL BLOB 的 std::io::{Read, Write, Seek} 访问。注意：此功能需要 SQLite 3.7.4 或更高版本。
• limits 允许您设置和检索 SQLite 的每个连接限制。
• chrono 实现了来自 FromSql 和 ToSql 的各种类型，这些类型来自 chrono crate。
• serde_json 实现了来自 FromSql 和 ToSql 的 Value 类型，这些类型来自 serde_json crate。
• bundled 使用了 sqlite3 的捆绑版本。这对于链接到 sqlite3 比较复杂的情况，如 Windows，是一个很好的选择。
• sqlcipher 寻找 SQLCipher 库以进行链接，而不是 SQLite。此功能与 bundled 是互斥的。

关于构建 rusqlcipher 和 libsqlcipher-sys 的说明

libsqlcipher-sys 是一个与 rusqlcipher 分离的 crate，它提供了 SQLite 的 C API 的 Rust 声明。默认情况下，libsqlcipher-sys 尝试使用 pkg-config 在您的系统上查找现有的 SQLite 库，或者为 MSVC ABI 构建使用 Vcpkg 安装。 rusqlcipher 也依赖于 OpenSSL 1.1.0 或更高版本。

您可以通过多种方式调整此行为

• 如果您使用 bundled 功能，libsqlcipher-sys 将使用 gcc crate 从源代码编译 SQLite 并链接到该源。此源代码嵌入在 libsqlcipher-sys crate 中，当前为 SQLite 3.15.2（截至 rusqlcipher 0.10.1 / libsqlcipher-sys 0.7.1）。这可能是解决任何构建问题的最简单方法。您可以通过在您的 Cargo.toml 文件中添加以下内容来启用此功能

  [dependencies.rusqlcipher]
  version = "0.11.0"
  features = ["bundled"]
  

• 您可以将 SQLITE3_LIB_DIR 设置为指向包含 SQLite 库的目录。
• 安装 sqlite3 开发包通常就足够了，但 pkg-config 和 vcpkg 的构建助手有一些额外的配置选项。使用 vcpkg 的默认情况是动态链接。 vcpkg install sqlite3:x64-windows 将安装所需的库。

绑定生成

我们使用 bindgen 从 SQLite 的 C 头文件生成 Rust 声明。 bindgen 推荐 将其作为使用此库的库的构建过程的一部分运行。我们尝试了这种方法（特别是 rusqlcipher 0.10.0），但它有一些不便之处

• libsqlcipher-sys（以及因此 rusqlcipher）的构建时间显著增加。
• 运行 bindgen 需要一个相对较新的 Clang 版本，而许多系统默认并未安装。
• 运行 bindgen 还需要 SQLite 头文件存在。

截至 rusqlcipher 0.1.0，我们通过提供几个 SQLite 版本的预生成绑定来避免在构建时运行 bindgen。当编译 rusqlcipher 时，我们使用您选择的 Cargo 功能来选择支持您选择的功能的最小 SQLite 版本的绑定。如果您直接使用 libsqlcipher-sys，您可以使用相同的功能来选择预生成的绑定

• min_sqlite_version_3_6_8 - SQLite 3.6.8 绑定（这是默认值）
• min_sqlite_version_3_6_11 - SQLite 3.6.11 绑定
• min_sqlite_version_3_6_23 - SQLite 3.6.23 绑定
• min_sqlite_version_3_7_3 - SQLite 3.7.3 绑定
• min_sqlite_version_3_7_4 - SQLite 3.7.4 绑定

如果您使用 bundled 功能，您将获得 SQLite 集成版本预生成的绑定。如果您需要其他特定的预生成绑定版本，请提交一个问题。如果您想在构建时运行 bindgen 以生成自己的绑定，请使用 buildtime_bindgen Cargo 功能。

作者

Michael Lodder, [email protected]

原作者

John Gallagher, [email protected]

许可证

Rusqlcipher 可在 Apache 版本 2 许可证下使用。有关更多信息，请参阅 LICENSE 文件。Rusqlite 可在 MIT 许可证下使用。有关更多信息，请参阅 ORIGLICENSE 文件。