docs: insert, update and save return model (SeaQL/sea-orm#339)

docs: rework `ActiveValue` (SeaQL/sea-orm#340) docs: schema_name will always be applied (SeaQL/sea-orm#370) docs: `ActiveModelBehavior::after_save` takes `Model` (SeaQL/sea-orm#339) docs: `Schema::create_enum_from_active_enum` (SeaQL/sea-orm#348) docs: `ModelTrait::delete` (SeaQL/sea-orm#396) docs: codegen SQLite (SeaQL/sea-orm#386) docs: unsigned integers (SeaQL/sea-orm#397) docs: debug log (SeaQL/sea-orm#373) blog: draft "What's new in SeaORM 0.5.0" docs: revert `save` to return Self (SeaQL/sea-orm@d5c9c65) Revert "docs: unsigned integers (SeaQL/sea-orm#397)" This reverts commit ac6d49e. docs: exclude SeaQL/sea-orm#397 in 0.5.0 blog post docs: update landing page examples docs: edit docs: edit docs: fix 0.4.x docs link build: bump docusaurus version to 2.0.0-beta.14
SeaQL · Dec 31, 2021 · ba746b9 · ba746b9
1 parent 98ee7e3
commit ba746b9
Show file tree

Hide file tree

Showing 36 changed files with 14,289 additions and 16,465 deletions.
diff --git a/SeaORM/blog/2021-12-24-whats-new-in-0.5.0.md b/SeaORM/blog/2021-12-24-whats-new-in-0.5.0.md
@@ -0,0 +1,301 @@
+---
+slug: 2021-12-24-whats-new-in-0.5.0
+title: What's new in SeaORM 0.5.0
+author: SeaQL Team
+author_title: Chris Tsang
+author_url: https://github.com/SeaQL
+author_image_url: https://www.sea-ql.org/SeaORM/img/SeaQL.png
+tags: [news]
+---
+
+🎉 We are pleased to release SeaORM [`0.5.0`](https://github.com/SeaQL/sea-orm/releases/tag/0.5.0) today! Here are some feature highlights 🌟:
+
+## Insert and Update Return `Model`
+
+[[#339](https://github.com/SeaQL/sea-orm/pull/339)] As asked and requested by many of our community members. You can now get the refreshed `Model` after insert or update operations. If you want to mutate the model and save it back to the database you can convert it into `ActiveModel` with the method `into_active_model`.
+
+Breaking Changes:
+- Insert or update return `Model` instead of `ActiveModel`
+- Method `ActiveModelBehavior::after_save` takes `Model` as input instead of `ActiveModel`
+
+```rust
+// Construct a `ActiveModel`
+let active_model = ActiveModel {
+    name: Set("Classic Vanilla Cake".to_owned()),
+    ..Default::default()
+};
+// Do insert
+let cake: Model = active_model.insert(db).await?;
+assert_eq!(
+    cake,
+    Model {
+        id: 1,
+        name: "Classic Vanilla Cake".to_owned(),
+    }
+);
+
+// Covert `Model` into `ActiveModel`
+let mut active_model = cake.into_active_model();
+// Change the name of cake
+active_model.name = Set("Chocolate Cake".to_owned());
+// Do update
+let cake: Model = active_model.update(db).await?;
+assert_eq!(
+    cake,
+    Model {
+        id: 1,
+        name: "Chocolate Cake".to_owned(),
+    }
+);
+
+// Do delete
+cake.delete(db).await?;
+```
+
+<div class="row">
+    <div class="col col--6 margin-bottom--md">
+        Proposed by:
+        <br/><br/>
+        <div class="avatar">
+            <a class="avatar__photo-link avatar__photo avatar__photo--sm" href="https://github.com/nicoulaj">
+                <img src="https://avatars.githubusercontent.com/u/3162?v=4" />
+            </a>
+            <div class="avatar__intro">
+                <div class="avatar__name">
+                    Julien Nicoulaud
+                </div>
+            </div>
+        </div>
+        <br/>
+        <div class="avatar">
+            <a class="avatar__photo-link avatar__photo avatar__photo--sm" href="https://github.com/edg-l">
+                <img src="https://avatars.githubusercontent.com/u/15859336?v=4" />
+            </a>
+            <div class="avatar__intro">
+                <div class="avatar__name">
+                    Edgar
+                </div>
+            </div>
+        </div>
+    </div>
+    <div class="col col--6 margin-bottom--md">
+        Contributed by:
+        <br/><br/>
+        <div class="avatar">
+            <a class="avatar__photo-link avatar__photo avatar__photo--sm" href="https://github.com/billy1624">
+                <img src="https://avatars.githubusercontent.com/u/30400950?v=4" />
+            </a>
+            <div class="avatar__intro">
+                <div class="avatar__name">
+                    Billy Chan
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+
+## `ActiveValue` Revamped
+
+[[#340](https://github.com/SeaQL/sea-orm/pull/340)] The `ActiveValue` is now defined as an enum instead of a struct. The public API of it remains unchanged, except `Unset` was deprecated and `ActiveValue::NotSet` should be used instead.
+
+Breaking Changes:
+- Rename method `sea_orm::unchanged_active_value_not_intended_for_public_use` to `sea_orm::Unchanged`
+- Rename method `ActiveValue::unset` to `ActiveValue::not_set`
+- Rename method `ActiveValue::is_unset` to `ActiveValue::is_not_set`
+- `PartialEq` of `ActiveValue` will also check the equality of state instead of just checking the equality of value
+
+```rust
+/// Defines a stateful value used in ActiveModel.
+pub enum ActiveValue<V>
+where
+    V: Into<Value>,
+{
+    /// A defined [Value] actively being set
+    Set(V),
+    /// A defined [Value] remain unchanged
+    Unchanged(V),
+    /// An undefined [Value]
+    NotSet,
+}
+```
+
+<div class="row">
+    <div class="col col--6 margin-bottom--md">
+        Designed by:
+        <br/><br/>
+        <div class="avatar">
+            <a class="avatar__photo-link avatar__photo avatar__photo--sm" href="https://github.com/tyt2y3">
+                <img src="https://avatars.githubusercontent.com/u/1782664?v=4" />
+            </a>
+            <div class="avatar__intro">
+                <div class="avatar__name">
+                    Chris Tsang
+                </div>
+            </div>
+        </div>
+    </div>
+    <div class="col col--6 margin-bottom--md">
+        Contributed by:
+        <br/><br/>
+        <div class="avatar">
+            <a class="avatar__photo-link avatar__photo avatar__photo--sm" href="https://github.com/billy1624">
+                <img src="https://avatars.githubusercontent.com/u/30400950?v=4" />
+            </a>
+            <div class="avatar__intro">
+                <div class="avatar__name">
+                    Billy Chan
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+
+## SeaORM CLI & Codegen Updates
+
+Install latest version of `sea-orm-cli`:
+
+```sh
+cargo install sea-orm-cli
+```
+
+Updates related to entity files generation (`cargo generate entity`):
+
+- [[#348](https://github.com/SeaQL/sea-orm/pull/348)] Discovers and defines PostgreSQL enums
+- [[#386](https://github.com/SeaQL/sea-orm/pull/386)] Supports SQLite database, you can generate entity files from all supported databases including MySQL, PostgreSQL and SQLite
+
+<div class="row">
+    <div class="col col--6 margin-bottom--md">
+        Proposed by:
+        <br/><br/>
+        <div class="avatar">
+            <a class="avatar__photo-link avatar__photo avatar__photo--sm" href="https://github.com/exzachlyvv">
+                <img src="https://avatars.githubusercontent.com/u/46034847?v=4" />
+            </a>
+            <div class="avatar__intro">
+                <div class="avatar__name">
+                    Zachary Vander Velden
+                </div>
+            </div>
+        </div>
+    </div>
+    <div class="col col--6 margin-bottom--md">
+        Contributed by:
+        <br/><br/>
+        <div class="avatar">
+            <a class="avatar__photo-link avatar__photo avatar__photo--sm" href="https://github.com/charleschege">
+                <img src="https://avatars.githubusercontent.com/u/33346042?v=4" />
+            </a>
+            <div class="avatar__intro">
+                <div class="avatar__name">
+                    Charles·Chege
+                </div>
+            </div>
+        </div>
+        <br/>
+        <div class="avatar">
+            <a class="avatar__photo-link avatar__photo avatar__photo--sm" href="https://github.com/billy1624">
+                <img src="https://avatars.githubusercontent.com/u/30400950?v=4" />
+            </a>
+            <div class="avatar__intro">
+                <div class="avatar__name">
+                    Billy Chan
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+
+## Tracing
+
+[[#373](https://github.com/SeaQL/sea-orm/pull/373)] You can trace the query executed by SeaORM with `debug-print` feature enabled and [`tracing-subscriber`](https://crates.io/crates/tracing-subscriber) up and running.
+
+```rust
+pub async fn main() {
+    tracing_subscriber::fmt()
+        .with_max_level(tracing::Level::DEBUG)
+        .with_test_writer()
+        .init();
+
+    // ...
+}
+```
+
+Contributed by:
+
+<div class="row">
+    <div class="col col--6 margin-bottom--md">
+        <div class="avatar">
+            <a class="avatar__photo-link avatar__photo avatar__photo--sm" href="https://github.com/nappa85">
+                <img src="https://avatars.githubusercontent.com/u/7566389?v=4" />
+            </a>
+            <div class="avatar__intro">
+                <div class="avatar__name">
+                    Marco Napetti
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+
+## Sponsor
+
+Our [GitHub Sponsor](https://github.com/sponsors/SeaQL) profile is up! If you feel generous, a small donation will be greatly appreciated.
+
+A big shout out to our sponsors 😇:
+
+<div class="row">
+    <div class="col col--6 margin-bottom--md">
+        <div class="avatar">
+            <a class="avatar__photo-link avatar__photo avatar__photo--sm" href="https://github.com/shanesveller">
+                <img src="https://avatars.githubusercontent.com/u/831?v=4" />
+            </a>
+            <div class="avatar__intro">
+                <div class="avatar__name">
+                    Shane Sveller
+                </div>
+            </div>
+        </div>
+    </div>
+    <div class="col col--6 margin-bottom--md">
+        <div class="avatar">
+            <a class="avatar__photo-link avatar__photo avatar__photo--sm" href="https://github.com/exzachlyvv">
+                <img src="https://avatars.githubusercontent.com/u/46034847?v=4" />
+            </a>
+            <div class="avatar__intro">
+                <div class="avatar__name">
+                    Zachary Vander Velden
+                </div>
+            </div>
+        </div>
+    </div>
+    <div class="col col--6 margin-bottom--md">
+        <div class="avatar">
+            <a class="avatar__photo-link avatar__photo avatar__photo--sm" href="https://github.com/praveenperera">
+                <img src="https://avatars.githubusercontent.com/u/1775346?v=4" />
+            </a>
+            <div class="avatar__intro">
+                <div class="avatar__name">
+                    Praveen Perera
+                </div>
+            </div>
+        </div>
+    </div>
+    <div class="col col--6 margin-bottom--md">
+        <div class="avatar">
+            <a class="avatar__photo-link avatar__photo avatar__photo--sm">
+                <img style={{width: '100%'}} src="data:image/gif;base64,R0lGODlhAQABAIAAAMLCwgAAACH5BAAAAAAALAAAAAABAAEAAAICRAEAOw=="/>
+            </a>
+            <div class="avatar__intro">
+                <div class="avatar__name">
+                    Unnamed Sponsor
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+
+## Community
+
+SeaQL is a community driven project. We welcome you to participate, contribute and together build for Rust's future.
+
+Here is the roadmap for SeaORM [`0.6.x`](https://github.com/SeaQL/sea-orm/milestone/6).
diff --git a/SeaORM/docs/02-install-and-config/01-database-and-async-runtime.md b/SeaORM/docs/02-install-and-config/01-database-and-async-runtime.md
@@ -13,7 +13,7 @@ You must choose a `DATABASE_DRIVER` and an `ASYNC_RUNTIME`. `macros` is needed i
 You can choose one or more from:
 
 + `sqlx-mysql` - SQLx MySQL
-+ `sqlx-postgres` - SQLx Postgres
++ `sqlx-postgres` - SQLx PostgreSQL
 + `sqlx-sqlite` - SQLx SQLite
 
 See also: [SQLx docs](https://docs.rs/crate/sqlx/latest/features).

diff --git a/SeaORM/docs/02-install-and-config/04-debug-log.md b/SeaORM/docs/02-install-and-config/04-debug-log.md
@@ -1,14 +1,14 @@
 # Debug Log
 
-SeaORM (with `debug-print` feature turned on) and SQLx both log debug messages via the [`log`](https://crates.io/crates/log) crate.
+SeaORM (with `debug-print` feature turned on) log debug messages via the [`tracing`](https://crates.io/crates/tracing) crate.
 
-You need to choose one of the [logging implementations](https://docs.rs/log/0.4.14/log/#available-logging-implementations) to capture and view the debug log. To use [`env_logger`](https://crates.io/crates/env_logger), see the snippet below and a complete example [here](https://github.com/SeaQL/sea-orm/blob/master/examples/tokio/src/main.rs).
+You need to setup [`tracing-subscriber`](https://crates.io/crates/tracing-subscriber) to capture and view the debug log. See the snippet below and a complete example [here](https://github.com/SeaQL/sea-orm/blob/master/examples/actix_example/src/main.rs).
 
 ```rust
 pub async fn main() {
-    env_logger::builder()
-        .filter_level(log::LevelFilter::Debug)
-        .is_test(true)
+    tracing_subscriber::fmt()
+        .with_max_level(tracing::Level::DEBUG)
+        .with_test_writer()
         .init();
 
     // ...

diff --git a/SeaORM/docs/03-generate-entity/01-sea-orm-cli.md b/SeaORM/docs/03-generate-entity/01-sea-orm-cli.md
@@ -33,19 +33,22 @@ $ sea-orm-cli generate entity -h
 
 Discover all tables in a database and generate a corresponding SeaORM entity file for each table.
 
-> Generating Entity files from SQLite is not yet supported. You can write the entity files by hand, and then use the Entity to [initialize a database](07-write-test/03-sqlite.md#setup-database-schema).
+Supported databases:
+- MySQL
+- PostgreSQL
+- SQLite
 
 Command line options:
 - `-u` / `--database-url`: database URL (default: DATABASE_URL specified in ENV)
 - `-s` / `--database-schema`: database schema (default: DATABASE_SCHEMA specified in ENV)
-    - For MySQL, this argument is ignored
+    - For MySQL & SQLite, this argument is ignored
     - For PostgreSQL, this argument is optional with default value 'public'
 - `-o` / `--output-dir`: entity file output directory (default: current directory)
 - `-v` / `--verbose`: print debug messages
 - `--include-hidden-tables`: generate entity files from hidden tables (table names starting with an underscore are ignored by default)
-- `--compact-format`: Generate entity file of [compact format](03-generate-entity/02-entity-structure.md) (default: true)
-- `--expanded-format`: Generate entity file of [expanded format](03-generate-entity/03-expanded-entity-structure.md)
-- `--with-serde`: Automatically derive serde Serialize / Deserialize traits for the entity (none, serialize, deserialize, both) (default: none)
+- `--compact-format`: generate entity file of [compact format](03-generate-entity/02-entity-structure.md) (default: true)
+- `--expanded-format`: generate entity file of [expanded format](03-generate-entity/03-expanded-entity-structure.md)
+- `--with-serde`: automatically derive serde Serialize / Deserialize traits for the entity (none, serialize, deserialize, both) (default: none)
 
 ```shell
 # Generate entity files of database `bakery` to `src/entity`

diff --git a/SeaORM/docs/03-generate-entity/02-entity-structure.md b/SeaORM/docs/03-generate-entity/02-entity-structure.md
@@ -29,7 +29,7 @@ The `DeriveEntityModel` macro does all the heavy lifting of defining an `Entity`
 ### Table Name
 
 The `table_name` attribute specifies the corresponding table in the database.
-Optionally, you can also specify the database schema by `schema_name` (Postgres only).
+Optionally, you can also specify the database schema or database name by `schema_name`.
 
 ```rust
 #[sea_orm(table_name = "cake", schema_name = "public")]
@@ -42,7 +42,7 @@ pub struct Model { ... }
 
 The column type will be derived automatically with the following mapping:
 
-| Rust type | Database Type |
+| Rust type | Database Type <br/> ([`ColumnType`](https://docs.rs/sea-orm/0.*/sea_orm/entity/enum.ColumnType.html)) |
 | --------- | ------------- |
 | char | Char |
 | String | String |
@@ -100,7 +100,7 @@ pub id: i32
 
 ### Auto Increment
 
-By default, `auto_increment` is implied. Override by specifying `false`.
+By default, `auto_increment` is implied for `primary_key` column. Override it by specifying `false`.
 
 ```rust
 #[sea_orm(primary_key, auto_increment = false)]
@@ -109,7 +109,7 @@ pub id: i32
 
 ### Composite Key
 
-This is usually the case in junction tables, where a two-column tuple is used as the primary key. Simply annotate multiple columns to define a composite primary key.
+This is usually the case in junction tables, where a two-column tuple is used as the primary key. Simply annotate multiple columns to define a composite primary key. By default, `auto_increment` is `false` for composite key.
 
 ```rust
 pub struct Model {