Butane

一个专注于简洁性和Rust而非SQL编写的Rust实验性ORM。

Butane采用面向对象的方法进行数据库操作。它可以被看作是一个对象持久化系统，而不仅仅是ORM -- 它背后是SQL数据库的事实主要对API用户是实现细节。

功能

• 使用类似Rust语法的关联查询（通过 proc-macro）
• 无需编写SQL即可自动迁移（尽管如果需要，可以手动调整生成的SQL）
• 能够在Rust代码中嵌入迁移（以便库可以轻松捆绑其迁移）
• SQLite和PostgreSQL后端
• 无论数据库后端如何，都可以编写完全相同或几乎相同的代码

入门

模型，通过结构属性声明定义数据库模式。例如，一个博客的Post模型可能看起来像这样

#[model]
#[derive(Default)]
struct Post {
    id: AutoPk<i32>,
    title: String,
    body: String,
    published: bool,
    likes: i32,
    tags: Many<Tag>,
    blog: ForeignKey<Blog>,
    byline: Option<String>,
}

一个 对象 是一个 模型 的实例。对象被创建的方式就像一个普通的结构体实例一样，但必须保存才能持久化。

let mut post = Post::new(blog, title, body);
post.save(conn)?;

只有保存实例的更改才会应用于数据库

post.published = true;
post.save(conn)?;

使用 query! 宏进行查询时，具有良好的人体工程学。

let posts = query!(Post, published == true).limit(5).load(&conn)?;

有关详细教程，请参阅 入门指南。

Cargo功能

Butane向Cargo公开了几个功能。默认情况下，没有启用后端：您可能需要启用 sqlite 和/或 pg

• default：启用 datetime、json 和 uuid。
• debug：用于开发Butane，用户通常不会启用。
• datetime：支持时间戳（使用 chrono 包）。
• fake：支持 fake 包生成假数据。
• json：支持将结构体存储为 JSON，包括使用 postgres 的 JSONB 字段类型。
• log：将某些警告记录到 log 包界面（目标 "butane"）。
• pg：支持使用 postgres 包的 PostgreSQL。
• r2d2：使用 r2d2 支持连接池（见 butane::db::ConnectionManager）。
• sqlite：支持使用 rusqlite 包的 SQLite。
• sqlite-bundled：捆绑 sqlite 而不是使用系统版本。
• tls：当使用 PostgreSQL 时支持 TLS，使用 postgres-native-tls 包。
• uuid：支持 UUID（使用 uuid 包）。

限制

• Butane，特别是其迁移系统，期望拥有数据库。它可以与被其他消费者访问的现有数据库一起使用，但这不是设计目标，也没有从现有数据库模式推断 Butane 模型的工具。
• API 的人性化优先于性能。这并不意味着 Butane 慢，而是在简单直接的 API 和尽可能小的开销之间做出选择时，API 将获胜。

路线图

Butane 是年轻的。以下功能目前尚不存在，但计划实现

• 外键约束级联设置
• 增量对象保存
• ForeignKey 和 Many 的反向引用。
• 迁移中支持字段/列重命名
• 准备/可重用查询
• 基准测试和性能调整
• 支持其他数据库，如 MySQL 或 SQL Server，没有明确计划，但欢迎贡献。

与 Diesel 的比较

Butane 受 Diesel 和 Django ORM 的启发。如果您正在寻找成熟、性能良好且灵活的 ORM，请使用 Diesel。Butane 不旨在比 Diesel 更好，但它做出了一些 不同的 决定，包括

1. 它更面向对象，以牺牲灵活性为代价。

2. 优先考虑自动迁移。

3. Rust 代码是真相之源。模式是通过 Rust 代码中模型的定义来理解的，而不是从数据库中推断。

4. 查询是通过在 proc-macro 调用内部使用 DSL 构建的，而不是通过导入 DSL 方法/名称到当前作用域中来使用。对于 Diesel，您可能会编写

   use diesel_demo::schema::posts::dsl::*;
   let posts = posts.filter(published.eq(true))
        .limit(5)
        .load::<Post>(&conn)?
   

   而对于 Butane，您将改写为

   let posts = query!(Post, published == true).limit(5).load(&conn)?;
   

   哪种形式更可取主要是一种审美判断。

5. 数据库后端之间的差异在很大程度上被隐藏了。

6. Diesel 在整体上要成熟得多，功能也更齐全。

有关详细教程，请参阅 入门指南。

许可证

Butane 依据 MIT 许可证或 Apache 许可证 Version 2.0，由您选择。

除非您明确表示，否则根据 Apache-2.0 许可证定义，您提交给 Butane 的任何有意贡献，都将如上所述双许可，没有额外的条款或条件。