英文文档

如果你喜欢我们的工作，请考虑给我们加星标、分享并参与贡献！

完成 SeaQL 社区调查 2025 可以帮助我们维护 SeaORM！

加入我们的 Discord 服务器，与 SeaQL 社区的其他成员交流！

• 文档
• 教程
• 示例集

集成示例：

• Actix v4 示例
• Axum 示例
• GraphQL 示例
• jsonrpsee 示例
• Loco TODO 示例 / Loco REST 入门
• Poem 示例
• Rocket 示例 / Rocket OpenAPI 示例
• Salvo 示例
• Tonic 示例
• Seaography 示例

1. 异步

   基于 SQLx，SeaORM 从第一天起就支持异步。

2. 动态

   构建在 SeaQuery 之上，SeaORM 允许你构建复杂的动态查询。

3. 面向服务

   快速构建能够在 REST、GraphQL 和 gRPC API 中进行关联、过滤、排序和分页数据的服务。

4. 生产就绪

   SeaORM 功能丰富、测试完善，并已被多家公司和初创企业用于生产环境。

use sea_orm::entity::prelude::*;

#[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
#[sea_orm(table_name = "cake")]
pub struct Model {
    #[sea_orm(primary_key)]
    pub id: i32,
    pub name: String,
}

#[derive(Copy, Clone, Debug, EnumIter, DeriveRelation)]
pub enum Relation {
    #[sea_orm(has_many = "super::fruit::Entity")]
    Fruit,
}

impl Related<super::fruit::Entity> for Entity {
    fn to() -> RelationDef {
        Relation::Fruit.def()
    }
}

// 查找所有模型
let cakes: Vec<cake::Model> = Cake::find().all(db).await?;

// 查找并过滤
let chocolate: Vec<cake::Model> = Cake::find()
    .filter(cake::Column::Name.contains("chocolate"))
    .all(db)
    .await?;

// 查找单个模型
let cheese: Option<cake::Model> = Cake::find_by_id(1).one(db).await?;
let cheese: cake::Model = cheese.unwrap();

// 查找关联模型（惰性）
let fruits: Vec<fruit::Model> = cheese.find_related(Fruit).all(db).await?;

// 查找关联模型（急切）
let cake_with_fruits: Vec<(cake::Model, Vec<fruit::Model>)> =
    Cake::find().find_with_related(Fruit).all(db).await?;

use sea_orm::DerivePartialModel;

#[derive(DerivePartialModel)]
#[sea_orm(entity = "cake::Entity")]
struct CakeWithFruit {
    id: i32,
    name: String,
    #[sea_orm(nested)]
    fruit: Option<fruit::Model>,
}

let cakes: Vec<CakeWithFruit> = cake::Entity::find()
    .left_join(fruit::Entity)
    .into_partial_model()
    .all(db)
    .await?;

let apple = fruit::ActiveModel {
    name: Set("Apple".to_owned()),
    ..Default::default() // 不需要设置主键
};

let pear = fruit::ActiveModel {
    name: Set("Pear".to_owned()),
    ..Default::default()
};

// 插入单个
let pear = pear.insert(db).await?;

// 插入多个并返回最后插入的id（需要数据库与列类型支持）
Fruit::insert_many([apple, pear]).exec(db).await?;
result.last_insert_id == Some(2);

// 插入多条记录并返回（需要数据库支持）
let models: Vec<fruit::Model> = Fruit::insert_many([apple, pear])
    .exec_with_returning(db)
    .await?;
models[0]
    == fruit::Model {
        id: 1,
        name: "Apple".to_owned(),
        cake_id: None,
    };

// 使用 ON CONFLICT，在主键冲突时忽略插入, 并为 MySQL 提供特定的 polyfill
let result = Fruit::insert_many([apple, pear])
    .on_conflict_do_nothing()
    .exec(db)
    .await?;

matches!(result, TryInsertResult::Conflicted);

use sea_orm::sea_query::{Expr, Value};

let pear: Option<fruit::Model> = Fruit::find_by_id(1).one(db).await?;
let mut pear: fruit::ActiveModel = pear.unwrap().into();

pear.name = Set("Sweet pear".to_owned());

// 更新单个
let pear: fruit::Model = pear.update(db).await?;

// 更新多个：UPDATE "fruit" SET "cake_id" = NULL WHERE "fruit"."name" LIKE '%Apple%'
Fruit::update_many()
    .col_expr(fruit::Column::CakeId, Expr::value(Value::Int(None)))
    .filter(fruit::Column::Name.contains("Apple"))
    .exec(db)
    .await?;

let banana = fruit::ActiveModel {
    id: NotSet,
    name: Set("Banana".to_owned()),
    ..Default::default()
};

// 创建，因为主键 `id` 是 `NotSet`
let mut banana = banana.save(db).await?;

banana.name = Set("Banana Mongo".to_owned());

// 更新，因为主键 `id` 是 `Set`
let banana = banana.save(db).await?;

// 删除单个
let orange: Option<fruit::Model> = Fruit::find_by_id(1).one(db).await?;
let orange: fruit::Model = orange.unwrap();
fruit::Entity::delete(orange.into_active_model())
    .exec(db)
    .await?;

// 或者更简单
let orange: Option<fruit::Model> = Fruit::find_by_id(1).one(db).await?;
let orange: fruit::Model = orange.unwrap();
orange.delete(db).await?;

// 删除多个：DELETE FROM "fruit" WHERE "fruit"."name" LIKE 'Orange'
fruit::Entity::delete_many()
    .filter(fruit::Column::Name.contains("Orange"))
    .exec(db)
    .await?;

Seaography 是一个构建在 SeaORM 之上的 GraphQL 框架。Seaography 允许你快速构建 GraphQL 解析器。只需几个命令，你就可以从 SeaORM 实体启动一个 GraphQL 服务器！

查看 Seaography 示例 了解更多。

SeaORM Pro 是一个管理面板解决方案，让你可以快速轻松地为应用程序启动管理面板 - 不需要前端开发技能，但有当然更好！

特性：

• 完整的 CRUD 操作
• 基于 React + GraphQL 构建
• 内置 GraphQL 解析器
• 使用简单的 TOML 自定义 UI

了解更多

• 示例仓库
• Loco 入门
• Axum 入门

SeaORM 1.0 是一个稳定版本。1.x 版本将更新到至少 2025 年 10 月，之后我们将决定是发布 2.0 版本还是延长 1.x 的生命周期。

这并不意味着 SeaORM 已经"完成"，我们设计了一种架构，可以在不进行重大突破性更改的情况下提供新功能。事实上，更多功能即将推出！

• 变更日志

以下是一些使用 SeaORM 构建的优秀开源软件的简短列表。完整列表在这里。欢迎提交你的项目！

项目	GitHub	标语
Zed		高性能、多人代码编辑器
OpenObserve		开源可观测性平台
RisingWave		流处理和管理平台
LLDAP		轻量级 LDAP 用户管理服务器
Warpgate		智能 SSH 堡垒，适用于任何 SSH 客户端
Svix		企业级 Webhooks 服务
Ryot		你永远需要的唯一自托管追踪器
Lapdev		自托管远程开发环境
System Initiative		DevOps 自动化平台
OctoBase		轻量级、可扩展、离线协作数据后端

根据以下任一许可证授权：

• Apache 许可证 2.0 (LICENSE-APACHE 或 http://www.apache.org/licenses/LICENSE-2.0)
• MIT 许可证 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

由你选择。

除非你明确声明，否则你有意提交的任何贡献，根据 Apache-2.0 许可证的定义，都将按照上述许可证双重授权，且不附带任何附加条款或条件。

我们诚挚邀请你参与、贡献，并携手共建 Rust 的未来。

向我们的贡献者们致以最真诚的感谢！

SeaQL.org 是一个由热情的开发者运营的独立开源组织。如果你喜欢使用我们的库，请为我们的仓库点赞和分享。如果你愿意，通过 GitHub Sponsor 进行小额捐赠将不胜感激，并将大大有助于维持组织的运营。

QDX 开创了量子动力学驱动的药物发现，利用人工智能和超级计算加速分子建模。 我们非常感谢 QDX 赞助 SeaORM 的开发，这是为其数据工程工作流提供支持的 SQL 工具包。

我们感谢银牌赞助商：Digital Ocean 赞助我们的服务器。以及 JetBrains 赞助我们的 IDE。

Ferris 的朋友，寄居蟹 Terres 是 SeaORM 的官方吉祥物。他的爱好是收集贝壳。

Rustacean 贴纸包是表达你对 Rust 热情的完美方式。 我们的贴纸采用优质防水乙烯基制成，具有独特的哑光 finish。 把它们贴在你的笔记本电脑、笔记本或任何设备上，展示你对 Rust 的热爱！

贴纸包内容：

• SeaQL 项目的标志：SeaQL、SeaORM、SeaQuery、Seaography、FireDBG
• SeaQL 的吉祥物：寄居蟹 Terres
• Rust 的吉祥物：螃蟹 Ferris
• Rustacean 文字

支持 SeaQL 并获取贴纸包！ 所有收益直接用于 SeaQL 项目的持续开发。