From ea88d73e84d3fa8f2946f8a500508e86db9f9f39 Mon Sep 17 00:00:00 2001 From: Chris Tsang Date: Sat, 2 Oct 2021 14:17:40 +0800 Subject: [PATCH] Cleanup Readme --- README.md | 94 ----------------------------- src/docs.rs | 166 ++++++++++++++++++++++++++++++++++++++++++++++++++++ src/lib.rs | 152 +---------------------------------------------- 3 files changed, 167 insertions(+), 245 deletions(-) create mode 100644 src/docs.rs diff --git a/README.md b/README.md index 43daa1d6..b4525b31 100644 --- a/README.md +++ b/README.md @@ -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, Vec) = - 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::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("/?&")] -async fn list( - conn: Connection, - page: Option, - per_page: Option, -) -> 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 diff --git a/src/docs.rs b/src/docs.rs new file mode 100644 index 00000000..bab054ef --- /dev/null +++ b/src/docs.rs @@ -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, Vec) = +//! 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::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("/?&")] +//! async fn list( +//! conn: Connection, +//! page: Option, +//! per_page: Option, +//! ) -> 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, +//! }, +//! ) +//! } +//! ``` \ No newline at end of file diff --git a/src/lib.rs b/src/lib.rs index 734663a4..910044a5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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, Vec) = -//! 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::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("/?&")] -//! async fn list( -//! conn: Connection, -//! page: Option, -//! per_page: Option, -//! ) -> 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::*;