pg-worm

PostgreSQL 的 Worst ORM

pg-worm 是一个简单的、完全类型化的、异步的 PostgreSQL ORM 和查询构建器。好吧，至少这是目标。

功能/为什么选择 pg-worm？

• 现有的 ORM 不是 async，需要你编写迁移或使用 cli。 pg-worm 的明确目标是 简单，并且只需定义你的类型，无需设置。

• pg-worm 还具有 内置连接池 和 简洁的语法。

• pg-worm 不会阻碍你 - 在享受其他功能的同时，可以轻松地包含原始查询。

用法

这个库基于 tokio_postgres，并打算与 tokio 一起使用。

幸运的是，使用 pg-worm 非常简单。

只需为你的类型派生 Model 特性，连接到你的数据库，你就可以出发了！

以下是一个快速示例

// Import the prelude to get started quickly
use pg_worm::prelude::*;

#[derive(Model)]
struct Book {
    // An auto-generated primary key
    #[column(primary_key, auto)]
    id: i64,
    title: String,
    author_id: i64
}

#[derive(Model)]
struct Author {
    #[column(primary_key, auto)]
    id: i64,
    name: String
}

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // First create a connection. This can be only done once.
    Connection::build("postgres://postgres:postgres@localhost:5432").connect()?;

    // Then, create tables for your models. 
    // Use `try_create_table!` if you want to fail if a
    // table with the same name already exists.
    //
    // `force_create_table` drops the old table,
    // which is useful for development.
    //
    // If your tables already exist, skip this part.
    force_create_table!(Author, Book).await?;

    // Next, insert some data.
    // This works by passing values for all
    // fields which aren't autogenerated.
    Author::insert("Stephen King").await?;
    Author::insert("Martin Luther King").await?;
    Author::insert("Karl Marx").await?;
    Book::insert("Foo - Part I", 1).await?;
    Book::insert("Foo - Part II", 2).await?;
    Book::insert("Foo - Part III", 3).await?;

    // Let's start with a simple query for all books:
    let books = Book::select().await?; // Vec<Book>
    assert_eq!(books.len(), 3);

    // You can also search for a specific book.
    // Adding a `WHERE` clause is as simple as
    // calling a method on the respective field:
    let book = Book::select_one()
        .where_(Book::title.eq(&"Foo - Part I".to_string()))
        .await?; // Option<Book>
    assert!(book.is_some());

    // Or update exsisting records:
    let books_updated = Book::update()
        .set(Book::title, &"Foo - Part III".to_string())
        .where_(Book::title.eq(&"Foo - Part II".to_string()))
        .await?; // u64
    assert_eq!(books_updated, 1);

    // Or delete a book, you don't like:
    let books_deleted = Book::delete()
        .where_(Book::title.eq(&"Foo - Part III".to_string()))
        .await?; // u64
    assert_eq!(books_deleted, 2);

    Ok(())
}

如果你想查看更多代码示例，请查看 测试目录。

查询构建器

如上所示，pg-worm 允许你通过在所谓的 '构建器' 上链式调用方法来构建查询。对于每种查询类型，pg-worm 都提供相应的构建器（除了 INSERT，它以不同的方式处理）。

这些构建器公开了一组用于构建查询的方法。以下是他们中的几个

使用 WHERE 进行过滤

.where_() 可用于轻松地将 WHERE 子句包含在查询中。

这是通过传递一个由调用相应列的方法构建的 Where 对象来完成的。 pg-worm 会自动为你的 Model 的每个字段构造一个常量。

一个实际例子可能看起来像这样

let where_: Where<'_> = MyModel::my_field.eq(&5);

可用方法

目前，已实现了以下方法

布尔逻辑

您还可以使用标准布尔逻辑链接/修改这些过滤器

Book::select()
    .where_(!Book::id.eq(&1) & Book::id.gt(&3))
    .await?;

执行查询

构建完查询后，您只需调用 .await。这将把构建器转换为 Query 对象，然后异步执行。

执行查询总是会返回一个 Result。

原始查询

虽然这些功能很棒，但它们并不适用于所有应用程序。这就是为什么您可以轻松地执行自定义查询，同时仍然利用自动解析等优势。

// NOTE: You have to pass the exact type that PostgreSQL is 
// expecting. Doing otherwise will result in a runtime error.
let king_books = Book::query(r#"
        SELECT * FROM book 
        JOIN author ON author.id = book.author_id
        WHERE POSITION(? in author.name) > 0 
    "#, 
    vec![&"King".to_string()]
).await?;
assert_eq!(king_books.len(), 2);

有关查询构建器上的 .where_raw，请参阅相关内容，您可以通过它传递一个原始条件，而无需自己编写整个查询。

事务

pg-worm 也支持事务。您可以在 Transaction 中轻松执行任何查询，并且只有在您满意时才提交。

当事务被丢弃时，事务会自动回滚，除非它们之前已被提交。

以下是一个示例

use pg_worm::prelude::*;

#[derive(Model)]
struct Foo {
    bar: i64
}

async fn foo() -> Result<(), Box<dyn std::error::Error>> {
    // Easily create a new transaction
    let transaction = Transaction::begin().await?;

    // Execute any query inside the transaction
    let all_foo = transaction.execute(
        Foo::select()
    ).await?;   

    // Commit the transaction when done.
    // If not committed, transaction are rolled back
    // when dropped.
    transaction.commit().await?;
}

支持类型

以下是一个支持（Rust）类型及其映射到PostgreSQL类型的列表。

*T必须是另一个支持类型。嵌套和混合 Option/Vec 目前不支持。

JSON、时间戳等

也是支持的。要使用它们，请激活相应的功能，如下所示

# Cargo.toml
[dependencies]
pg-worm = { version = "latest-version", features = ["foo"] }

以下是一个支持的功能/类型及其相应的PostgreSQL类型的列表

• "serde-json" 用于 serde_json v1.0

  Rust类型	PostgreSQL类型
  Value	JSONB

• "time" 用于 time v3.0

  Rust类型	PostgreSQL类型
  Date	DATE
  Time	TIME
  PrimitiveDateTime	TIMESTAMP
  OffsetDateTime	TIMESTAMP WITH TIME ZONE

• "uuid" 用于 uuid v1.0

  Rust类型	PostgreSQL类型
  Uuid	UUID

derive 选项

您可以为您 Model 配置一些选项。这是通过使用 pg-worm 暴露的两个属性之一来完成的。

属性 #[table]

属性 #[table] 可以用来向 Model 传递配置，该配置影响相应的表本身。

use pg_worm::prelude::*;

#[derive(Model)]
#[table(table_name = "book_list")]
struct Book {
    id: i64
}

属性 #[column]

属性 #[column] 可以用来向 Model 的字段传递配置，该配置影响相应的列。

use pg_worm::prelude::*;

#[derive(Model)]
struct Book {
    #[column(primary_key, auto)]
    id: i64
}

MSRV

最低支持的 Rust 版本是 1.70，因为此 crate 使用了最近引入的 OnceLock。

许可协议

此项目在 MIT 和 Apache 2.0 许可协议下双授权。