166 lines
4.7 KiB
Markdown
166 lines
4.7 KiB
Markdown
<div align="center">
|
|
|
|
<img src="https://www.sea-ql.org/SeaORM/img/SeaORM banner.png"/>
|
|
|
|
<h1>SeaORM</h1>
|
|
|
|
<p>
|
|
<strong>🐚 An async & dynamic ORM for Rust</strong>
|
|
</p>
|
|
|
|
[](https://crates.io/crates/sea-orm)
|
|
[](https://docs.rs/sea-orm)
|
|
[](https://github.com/SeaQL/sea-orm/actions/workflows/rust.yml)
|
|
|
|
<sub>Built with 🔥 by 🌊🦀🐚</sub>
|
|
|
|
</div>
|
|
|
|
# SeaORM
|
|
|
|
SeaORM is a relational ORM to help you build light weight and concurrent web services in Rust.
|
|
|
|
[](https://www.sea-ql.org/SeaORM/docs/index)
|
|
[](https://github.com/SeaQL/sea-orm/tree/master/examples/async-std)
|
|
[](https://github.com/SeaQL/sea-orm/tree/master/examples/rocket_example)
|
|
[](https://discord.com/invite/uCPdDXzbdv)
|
|
|
|
## Features
|
|
|
|
1. Async
|
|
|
|
Relying on [SQLx](https://github.com/launchbadge/sqlx), SeaORM is a new library with async support from day 1.
|
|
|
|
2. Dynamic
|
|
|
|
Built upon [SeaQuery](https://github.com/SeaQL/sea-query), SeaORM allows you to build complex queries without 'fighting the ORM'.
|
|
|
|
3. Testable
|
|
|
|
Use mock connections to write unit tests for your logic.
|
|
|
|
4. Service oriented
|
|
|
|
Quickly build services that join, filter, sort and paginate data in APIs.
|
|
|
|
## A quick taste of SeaORM
|
|
|
|
### Select
|
|
```rust
|
|
// find all models
|
|
let cakes: Vec<cake::Model> = Cake::find().all(db).await?;
|
|
|
|
// find and filter
|
|
let chocolate: Vec<cake::Model> = Cake::find()
|
|
.filter(cake::Column::Name.contains("chocolate"))
|
|
.all(db)
|
|
.await?;
|
|
|
|
// find one model
|
|
let cheese: Option<cake::Model> = Cake::find_by_id(1).one(db).await?;
|
|
let cheese: cake::Model = cheese.unwrap();
|
|
|
|
// find related models (lazy)
|
|
let fruits: Vec<fruit::Model> = cheese.find_related(Fruit).all(db).await?;
|
|
|
|
// find related models (eager)
|
|
let cake_with_fruits: Vec<(cake::Model, Vec<fruit::Model>)> =
|
|
Cake::find().find_with_related(Fruit).all(db).await?;
|
|
|
|
```
|
|
### Insert
|
|
```rust
|
|
let apple = fruit::ActiveModel {
|
|
name: Set("Apple".to_owned()),
|
|
..Default::default() // no need to set primary key
|
|
};
|
|
|
|
let pear = fruit::ActiveModel {
|
|
name: Set("Pear".to_owned()),
|
|
..Default::default()
|
|
};
|
|
|
|
// insert one
|
|
let pear = pear.insert(db).await?;
|
|
|
|
// insert many
|
|
Fruit::insert_many(vec![apple, pear]).exec(db).await?;
|
|
```
|
|
### Update
|
|
```rust
|
|
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());
|
|
|
|
// update one
|
|
let pear: fruit::ActiveModel = pear.update(db).await?;
|
|
|
|
// update many: 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?;
|
|
|
|
```
|
|
### Save
|
|
```rust
|
|
let banana = fruit::ActiveModel {
|
|
id: Unset(None),
|
|
name: Set("Banana".to_owned()),
|
|
..Default::default()
|
|
};
|
|
|
|
// create, because primary key `id` is `Unset`
|
|
let mut banana = banana.save(db).await?;
|
|
|
|
banana.name = Set("Banana Mongo".to_owned());
|
|
|
|
// update, because primary key `id` is `Set`
|
|
let banana = banana.save(db).await?;
|
|
|
|
```
|
|
### Delete
|
|
```rust
|
|
let orange: Option<fruit::Model> = Fruit::find_by_id(1).one(db).await?;
|
|
let orange: fruit::ActiveModel = orange.unwrap().into();
|
|
|
|
// delete one
|
|
fruit::Entity::delete(orange).exec(db).await?;
|
|
// or simply
|
|
orange.delete(db).await?;
|
|
|
|
// delete many: DELETE FROM "fruit" WHERE "fruit"."name" LIKE 'Orange'
|
|
fruit::Entity::delete_many()
|
|
.filter(fruit::Column::Name.contains("Orange"))
|
|
.exec(db)
|
|
.await?;
|
|
|
|
```
|
|
|
|
## Learn More
|
|
|
|
1. [Design](https://github.com/SeaQL/sea-orm/tree/master/DESIGN.md)
|
|
1. [Architecture](https://github.com/SeaQL/sea-orm/tree/master/ARCHITECTURE.md)
|
|
1. [Compare with Diesel](https://www.sea-ql.org/SeaORM/docs/internal-design/diesel)
|
|
|
|
## License
|
|
|
|
Licensed under either of
|
|
|
|
- Apache License, Version 2.0
|
|
([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
|
|
- MIT license
|
|
([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
|
|
|
|
at your option.
|
|
|
|
## Contribution
|
|
|
|
Unless you explicitly state otherwise, any contribution intentionally submitted
|
|
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
|
|
dual licensed as above, without any additional terms or conditions.
|