ormlite

ormlite 是一个专为喜欢SQL的开发者设计的Rust ORM。 让我们看看它的实际应用

use ormlite::model::*;
use ormlite::sqlite::SqliteConnection;

#[derive(Model, Debug)]
pub struct Person {
    pub id: i32,
    pub name: String,
    pub age: i32,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// Start by making a database connection.
    let mut conn = SqliteConnection::connect(":memory:").await.unwrap();

    /// You can insert the model directly.
    let mut john = Person {
        id: 1,
        name: "John".to_string(),
        age: 99,
    }.insert(&mut conn).await?;

    println!("{:?}", john);

    /// After modifying the object, you can update all its fields.
    john.age += 1;
    john.update_all_fields(&mut conn).await?;

    /// Query builder syntax closely follows SQL syntax, translated into chained function calls.
    let people = Person::select()
        .where_("age > ?").bind(50)
        .fetch_all(&mut conn).await?;

    println!("{:?}", people);
}

你可能会喜欢 ormlite 因为

• 它可以从Rust结构体自动生成迁移。据我所知，这是唯一具有这种功能的Rust ORM。
• 连接API（处于alpha阶段）的组件比其他任何Rust ORM都要少。它仅依赖于表 struct 本身，而不依赖于关系特性和模块（如SeaORM或Diesel）。
• 几乎没有查询构建器语法要学习。查询构建器基本上是将原始SQL的 &str 片段连接起来。它介于可组合性和对已熟悉SQL的人几乎零学习曲线之间。

快速入门

安装

使用 cargo 安装

# For postgres
cargo add ormlite --features postgres
# For sqlite
cargo add ormlite --features sqlite

或更新你的 Cargo.toml

[dependencies]
# For postgres
ormlite = { version = "..", features = ["postgres"] }
# For sqlite
ormlite = { version = "..", features = ["sqlite"] }

支持其他数据库和运行时，但测试较少。如果您遇到任何问题，请提交问题。

环境设置

您需要在环境中设置 DATABASE_URL。我们建议使用像 just 这样的工具，它可以拉入 .env 文件，但为了简单起见，这里我们将直接使用shell。

export DATABASE_URL=postgres://postgres:postgres@localhost:5432/postgres

迁移

如果您正在查询静态数据库并且不需要迁移，请跳过本节。如果您需要迁移，请继续阅读。

首先，安装 ormlite-cli。目前，该命令行工具仅支持Postgres。虽然 ormlite-cli 与 sqlx-cli 是分开的，但它们之间100%兼容。《code>sqlx-cli 不支持自动生成迁移或快照（在开发中无需编写迁移即可回滚），但它的边缘技术较少，支持更多数据库类型。

cargo install ormlite-cli

接下来，创建数据库和迁移表。 init 创建一个 _sqlx_migrations 表来跟踪你的迁移。

# Create the database if it doesn't exist. For postgres, that's:
# createdb <dbname>
ormlite init

让我们看看迁移的实际应用。创建一个带有 #[derive(Model)] 的Rust结构体，这样CLI工具可以检测到并自动生成迁移

# src/models.rs

use ormlite::model::*;

#[derive(Model, Debug)]
pub struct Person {
    pub id: i32,
    pub name: String,
    pub age: i32,
}

接下来，自动生成迁移。

ormlite migrate initial

这将在 migrations/ 中创建一个纯SQL文件。在执行之前，我们先来审查它

cat migrations/*.sql

审查满意后，您可以执行它

ormlite up

默认情况下， up 还会创建一个快照，因此如果需要，您可以使用 ormlite down 进行回滚。还可以选择生成成对的up/down迁移，而不是仅生成up迁移。

设置到此结束。现在让我们看看如何运行查询。

插入 & 更新

README顶部插入和更新的语法对于UUID主键表最有效。

use ormlite::model::*;
use uuid::Uuid;

#[derive(Model, Debug)]
pub struct Event {
    pub id: Uuid,
    pub name: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let mut conn = ormlite::sqlite::SqliteConnection::connect(":memory:").await.unwrap();

    let mut event = Event {
        id: Uuid::new_v4(),
        name: "user_clicked".to_string(),
    }.insert(&mut conn).await?;

    println!("{:?}", event);
}

这个语法有两个可能的问题。首先，id 不是 Option，所以它必须设置，这会给自动增长的id字段造成问题。其次，结构体无法跟踪哪些字段被修改，因此更新方法必须更新所有列。

插入结构体

为了解决自动增长的问题，您可以使用这里显示的插入结构体或下面的构建器。

use ormlite::types::Json;
use serde_json::Value;

#[derive(Model, Debug)]
#[ormlite(insertable = InsertPerson)]
pub struct Person {
    pub id: i32,
    // Because the other fields are the primary key, and marked as default and default_value respectively,
    // `name` is the only field in the InsertPerson struct.
    pub name: String,
    // This field will not be part of the InsertPerson struct,
    // and rows will take the database-level default upon insertion.
    #[ormlite(default)]
    pub archived_at: Option<DateTime<Utc>>,
    // This field will not be part of the InsertPerson struct, 
    // which will always pass the provided value when inserting.
    #[ormlite(default_value = "serde_json::json!({})")]
    pub metadata: Json<Value>,
}

async fn insertion_struct_example(conn: &mut SqliteConnection) {  
    let john: Person = InsertPerson {
        name: "John".to_string(),
    }.insert(&mut conn).await?;

    println!("{:?}", john);
}

如果派生的结构体不符合您的需求，您可以手动定义一个只包含您想要的字段的结构体，指定 table = "<table>" 以将结构体路由到同一数据库表。

#[derive(Model, Debug)]
#[ormlite(table = "person")]
pub struct InsertPerson {
    pub name: String,
    pub age: i32,
}

插入构建器 & 更新构建器

您还可以使用构建器语法进行插入或仅更新某些字段。

#[derive(Model, Debug)]
pub struct Person {
    pub id: i32,
    pub name: String,
    pub age: i32,
}

async fn builder_syntax_example() {    
    // builder syntax for insert
    let john = Person::builder()
        .name("John".to_string())
        .age(99)
        .insert(&mut conn).await?;

    println!("{:?}", john);

    // builder syntax for update
    let john = john.update_partial()
        .age(100)
        .update(&mut conn).await?;

    println!("{:?}", john);
}

选择查询

您可以使用 Model::select 在Rust逻辑中构建SQL查询。

注意：Postgres使用编号的美元符号占位符构建查询的方法很快就会失效。因此，即使与Postgres一起使用，也使用 ? 作为参数， ormlite 将在构建最终查询时将 ? 占位符替换为 $ 占位符。

#[derive(Model, Debug)]
pub struct Person {
    pub id: i32,
    pub name: String,
    pub age: i32,
}

async fn query_builder_example() {
    let people = Person::select()
        .where_("age > ?")
        .bind(50i32)
        .fetch_all(&mut conn)
        .await?;
    println!("All people over 50: {:?}", people); 
}

原始查询

如果您发现ORM方法不起作用，则可以退回到原始查询。您可以包含手写的字符串，或者如果您想要更底层的查询构建器，则可以使用 sqlmo，这是 ormlite 查询构建器和迁移自动生成背后的底层引擎。

async fn model_query_example() {
    // Query using the Model to still deserialize results into the struct
    let _person = Person::query("SELECT * FROM person WHERE id = ?")
        .bind(1)
        .fetch_one(&mut conn)
        .await?;
}

async fn raw_query_example() {
    // You can also use the raw query API, which will return tuples to decode as you like
    let _used_ids: Vec<i32> = ormlite::query_as("SELECT id FROM person")
        .fetch_all(pool)
        .await
        .unwrap()
        .into_iter()
        .map(|row: (i32, )| row.0)
        .collect();
}

表定制

属性在 这些结构体中定义。

以下示例展示了它们的应用

#[derive(Model, Debug)]
#[ormlite(table = "people", insertable = InsertPerson)]
pub struct Person {
    #[ormlite(primary_key)]
    pub id: i32,
    pub name: String,
    #[ormlite(column = "name_of_column_in_db")]
    pub age: i32,
}

连接

支持联接处于alpha阶段。目前，ormlite仅支持多对一关系（例如，人属于组织）。计划支持多对多和一对多。如果您使用此功能，请报告您遇到的任何错误。

#[derive(Model, Debug)]
pub struct Person {
    pub id: Uuid,
    pub name: String,
    pub age: i32,
    
    // Note that we don't declare a separate field `pub organization_id: Uuid`.
    // It is implicitly defined by the Join and the join_column attribute.
    #[ormlite(join_column = "organization_id")]
    pub organization: Join<Organization>,
}

#[derive(Model, Debug)]
pub struct Organization {
    pub id: Uuid,
    pub name: String,
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Note we don't need to insert it.
    let org = Organization {
        id: Uuid::new_v4(),
        name: "Acme".to_string(),
    };
    
    let user = Person {
        id: Uuid::new_v4(),
        name: "John".to_string(),
        age: 99,
        organization: Join::new(org),
    };
    
    let mut conn = ormlite::sqlite::SqliteConnection::connect(":memory:").await.unwrap();

    let user = user.insert(&mut conn).await?;
    assert_eq!(user.organization.loaded(), true);
    println!("{:?}", user);
    
    // You can choose whether you want to load the relation or not. The value will be Join::NotQueried if you don't 
    // opt-in to loading it.
    let users = Person::select()
        .join(Person::organization())
        .fetch_all(&mut conn)
        .await?;

    for user in users {
        assert!(user.organization.loaded());
        println!("{:?}", user);
    }
}

特性 & 数据类型

Uuid，Chrono，& 时间

如果您想使用Uuid或DateTime，结合serde，您需要直接依赖uuid、time或chrono，并为它们每个添加serde特性。

# Cargo.toml
[dependencies]
uuid = { version = "...", features = ["serde"] } 
chrono = { version = "...", features = ["serde"] }
time = { version = "...", features = ["serde"] }

use ormlite::model::*;
use serde::{Serialize, Deserialize};
use ormlite::types::Uuid;
use ormlite::types::chrono::{DateTime, Utc};

#[derive(Model, Debug, Serialize, Deserialize)]
pub struct Person {
    pub uuid: Uuid,
    pub created_at: DateTime<Utc>,
    pub name: String,
}

Json/Jsonb 列

您可以使用ormlite::types::Json用于JSON或JSONB字段。对于非结构化数据，使用serde_json::Value作为内部类型。对于结构化数据，使用具有Deserialize + Serialize的struct作为泛型。

use ormlite::model::*;
use ormlite::types::Json;
use serde_json::Value;

#[derive(Debug, Serialize, Deserialize)]
pub struct JobData {
    pub name: String,
}

#[derive(Model, Serialize, Deserialize)]
pub struct Job {
    pub id: i32,
    pub structured_data: Json<JobData>,
    pub unstructured_data: Json<Value>,
}

日志记录

您可以使用sqlx的logger记录查询：RUST_LOG=sqlx=info

路线图

• 直接在模型实例上插入、更新、删除
• 部分更新和插入的构建器
• 用户可以创建忽略默认值的插入模型
• 选择查询构建器
• 构建 derive 宏
• 用于获取单个实体的 Get() 函数。
• 可以指定表名和主键列名
• 自动生成插入模型
• 自动生成迁移
• 消除需要 FromRow 宏的需求
• 多对一连接
• 为迁移自动生成索引
• 多对多连接
• 一对多连接
• 确保功能正确连接以支持mysql和不同的运行时 & SSL库。
• 宏选项，自动调整如updated_at之类的列
• Upsert功能
• 批量插入
• 批量更新的查询构建器
• 处理批量更新中的on conflict子句
• 与原始sql、sqlx、ormx、seaorm、sqlite3-sys、pg、diesel的基准比较
• 宏选项，用deleted_at而不是DELETE删除
• 支持补丁记录，即带有静态字段的更新。
• 考虑一个阻塞接口，也许只适用于sqlite/Rusqlite。

贡献

开源依赖于贡献，而ormlite是一个社区项目。我们欢迎您提交错误报告、特性请求、更好的文档请求、pull请求等！