SeaORM 0.9.x Docs - 1 (#38)

* Custom join condition (SeaQL/sea-orm#793) * Migration does not depend on entity crate * Define integer enum with repr[x] syntax * Document datatype mappings (SeaQL/sea-orm#772) * Cursor pagination (SeaQL/sea-orm#754, SeaQL/sea-orm#822) * (de)serialize custom JSON types (SeaQL/sea-orm#794) * Generate new migration file (SeaQL/sea-orm#656) * Skip generating entity file for specific tables (SeaQL/sea-orm#837) * Generate entity with date time crate option (SeaQL/sea-orm#724) * Drop `SelectTwoMany::one()` method (SeaQL/sea-orm#813) * Datatype mappings of primitives (SeaQL/sea-orm#850, SeaQL/sea-schema#75) * Join with table alias (SeaQL/sea-orm#852) * SQLx logging level (SeaQL/sea-orm#800) * Insert with on conflict (SeaQL/sea-orm#791) * Migrate generate should take file name as argument instead of option (SeaQL/sea-orm#870) * Upgrade docusaurus to 2.0.0-beta.22 * What's new in SeaORM 0.9.0 * Move migration section forward * Rename "Generating Database Schema" section to "Generating SeaQuery Statement" * Fix broken links * Edit * Edit * Edit * Edit Co-authored-by: Chris Tsang <chris.2y3@outlook.com>
SeaQL · Jul 17, 2022 · e806f0b · e806f0b
1 parent 27c9ab5
commit e806f0b
Show file tree

Hide file tree

Showing 50 changed files with 9,616 additions and 8,446 deletions.
diff --git a/SeaORM/blog/2022-07-17-whats-new-in-0.9.0.md b/SeaORM/blog/2022-07-17-whats-new-in-0.9.0.md
diff --git a/SeaORM/docs/01-index.md b/SeaORM/docs/01-index.md
@@ -24,23 +24,25 @@
 
     2.4 [Debug Log](02-install-and-config/04-debug-log.md)
 
-3. Generating Entities
+3. Migration
 
-    3.1 [Using `sea-orm-cli`](03-generate-entity/01-sea-orm-cli.md)
+    3.1 [Setting Up Migration](03-migration/01-setting-up-migration.md)
 
-    3.2 [Entity Structure](03-generate-entity/02-entity-structure.md)
+    3.2 [Writing Migration](03-migration/02-writing-migration.md)
 
-    3.3 [Expanded Entity Structure](03-generate-entity/03-expanded-entity-structure.md)
+    3.3 [Running Migration](03-migration/03-running-migration.md)
 
-    3.4 [Enumeration](03-generate-entity/04-enumeration.md)
+    3.4 [Seeding Data](03-migration/04-seeding-data.md)
 
-4. Generating Database Schema
+4. Generating Entities
 
-    4.1 [Create Table](04-generate-database-schema/01-create-table.md)
+    4.1 [Using `sea-orm-cli`](04-generate-entity/01-sea-orm-cli.md)
 
-    4.2 [Create Enum](04-generate-database-schema/02-create-enum.md)
+    4.2 [Entity Structure](04-generate-entity/02-entity-structure.md)
 
-    4.3 [Create Index](04-generate-database-schema/03-create-index.md)
+    4.3 [Expanded Entity Structure](04-generate-entity/03-expanded-entity-structure.md)
+
+    4.4 [Enumeration](04-generate-entity/04-enumeration.md)
 
 5. Basic CRUD
 
@@ -60,55 +62,55 @@
 
 ## Advanced Topics
 
-6. Migration
+6. Relations
 
-    6.1 [Setting Up Migration](06-migration/01-setting-up-migration.md)
+    6.1 [One to One](06-relation/01-one-to-one.md)
 
-    6.2 [Writing Migration](06-migration/02-writing-migration.md)
+    6.2 [One to Many](06-relation/02-one-to-many.md)
 
-    6.3 [Running Migration](06-migration/03-running-migration.md)
+    6.3 [Many to Many](06-relation/03-many-to-many.md)
 
-    6.4 [Seeding Data](06-migration/04-seeding-data.md)
+    6.4 [Chained Relations](06-relation/04-chained-relations.md)
 
-7. Relations
+    6.5 [Self Referencing](06-relation/05-self-referencing.md)
 
-    7.1 [One to One](07-relation/01-one-to-one.md)
+    6.6 [Custom Join Condition](06-relation/06-custom-join-condition.md)
 
-    7.2 [One to Many](07-relation/02-one-to-many.md)
+    6.7 [Bakery Schema](06-relation/07-bakery-schema.md)
 
-    7.3 [Many to Many](07-relation/03-many-to-many.md)
+7. Writing Tests
 
-    7.4 [Chained Relations](07-relation/04-chained-relations.md)
+    7.1 [Robust & Correct](07-write-test/01-testing.md)
 
-    7.5 [Self Referencing](07-relation/05-self-referencing.md)
+    7.2 [Mock Interface](07-write-test/02-mock.md)
 
-    7.6 [Bakery Schema](07-relation/06-bakery-schema.md)
+    7.3 [Using SQLite](07-write-test/03-sqlite.md)
 
-8. Writing Tests
+8. Advanced Queries
 
-    8.1 [Robust & Correct](08-write-test/01-testing.md)
+    8.1 [Custom select](08-advanced-query/01-custom-select.md)
 
-    8.2 [Mock Interface](08-write-test/02-mock.md)
+    8.2 [Conditional expressions](08-advanced-query/02-conditional-expression.md)
 
-    8.3 [Using SQLite](08-write-test/03-sqlite.md)
+    8.3 [Aggregate functions](08-advanced-query/03-aggregate-function.md)
 
-9. Advanced Queries
+    8.4 [Custom Joins](08-advanced-query/04-custom-joins.md)
 
-    9.1 [Custom select](09-advanced-query/01-custom-select.md)
+    8.5 [Sub Query](08-advanced-query/05-subquery.md)
 
-    9.2 [Conditional expressions](09-advanced-query/02-conditional-expression.md)
+    8.6 [Transaction](08-advanced-query/06-transaction.md)
 
-    9.3 [Aggregate functions](09-advanced-query/03-aggregate-function.md)
+    8.7 [Streaming](08-advanced-query/07-streaming.md)
 
-    9.4 [Custom Joins](09-advanced-query/04-custom-joins.md)
+    8.8 [Custom Active Model](08-advanced-query/08-custom-active-model.md)
 
-    9.5 [Sub Query](09-advanced-query/05-subquery.md)
+9. Generating SeaQuery Statement
 
-    9.6 [Transaction](09-advanced-query/06-transaction.md)
+    9.1 [Create Table](09-generate-sea-query-statement/01-create-table.md)
 
-    9.7 [Streaming](09-advanced-query/07-streaming.md)
+    9.2 [Create Enum](09-generate-sea-query-statement/02-create-enum.md)
 
-    9.8 [Custom Active Model](09-advanced-query/08-custom-active-model.md)
+    9.3 [Create Index](09-generate-sea-query-statement/03-create-index.md)
 
 10. Internal Design
 

diff --git a/SeaORM/docs/01-introduction/03-sea-orm.md b/SeaORM/docs/01-introduction/03-sea-orm.md
@@ -2,14 +2,14 @@
 
 In SeaORM, a database with a collection of tables is called a `Schema`.
 
-Each table corresponds to an [`Entity`](03-generate-entity/02-entity-structure.md#entity) in SeaORM, which helps you perform `CRUD` (Create, Read, Update, and Delete) operations on relevant tables.
+Each table corresponds to an [`Entity`](04-generate-entity/02-entity-structure.md#entity) in SeaORM, which helps you perform `CRUD` (Create, Read, Update, and Delete) operations on relevant tables.
 
-The `Entity` trait provides an API for you to inspect its properties ([`Column`](03-generate-entity/02-entity-structure.md#column), [`Relation`](03-generate-entity/02-entity-structure.md#relation) and [`PrimaryKey`](03-generate-entity/02-entity-structure.md#primary-key)) at runtime.
+The `Entity` trait provides an API for you to inspect its properties ([`Column`](04-generate-entity/02-entity-structure.md#column), [`Relation`](04-generate-entity/02-entity-structure.md#relation) and [`PrimaryKey`](04-generate-entity/02-entity-structure.md#primary-key)) at runtime.
 
 Each table has multiple columns, which are referred to as `attribute`.
 
-These attributes and their values are grouped in a Rust struct (a [`Model`](03-generate-entity/03-expanded-entity-structure.md#model)) so that you can manipulate them.
+These attributes and their values are grouped in a Rust struct (a [`Model`](04-generate-entity/03-expanded-entity-structure.md#model)) so that you can manipulate them.
 
-However, `Model` is for read operations only. To perform insert, update, or delete, you need to use [`ActiveModel`](03-generate-entity/03-expanded-entity-structure.md#active-model) which attaches meta-data on each attribute.
+However, `Model` is for read operations only. To perform insert, update, or delete, you need to use [`ActiveModel`](04-generate-entity/03-expanded-entity-structure.md#active-model) which attaches meta-data on each attribute.
 
 Finally, there is no singleton (global context) in SeaORM. Application code is responsible for managing the ownership of the [`DatabaseConnection`](02-install-and-config/03-connection.md). We do provide integration examples for web frameworks including [Rocket](https://github.com/SeaQL/sea-orm/tree/master/examples/rocket_example), [Actix](https://github.com/SeaQL/sea-orm/tree/master/examples/actix_example), [axum](https://github.com/SeaQL/sea-orm/tree/master/examples/axum_example) and [poem](https://github.com/SeaQL/sea-orm/tree/master/examples/poem_example) to help you get started quickly.
diff --git a/SeaORM/docs/02-install-and-config/02-schema.md b/SeaORM/docs/02-install-and-config/02-schema.md
@@ -1,5 +1,5 @@
 # Schema Management
 
-If you already have a database with tables and data, you can skip this section and move on to [generating SeaORM entities](03-generate-entity/01-sea-orm-cli.md).
+If you already have a database with tables and data, you can skip this section and move on to [generating SeaORM entities](04-generate-entity/01-sea-orm-cli.md).
 
-If you are starting from a fresh database, it's actually better to version control your database schema with a migration tool. Follow the steps in [migration docs](/SeaORM/docs/migration/setting-up-migration) to write the migration and run it to create tables in the database. Then, read on [generating SeaORM entities](03-generate-entity/01-sea-orm-cli.md).
+If you are starting from a fresh database, it's actually better to version control your database schema with a migration tool. Follow the steps in [migration docs](/SeaORM/docs/migration/setting-up-migration) to write the migration and run it to create tables in the database. Then, read on [generating SeaORM entities](04-generate-entity/01-sea-orm-cli.md).
diff --git a/SeaORM/docs/02-install-and-config/03-connection.md b/SeaORM/docs/02-install-and-config/03-connection.md
@@ -27,7 +27,8 @@ opt.max_connections(100)
     .connect_timeout(Duration::from_secs(8))
     .idle_timeout(Duration::from_secs(8))
     .max_lifetime(Duration::from_secs(8))
-    .sqlx_logging(true);
+    .sqlx_logging(true)
+    .sqlx_logging_level(log::LevelFilter::Info);
 
 let db = Database::connect(opt).await?;
 ```
diff --git a/...s/06-migration/01-setting-up-migration.md → ...s/03-migration/01-setting-up-migration.md b/...s/06-migration/01-setting-up-migration.md → ...s/03-migration/01-setting-up-migration.md
@@ -6,19 +6,15 @@ Version control your database schema with migrations written in SeaQuery or SQL.
 
 A table named `seaql_migrations` will be created in your database to keep track of the applied migrations. It will be created automatically when you run the migration.
 
-```rust
-#[derive(Clone, Debug, PartialEq, DeriveEntityModel)]
-#[sea_orm(table_name = "seaql_migrations")]
-pub struct Model {
-    #[sea_orm(primary_key, auto_increment = false)]
-    pub version: String,
-    pub applied_at: i64,
-}
-```
-
 ## Creating Migration Directory
 
-Setup the migration directory by executing `sea-orm-cli migrate init`.
+First, install `sea-orm-cli` with `cargo`.
+
+```shell
+$ cargo install sea-orm-cli
+```
+
+Then, setup the migration directory by executing `sea-orm-cli migrate init`.
 
 ```shell
 # Setup the migration directory in `./migration`
@@ -51,14 +47,46 @@ migration
 
 It is recommended to structure your cargo workspace as follows to share SeaORM entities between the app crate and the migration crate. Checkout the [integration examples](https://github.com/SeaQL/sea-orm/tree/master/examples) for demonstration.
 
+### Migration Crate
+
+Import the [`sea-orm-migration`](https://crates.io/crates/sea-orm-migration) and [`async-std`](https://crates.io/crates/async-std) crate.
+
+```toml title="migration/Cargo.toml"
+[dependencies]
+async-std = { version = "^1", features = ["attributes", "tokio1"] }
+sea-orm-migration = { version = "^0" }
+```
+
+Let's write a migration. Detailed instructions in the next section.
+
+```rust title="migration/src/m20220120_000001_create_post_table.rs"
+use sea_orm_migration::prelude::*;
+
+#[derive(DeriveMigrationName)]
+pub struct Migration;
+
+#[async_trait::async_trait]
+impl MigrationTrait for Migration {
+    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        // Replace the sample below with your own migration scripts
+        todo!();
+    }
+
+    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
+        // Replace the sample below with your own migration scripts
+        todo!();
+    }
+}
+```
+
 ### Entity Crate
 
 Create an entity crate in your root workspace.
 
 <details>
     <summary>You don't have SeaORM entities defined?</summary>
 
-You can create an entity crate with no entity files. Then, write the migration and run it to create tables in the database. Finally, [generate SeaORM entities](03-generate-entity/01-sea-orm-cli.md) with `sea-orm-cli` and output the entity files to `entity/src/entities` folder.
+You can create an entity crate without any entity files. Then, write the migration and run it to create tables in the database. Finally, [generate SeaORM entities](04-generate-entity/01-sea-orm-cli.md) with `sea-orm-cli` and output the entity files to `entity/src/entities` folder.
 
 After generating the entity files, you can re-export the generated entities by adding following lines in `entity/src/lib.rs`:
 
@@ -83,61 +111,6 @@ Specify SeaORM dependency.
 sea-orm = { version = "^0" }
 ```
 
-### Migration Crate
-
-Import the [`sea-orm-migration`](https://crates.io/crates/sea-orm-migration) crate. If you need some SeaORM entities when writing migrations, you can import the entity crate.
-
-```toml title="migration/Cargo.toml"
-[dependencies]
-sea-orm-migration = { version = "^0" }
-entity = { path = "../entity" } # depends on your needs
-```
-
-Let's write a migration. Detailed instructions in the next section.
-
-```rust title="migration/src/m20220120_000001_create_post_table.rs"
-use entity::post::*;
-use sea_orm_migration::prelude::*;
-
-pub struct Migration;
-
-impl MigrationName for Migration {
-    fn name(&self) -> &str {
-        "m20220120_000001_create_post_table"
-    }
-}
-
-#[async_trait::async_trait]
-impl MigrationTrait for Migration {
-    async fn up(&self, manager: &SchemaManager) -> Result<(), DbErr> {
-        manager
-            .create_table(
-                Table::create()
-                    .table(Entity)
-                    .if_not_exists()
-                    .col(
-                        ColumnDef::new(Column::Id)
-                            .integer()
-                            .not_null()
-                            .auto_increment()
-                            .primary_key(),
-                    )
-                    .col(ColumnDef::new(Column::Title).string().not_null())
-                    .col(ColumnDef::new(Column::Text).string().not_null())
-                    .to_owned(),
-            )
-            .await
-    }
-
-    // if you are against backward migrations, you do not have to impl this
-    async fn down(&self, manager: &SchemaManager) -> Result<(), DbErr> {
-        manager
-            .drop_table(Table::drop().table(Entity).to_owned())
-            .await
-    }
-}
-```
-
 ### App Crate
 
 This is where the application logic goes.