[SeaORM] Pin 1.0.x docs

Author: billy1624

SeaORM/versioned_docs/version-1.0.x/01-index.md

@@ -0,0 +1,141 @@
+# Index
+
+## Introduction
+
+1. Introduction
+
+    1.1. [What is an ORM](01-introduction/01-orm.md)
+
+    1.2. [Async Programming in Rust](01-introduction/02-async.md)
+
+    1.3. [SeaORM Concepts](01-introduction/03-sea-orm.md)
+
+    1.4. [Tutorial & Examples](01-introduction/04-tutorial.md)
+
+## Basics
+
+2. Installation & Configuration
+
+    2.1 [Choosing a Database & Async Runtime](02-install-and-config/01-database-and-async-runtime.md)
+
+    2.2 [Connection Pool](02-install-and-config/02-connection.md)
+
+    2.3 [Debug Log](02-install-and-config/03-debug-log.md)
+
+3. Migration
+
+    3.1 [Setting Up Migration](03-migration/01-setting-up-migration.md)
+
+    3.2 [Writing Migration](03-migration/02-writing-migration.md)
+
+    3.3 [Running Migration](03-migration/03-running-migration.md)
+
+    3.4 [Seeding Data](03-migration/04-seeding-data.md)
+
+4. Generating Entities
+
+    4.1 [Using `sea-orm-cli`](04-generate-entity/01-sea-orm-cli.md)
+
+    4.2 [Entity Structure](04-generate-entity/02-entity-structure.md)
+
+    4.3 [Expanded Entity Structure](04-generate-entity/03-expanded-entity-structure.md)
+
+    4.4 [Enumeration](04-generate-entity/04-enumeration.md)
+
+    4.5 [New Type](04-generate-entity/05-newtype.md)
+
+5. Basic CRUD
+
+    5.1 [Basic Schema](05-basic-crud/01-basic-schema.md)
+
+    5.2 [SELECT: find, filter, sort, paging](05-basic-crud/02-select.md)
+
+    5.3 [INSERT: Model & ActiveModel, insert many](05-basic-crud/03-insert.md)
+
+    5.4 [UPDATE: find & save, update many](05-basic-crud/04-update.md)
+
+    5.5 [SAVE: insert or update](05-basic-crud/05-save.md)
+
+    5.6 [DELETE: delete one & delete many](05-basic-crud/06-delete.md)
+
+    5.7 [JSON](05-basic-crud/07-json.md)
+
+    5.8 [Raw SQL query](05-basic-crud/08-raw-sql.md)
+
+## Advanced Topics
+
+6. Relations
+
+    6.1 [One to One](06-relation/01-one-to-one.md)
+
+    6.2 [One to Many](06-relation/02-one-to-many.md)
+
+    6.3 [Many to Many](06-relation/03-many-to-many.md)
+
+    6.4 [Chained Relations](06-relation/04-chained-relations.md)
+
+    6.5 [Self Referencing](06-relation/05-self-referencing.md)
+
+    6.6 [Custom Join Condition](06-relation/06-custom-join-condition.md)
+
+    6.7 [Data Loader](06-relation/07-data-loader.md)
+
+    6.8 [Bakery Schema](06-relation/08-bakery-schema.md)
+
+7. Writing Tests
+
+    7.1 [Robust & Correct](07-write-test/01-testing.md)
+
+    7.2 [Mock Interface](07-write-test/02-mock.md)
+
+    7.3 [Using SQLite](07-write-test/03-sqlite.md)
+
+8. Advanced Queries
+
+    8.1 [Custom select](08-advanced-query/01-custom-select.md)
+
+    8.2 [Conditional expressions](08-advanced-query/02-conditional-expression.md)
+
+    8.3 [Aggregate functions](08-advanced-query/03-aggregate-function.md)
+
+    8.4 [Custom Joins](08-advanced-query/04-custom-joins.md)
+
+    8.5 [Sub Query](08-advanced-query/05-subquery.md)
+
+    8.6 [Transaction](08-advanced-query/06-transaction.md)
+
+    8.7 [Streaming](08-advanced-query/07-streaming.md)
+
+    8.8 [Custom Active Model](08-advanced-query/08-custom-active-model.md)
+
+    8.9 [Error Handling](08-advanced-query/09-error-handling.md)
+
+9. Schema Statement
+
+    9.1 [Create Table](09-schema-statement/01-create-table.md)
+
+    9.2 [Create Enum](09-schema-statement/02-create-enum.md)
+
+    9.3 [Create Index](09-schema-statement/03-create-index.md)
+
+10. Seaography
+
+    10.1 [🧭 Seaography Intro](10-seaography/01-seaography-intro.md)
+
+    10.2 [Getting Started](10-seaography/02-getting-started.md)
+
+    10.3 [Looking Forward](10-seaography/03-looking-forward.md)
+
+11. Internal Design
+
+    11.1 [Traits and Types](11-internal-design/01-trait-and-type.md)
+
+    11.2 [Derive Macros](11-internal-design/02-derive-macro.md)
+
+    11.3 [Compare with Diesel](11-internal-design/03-diesel.md)
+
+    11.4 [Architecture](11-internal-design/04-architecture.md)
+
+12. What's Next
+
+    12.1 [What's Next](12-whats-next/01-whats-next.md)

SeaORM/versioned_docs/version-1.0.x/01-introduction/01-orm.md

@@ -0,0 +1,13 @@
+# What is an ORM
+
+An Object Relational Mapper (ORM) is a programming library to help you interact with a relational database from an Object-Oriented Programming (OOP) language.
+
+Tables and columns in a database are mapped to objects and attributes, while additional methods allow you to load and store data from and to the database.
+
+Services built in Rust are lightweight (small binary size, low memory usage), safe (with compile-time guarantee), correct (if unit tests are well-designed), and fast (compile-time optimizations minimize runtime overhead).
+
+Due to Rust being a static, strongly typed, compiled, thread-safe, non-garbage-collected, and unconventional object-oriented language, working with an ORM in Rust is a bit different from other scripting languages you are already familiar with.
+
+SeaORM tries to help you in reaping the above benefits while avoiding the hiccups when programming in Rust.
+
+Let's get started.

SeaORM/versioned_docs/version-1.0.x/01-introduction/02-async.md

@@ -0,0 +1,11 @@
+# Async Programming
+
+Async programming in Rust is a recent development, only having been stabilized in Rust [`1.39`](https://github.com/rust-lang/rust/releases/tag/1.39.0). The async ecosystem is rapidly evolving, and SeaORM is one of the first crates built from the ground up with async support in mind.
+
+The first thing to learn is the [`Future`](https://rust-lang.github.io/async-book/02_execution/02_future.html) trait. It's a placeholder for a function that will compute and return some value in the future. It's lazy, meaning `.await` must be called for any actual work to be done. `Future` allows us to achieve concurrency with little programming effort, e.g. [`future::join_all`](https://docs.rs/futures/latest/futures/future/fn.join_all.html) to execute multiple queries in parallel.
+
+Second, `async` in Rust is [multi-threaded programming](https://rust-lang.github.io/async-book/03_async_await/01_chapter.html) with syntactic sugar. A `Future` may move between threads, so any variables used in async bodies must be able to travel between threads, i.e. [`Send`](https://doc.rust-lang.org/nomicon/send-and-sync.html).
+
+Third, there are multiple async runtimes in Rust. [`async-std`](https://crates.io/crates/async-std) and [`tokio`](https://crates.io/crates/tokio) are the two most widely used. SeaORM's underlying driver, [`SQLx`](https://crates.io/crates/sqlx), supports both.
+
+Knowing these concepts is essential to get you up and running in async Rust.

SeaORM/versioned_docs/version-1.0.x/01-introduction/03-sea-orm.md

@@ -0,0 +1,15 @@
+# SeaORM Concepts
+
+In SeaORM, a database with a collection of tables is called a `Schema`.
+
+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`](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`](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`](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`. 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.

SeaORM/versioned_docs/version-1.0.x/01-introduction/04-tutorial.md

@@ -0,0 +1,19 @@
+# Tutorial & Examples
+
+If you prefer a step-by-step tutorial on how to use SeaORM, you can check out our official [SeaORM Tutorial](https://www.sea-ql.org/sea-orm-tutorial/). There are also some good tutorials written by [the community](https://github.com/SeaQL/sea-orm/blob/master/COMMUNITY.md#learning-resources)!
+
+You can also check out [SeaORM Cookbook](https://www.sea-ql.org/sea-orm-cookbook/) for some frequently asked questions and recommended practices of using SeaORM.
+
+If you are so eager and want something grab-and-go, SeaQL maintains a set of official examples contributed by the community (we welcome more!):
+
++ [Actix Example](https://github.com/SeaQL/sea-orm/tree/master/examples/actix_example)
++ [Axum Example](https://github.com/SeaQL/sea-orm/tree/master/examples/axum_example)
++ [GraphQL Example](https://github.com/SeaQL/sea-orm/tree/master/examples/graphql_example)
++ [jsonrpsee Example](https://github.com/SeaQL/sea-orm/tree/master/examples/jsonrpsee_example)
++ [Loco Example](https://github.com/SeaQL/sea-orm/tree/master/examples/loco_example)
++ [Loco REST Starter Example](https://github.com/SeaQL/sea-orm/tree/master/examples/loco_starter)
++ [Poem Example](https://github.com/SeaQL/sea-orm/tree/master/examples/poem_example)
++ [Rocket Example](https://github.com/SeaQL/sea-orm/tree/master/examples/rocket_example)
++ [Salvo Example](https://github.com/SeaQL/sea-orm/tree/master/examples/salvo_example)
++ [Tonic Example](https://github.com/SeaQL/sea-orm/tree/master/examples/tonic_example)
++ [Seaography Example](https://github.com/SeaQL/sea-orm/tree/master/examples/seaography_example)

SeaORM/versioned_docs/version-1.0.x/01-introduction/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Introduction",
+  "collapsed": false
+}

SeaORM/versioned_docs/version-1.0.x/02-install-and-config/01-database-and-async-runtime.md

@@ -0,0 +1,63 @@
+# Database & Async Runtime
+
+:::caution We need your support! ⭐
+Thank you for using SeaORM. Please star our [GitHub repo](https://github.com/SeaQL/sea-orm)! Your support is vital to the continued development and maintenance of SeaORM.
+:::
+
+First, add `sea-orm` to the `[dependencies]` section of `Cargo.toml`.
+
+```toml title="Cargo.toml"
+sea-orm = { version = "1.0.0-rc.5", features = [ <DATABASE_DRIVER>, <ASYNC_RUNTIME>, "macros" ] }
+```
+
+You must choose a `DATABASE_DRIVER` and an `ASYNC_RUNTIME`. `macros` is needed if you use SeaORM's generated entities (most likely).
+
+## DATABASE_DRIVER
+
+You can choose one or more from:
+
++ `sqlx-mysql` - SQLx MySQL and MariaDB
++ `sqlx-postgres` - SQLx PostgreSQL
++ `sqlx-sqlite` - SQLx SQLite
+
+See also: [SQLx docs](https://docs.rs/crate/sqlx/latest/features).
+
+:::tip SQL Server (MSSQL) backend
+
+The installation and configuration of MSSQL driver can be found [here](https://www.sea-ql.org/SeaORM-X/docs/install-and-config/database-and-async-runtime/).
+
+:::
+
+## ASYNC_RUNTIME
+
+You have to choose one from:
+
+`runtime-async-std-native-tls`, `runtime-tokio-native-tls`, `runtime-async-std-rustls`, `runtime-tokio-rustls`
+
+Basically, they are in the form of `runtime-ASYNC_RUNTIME-TLS_LIB`:
+
++ `ASYNC_RUNTIME` can be [`async-std`](https://crates.io/crates/async-std) or [`tokio`](https://crates.io/crates/tokio)
++ `TLS_LIB` can either be [`native-tls`](https://crates.io/crates/native-tls) or [`rustls`](https://crates.io/crates/rustls)
+
+1. Choose the ASYNC_RUNTIME corresponding to your Rust web framework:
+
+| ASYNC_RUNTIME | Web Framework  |
+| :-----------: | :------------: |
+| `async-std` | [`Tide`](https://docs.rs/tide) |
+| `tokio` | [`Axum`](https://docs.rs/axum), [`Actix`](https://actix.rs/), [`Poem`](https://docs.rs/poem), [`Rocket`](https://rocket.rs/) |
+
+2. `native-tls` uses the platform's native security facilities, while `rustls` is an (almost) pure Rust implementation.
+
+## Extra features
+
++ `debug-print` - print every SQL statement to logger
++ `mock` - mock interface for unit testing
++ `macros` - procedural macros for your convenient
++ `with-chrono` - support [`chrono`](https://crates.io/crates/chrono) types
++ `with-time` - support [`time`](https://crates.io/crates/time) types
++ `with-json` - support [`serde-json`](https://crates.io/crates/serde-json) types
++ `with-rust_decimal` - support [`rust_decimal`](https://crates.io/crates/rust_decimal) types
++ `with-bigdecimal` - support [`bigdecimal`](https://crates.io/crates/bigdecimal) types
++ `with-uuid` - support [`uuid`](https://crates.io/crates/uuid) types
++ `postgres-array` - support array types in Postgres (automatically enabled when `sqlx-postgres` feature is turned on)
++ `sea-orm-internal` - opt-in unstable internal APIs (for accessing re-export SQLx types)

SeaORM/versioned_docs/version-1.0.x/02-install-and-config/02-connection.md

@@ -0,0 +1,101 @@
+# Database Connection
+
+To obtain a database connection, use the [`Database`](https://docs.rs/sea-orm/*/sea_orm/struct.Database.html) interface:
+
+```rust
+let db: DatabaseConnection = Database::connect("protocol://username:password@host/database").await?;
+```
+
+`protocol` can be `mysql:`, `postgres:` or `sqlite:`.
+
+`host` is usually `localhost`, a domain name or an IP address.
+
+:::tip
+
+If you can't get `localhost` to work, try putting in an IP address and port number, e.g. `127.0.0.1:3306` or even `192.168.x.x`.
+
+:::
+
+Under the hood, a [`sqlx::Pool`](https://docs.rs/sqlx/0.5/sqlx/struct.Pool.html) is created and owned by [`DatabaseConnection`](https://docs.rs/sea-orm/*/sea_orm/enum.DatabaseConnection.html).
+
+Each time you call `execute` or `query_one/all` on it, a connection will be acquired and released from the pool.
+
+Multiple queries will execute in parallel as you `await` on them.
+
+## Connection String
+
+Here are some tips for database specific options:
+
+### MySQL
+
+Can't think of any
+
+### Postgres
+
+#### Specify a schema
+
+```
+postgres://username:password@host/database?currentSchema=my_schema
+```
+
+### SQLite
+
+#### In memory
+
+```
+sqlite::memory:
+```
+
+#### Create file if not exists
+
+```
+sqlite://path/to/db.sqlite?mode=rwc
+```
+
+#### Read only
+
+```
+sqlite://path/to/db.sqlite?mode=ro
+```
+
+## Connect Options
+
+To configure the connection, use the [`ConnectOptions`](https://docs.rs/sea-orm/*/sea_orm/struct.ConnectOptions.html) interface:
+
+```rust
+let mut opt = ConnectOptions::new("protocol://username:password@host/database");
+opt.max_connections(100)
+    .min_connections(5)
+    .connect_timeout(Duration::from_secs(8))
+    .acquire_timeout(Duration::from_secs(8))
+    .idle_timeout(Duration::from_secs(8))
+    .max_lifetime(Duration::from_secs(8))
+    .sqlx_logging(true)
+    .sqlx_logging_level(log::LevelFilter::Info)
+    .set_schema_search_path("my_schema"); // Setting default PostgreSQL schema
+
+let db = Database::connect(opt).await?;
+```
+
+## Checking Connection is Valid
+
+Checks if a connection to the database is still valid.
+
+```rust
+|db: DatabaseConnection| {
+    assert!(db.ping().await.is_ok());
+    db.clone().close().await;
+    assert!(matches!(db.ping().await, Err(DbErr::ConnectionAcquire)));
+}
+```
+
+## Closing Connection
+
+The connection will be automatically closed on drop. To close the connection explicitly, call the `close` method.
+
+```rust
+let db = Database::connect(url).await?;
+
+// Closing connection here
+db.close().await?;
+```