# 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);
}

Upsert

您可以使用OnConflict（文档）处理冲突时的插入。

use ormlite::{
    model::*,
    query_builder::OnConflict,
};

#[derive(Debug, Model)]
pub struct Users {
    #[ormlite(primary_key)]
    pub id:    i32,
    pub name:  String,
    pub email: String,
}

async fn upsert_example(conn: &mut PgConnection) {
    Users {
        id: 1,
        name: String::from("New name"),
        email: String::from("New email"),
    }
        .insert(&mut conn)
        // update values of all columns on primary key conflict
        .on_conflict(OnConflict::do_update_on_pkey("id"))
        .await
        .unwrap();
}

选择查询

您可以使用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只支持多对一关系（例如，Person属于Organization）。计划支持多对多和一对多。如果您使用此功能，请报告您遇到的任何错误。

#[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, & Time

如果您想使用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 的结构体作为泛型。

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 的日志记录器记录查询： RUST_LOG=sqlx=info

路线图

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

贡献

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