caisin/sea-orm
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Cleanup Readme

Browse Source
This commit is contained in:
Chris Tsang 2021-10-02 14:17:40 +08:00
parent 7c82670d12
commit ea88d73e84
3 changed files with 167 additions and 245 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

94
README.md
View File

@ -32,112 +32,18 @@ SeaORM is a relational ORM to help you build light weight and concurrent web ser
Relying on [SQLx](https://github.com/launchbadge/sqlx), SeaORM is a new library with async support from day 1.
```rust
// execute multiple queries in parallel
let cakes_and_fruits: (Vec<cake::Model>, Vec<fruit::Model>) =
futures::try_join!(Cake::find().all(&db), Fruit::find().all(&db))?;
```
2. Dynamic
Built upon [SeaQuery](https://github.com/SeaQL/sea-query), SeaORM allows you to build complex queries without 'fighting the ORM'.
```rust
// build subquery with ease
let cakes_with_filling: Vec<cake::Model> = cake::Entity::find()
.filter(
Condition::any().add(
cake::Column::Id.in_subquery(
Query::select()
.column(cake_filling::Column::CakeId)
.from(cake_filling::Entity)
.to_owned(),
),
),
)
.all(&db)
.await?;
```
3. Testable
Use mock connections to write unit tests for your logic.
```rust
// Setup mock connection
let db = MockDatabase::new(DbBackend::Postgres)
.append_query_results(vec![
vec![
cake::Model {
id: 1,
name: "New York Cheese".to_owned(),
},
],
])
.into_connection();
// Perform your application logic
assert_eq!(
cake::Entity::find().one(&db).await?,
Some(cake::Model {
id: 1,
name: "New York Cheese".to_owned(),
})
);
// Compare it against the expected transaction log
assert_eq!(
db.into_transaction_log(),
vec![
Transaction::from_sql_and_values(
DbBackend::Postgres,
r#"SELECT "cake"."id", "cake"."name" FROM "cake" LIMIT $1"#,
vec![1u64.into()]
),
]
);
```
4. Service Oriented
Quickly build services that join, filter, sort and paginate data in APIs.
```rust
#[get("/?<page>&<posts_per_page>")]
async fn list(
conn: Connection<Db>,
page: Option<usize>,
per_page: Option<usize>,
) -> Template {
// Set page number and items per page
let page = page.unwrap_or(1);
let per_page = per_page.unwrap_or(10);
// Setup paginator
let paginator = Post::find()
.order_by_asc(post::Column::Id)
.paginate(&conn, per_page);
let num_pages = paginator.num_pages().await.unwrap();
// Fetch paginated posts
let posts = paginator
.fetch_page(page - 1)
.await
.expect("could not retrieve posts");
Template::render(
"index",
context! {
page: page,
per_page: per_page,
posts: posts,
num_pages: num_pages,
},
)
}
```
## A quick taste of SeaORM
### Entity

166
src/docs.rs Normal file
View File

@ -0,0 +1,166 @@
//! 1. Async
//!
//! Relying on [SQLx](https://github.com/launchbadge/sqlx), SeaORM is a new library with async support from day 1.
//!
//! ```
//! # use sea_orm::{DbConn, error::*, entity::*, query::*, tests_cfg::*, DatabaseConnection, DbBackend, MockDatabase, Transaction, IntoMockRow};
//! # let db = MockDatabase::new(DbBackend::Postgres)
//! # .append_query_results(vec![
//! # vec![cake::Model {
//! # id: 1,
//! # name: "New York Cheese".to_owned(),
//! # }
//! # .into_mock_row()],
//! # vec![fruit::Model {
//! # id: 1,
//! # name: "Apple".to_owned(),
//! # cake_id: Some(1),
//! # }
//! # .into_mock_row()],
//! # ])
//! # .into_connection();
//! # let _: Result<(), DbErr> = smol::block_on(async {
//! // execute multiple queries in parallel
//! let cakes_and_fruits: (Vec<cake::Model>, Vec<fruit::Model>) =
//! futures::try_join!(Cake::find().all(&db), Fruit::find().all(&db))?;
//! # assert_eq!(
//! # cakes_and_fruits,
//! # (
//! # vec![cake::Model {
//! # id: 1,
//! # name: "New York Cheese".to_owned(),
//! # }],
//! # vec![fruit::Model {
//! # id: 1,
//! # name: "Apple".to_owned(),
//! # cake_id: Some(1),
//! # }]
//! # )
//! # );
//! # assert_eq!(
//! # db.into_transaction_log(),
//! # vec![
//! # Transaction::from_sql_and_values(
//! # DbBackend::Postgres,
//! # r#"SELECT "cake"."id", "cake"."name" FROM "cake""#,
//! # vec![]
//! # ),
//! # Transaction::from_sql_and_values(
//! # DbBackend::Postgres,
//! # r#"SELECT "fruit"."id", "fruit"."name", "fruit"."cake_id" FROM "fruit""#,
//! # vec![]
//! # ),
//! # ]
//! # );
//! # Ok(())
//! # });
//! ```
//!
//! 2. Dynamic
//!
//! Built upon [SeaQuery](https://github.com/SeaQL/sea-query), SeaORM allows you to build complex queries without 'fighting the ORM'.
//!
//! ```
//! # use sea_query::Query;
//! # use sea_orm::{DbConn, error::*, entity::*, query::*, tests_cfg::*};
//! # async fn function(db: DbConn) -> Result<(), DbErr> {
//! // build subquery with ease
//! let cakes_with_filling: Vec<cake::Model> = cake::Entity::find()
//! .filter(
//! Condition::any().add(
//! cake::Column::Id.in_subquery(
//! Query::select()
//! .column(cake_filling::Column::CakeId)
//! .from(cake_filling::Entity)
//! .to_owned(),
//! ),
//! ),
//! )
//! .all(&db)
//! .await?;
//!
//! # Ok(())
//! # }
//! ```
//!
//! 3. Testable
//!
//! Use mock connections to write unit tests for your logic.
//!
//! ```
//! # use sea_orm::{error::*, entity::*, query::*, tests_cfg::*, DbConn, MockDatabase, Transaction, DbBackend};
//! # async fn function(db: DbConn) -> Result<(), DbErr> {
//! // Setup mock connection
//! let db = MockDatabase::new(DbBackend::Postgres)
//! .append_query_results(vec![
//! vec![
//! cake::Model {
//! id: 1,
//! name: "New York Cheese".to_owned(),
//! },
//! ],
//! ])
//! .into_connection();
//!
//! // Perform your application logic
//! assert_eq!(
//! cake::Entity::find().one(&db).await?,
//! Some(cake::Model {
//! id: 1,
//! name: "New York Cheese".to_owned(),
//! })
//! );
//!
//! // Compare it against the expected transaction log
//! assert_eq!(
//! db.into_transaction_log(),
//! vec![
//! Transaction::from_sql_and_values(
//! DbBackend::Postgres,
//! r#"SELECT "cake"."id", "cake"."name" FROM "cake" LIMIT $1"#,
//! vec![1u64.into()]
//! ),
//! ]
//! );
//! # Ok(())
//! # }
//! ```
//!
//! 4. Service Oriented
//!
//! Quickly build services that join, filter, sort and paginate data in APIs.
//!
//! ```ignore
//! #[get("/?<page>&<posts_per_page>")]
//! async fn list(
//! conn: Connection<Db>,
//! page: Option<usize>,
//! per_page: Option<usize>,
//! ) -> Template {
//! // Set page number and items per page
//! let page = page.unwrap_or(1);
//! let per_page = per_page.unwrap_or(10);
//!
//! // Setup paginator
//! let paginator = Post::find()
//! .order_by_asc(post::Column::Id)
//! .paginate(&conn, per_page);
//! let num_pages = paginator.num_pages().await.unwrap();
//!
//! // Fetch paginated posts
//! let posts = paginator
//! .fetch_page(page - 1)
//! .await
//! .expect("could not retrieve posts");
//!
//! Template::render(
//! "index",
//! context! {
//! page: page,
//! per_page: per_page,
//! posts: posts,
//! num_pages: num_pages,
//! },
//! )
//! }
//! ```

152
src/lib.rs
View File

@ -39,169 +39,18 @@
//!
//! Relying on [SQLx](https://github.com/launchbadge/sqlx), SeaORM is a new library with async support from day 1.
//!
//! ```
//! # use sea_orm::{DbConn, error::*, entity::*, query::*, tests_cfg::*, DatabaseConnection, DbBackend, MockDatabase, Transaction, IntoMockRow};
//! # let db = MockDatabase::new(DbBackend::Postgres)
//! # .append_query_results(vec![
//! # vec![cake::Model {
//! # id: 1,
//! # name: "New York Cheese".to_owned(),
//! # }
//! # .into_mock_row()],
//! # vec![fruit::Model {
//! # id: 1,
//! # name: "Apple".to_owned(),
//! # cake_id: Some(1),
//! # }
//! # .into_mock_row()],
//! # ])
//! # .into_connection();
//! # let _: Result<(), DbErr> = smol::block_on(async {
//! // execute multiple queries in parallel
//! let cakes_and_fruits: (Vec<cake::Model>, Vec<fruit::Model>) =
//! futures::try_join!(Cake::find().all(&db), Fruit::find().all(&db))?;
//! # assert_eq!(
//! # cakes_and_fruits,
//! # (
//! # vec![cake::Model {
//! # id: 1,
//! # name: "New York Cheese".to_owned(),
//! # }],
//! # vec![fruit::Model {
//! # id: 1,
//! # name: "Apple".to_owned(),
//! # cake_id: Some(1),
//! # }]
//! # )
//! # );
//! # assert_eq!(
//! # db.into_transaction_log(),
//! # vec![
//! # Transaction::from_sql_and_values(
//! # DbBackend::Postgres,
//! # r#"SELECT "cake"."id", "cake"."name" FROM "cake""#,
//! # vec![]
//! # ),
//! # Transaction::from_sql_and_values(
//! # DbBackend::Postgres,
//! # r#"SELECT "fruit"."id", "fruit"."name", "fruit"."cake_id" FROM "fruit""#,
//! # vec![]
//! # ),
//! # ]
//! # );
//! # Ok(())
//! # });
//! ```
//!
//! 2. Dynamic
//!
//! Built upon [SeaQuery](https://github.com/SeaQL/sea-query), SeaORM allows you to build complex queries without 'fighting the ORM'.
//!
//! ```
//! # use sea_query::Query;
//! # use sea_orm::{DbConn, error::*, entity::*, query::*, tests_cfg::*};
//! # async fn function(db: DbConn) -> Result<(), DbErr> {
//! // build subquery with ease
//! let cakes_with_filling: Vec<cake::Model> = cake::Entity::find()
//! .filter(
//! Condition::any().add(
//! cake::Column::Id.in_subquery(
//! Query::select()
//! .column(cake_filling::Column::CakeId)
//! .from(cake_filling::Entity)
//! .to_owned(),
//! ),
//! ),
//! )
//! .all(&db)
//! .await?;
//!
//! # Ok(())
//! # }
//! ```
//!
//! 3. Testable
//!
//! Use mock connections to write unit tests for your logic.
//!
//! ```
//! # use sea_orm::{error::*, entity::*, query::*, tests_cfg::*, DbConn, MockDatabase, Transaction, DbBackend};
//! # async fn function(db: DbConn) -> Result<(), DbErr> {
//! // Setup mock connection
//! let db = MockDatabase::new(DbBackend::Postgres)
//! .append_query_results(vec![
//! vec![
//! cake::Model {
//! id: 1,
//! name: "New York Cheese".to_owned(),
//! },
//! ],
//! ])
//! .into_connection();
//!
//! // Perform your application logic
//! assert_eq!(
//! cake::Entity::find().one(&db).await?,
//! Some(cake::Model {
//! id: 1,
//! name: "New York Cheese".to_owned(),
//! })
//! );
//!
//! // Compare it against the expected transaction log
//! assert_eq!(
//! db.into_transaction_log(),
//! vec![
//! Transaction::from_sql_and_values(
//! DbBackend::Postgres,
//! r#"SELECT "cake"."id", "cake"."name" FROM "cake" LIMIT $1"#,
//! vec![1u64.into()]
//! ),
//! ]
//! );
//! # Ok(())
//! # }
//! ```
//!
//! 4. Service Oriented
//!
//! Quickly build services that join, filter, sort and paginate data in APIs.
//!
//! ```ignore
//! #[get("/?<page>&<posts_per_page>")]
//! async fn list(
//! conn: Connection<Db>,
//! page: Option<usize>,
//! per_page: Option<usize>,
//! ) -> Template {
//! // Set page number and items per page
//! let page = page.unwrap_or(1);
//! let per_page = per_page.unwrap_or(10);
//!
//! // Setup paginator
//! let paginator = Post::find()
//! .order_by_asc(post::Column::Id)
//! .paginate(&conn, per_page);
//! let num_pages = paginator.num_pages().await.unwrap();
//!
//! // Fetch paginated posts
//! let posts = paginator
//! .fetch_page(page - 1)
//! .await
//! .expect("could not retrieve posts");
//!
//! Template::render(
//! "index",
//! context! {
//! page: page,
//! per_page: per_page,
//! posts: posts,
//! num_pages: num_pages,
//! },
//! )
//! }
//! ```
//!
//! ## A quick taste of SeaORM
//!
//! ### Entity
@ -424,6 +273,7 @@ pub mod query;
pub mod schema;
#[doc(hidden)]
pub mod tests_cfg;
mod docs;
mod util;
pub use database::*;