SeaORM-X

.github/workflows/deploy.yml

@@ -35,6 +35,9 @@ jobs:
             SeaORM/node_modules
             SeaORM/.docusaurus
             SeaORM/build
+            SeaORM-X/node_modules
+            SeaORM-X/.docusaurus
+            SeaORM-X/build
             Blog/node_modules
             Blog/.docusaurus
             Blog/build
@@ -53,6 +56,9 @@ jobs:
       - if: ${{ contains(steps.git-log.outputs.message, '[SeaORM]') || contains(steps.git-log.outputs.message, '[full]') }}
         run: sh build-site.sh SeaORM SeaORM
 
+      - if: ${{ contains(steps.git-log.outputs.message, '[SeaORM-X]') || contains(steps.git-log.outputs.message, '[full]') }}
+        run: sh build-site.sh SeaORM-X SeaORM-X
+
       - if: ${{ contains(steps.git-log.outputs.message, '[Blog]') || contains(steps.git-log.outputs.message, '[full]') }}
         run: sh build-site.sh Blog blog
 

.github/workflows/preview.yml

@@ -31,6 +31,9 @@ jobs:
             SeaORM/node_modules
             SeaORM/.docusaurus
             SeaORM/build
+            SeaORM-X/node_modules
+            SeaORM-X/.docusaurus
+            SeaORM-X/build
             Blog/node_modules
             Blog/.docusaurus
             Blog/build

SeaORM-X/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

SeaORM-X/NOTES.md

@@ -0,0 +1 @@
+cp -r docs/* versioned_docs/version-0.12.x/

SeaORM-X/README.md

@@ -0,0 +1,33 @@
+# SeaORM Documentation
+
+This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+## Installation
+
+```console
+yarn install
+```
+
+## Local Development
+
+```console
+yarn start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+## Build
+
+```console
+yarn build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.
+
+## Deployment
+
+```console
+GIT_USER=<Your GitHub username> USE_SSH=true yarn deploy
+```
+
+If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch.

SeaORM-X/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

SeaORM-X/docs/01-index.md

@@ -0,0 +1,39 @@
+# Index
+
+## Introduction
+
+1. Introduction
+
+    1.1. [What is an ORM](01-introduction/01-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)
+
+3. Migration
+
+    3.1 [Setting Up Migration](03-migration/01-setting-up-migration.md)
+
+    3.3 [Running Migration](03-migration/03-running-migration.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)
+
+5. Basic CRUD
+
+    5.3 [INSERT: Model & ActiveModel, insert many](05-basic-crud/03-insert.md)
+
+## Advanced Topics
+
+11. Internal Design
+
+    11.4 [Architecture](11-internal-design/04-architecture.md)

SeaORM-X/docs/01-introduction/01-orm.md

@@ -0,0 +1,13 @@
+# What is SeaORM X
+
+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 X tries to help you in reaping the above benefits while avoiding the hiccups when programming in Rust and allows you to interact with MSSQL using the fluent API of SeaORM.
+
+Let's get started.

SeaORM-X/docs/01-introduction/04-tutorial.md

@@ -0,0 +1,10 @@
+# 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-x/tree/main/sea-orm-x/examples/mssql_actix_example)
++ [Axum Example](https://github.com/SeaQL/sea-orm-x/tree/main/sea-orm-x/examples/mssql_axum_example)

SeaORM-X/docs/01-introduction/_category_.json

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

SeaORM-X/docs/02-install-and-config/01-database-and-async-runtime.md

@@ -0,0 +1,49 @@
+# Database & Async Runtime
+
+First, add `sea-orm-x` to the `[dependencies]` section of `Cargo.toml`.
+
+```toml title="Cargo.toml"
+sea-orm-x = { version = "0.12", path = "<SEA_ORM_X_ROOT>/sea-orm-x", 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:
+
++ `sqlz-mssql` - SQLz MSSQL
+
+## 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-X/docs/02-install-and-config/02-connection.md

@@ -0,0 +1,84 @@
+# 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 `mssql:`, etc.
+
+`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:1433` or even `192.168.x.x`.
+
+:::
+
+Under the hood, a `sqlz::Pool` 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:
+
+### MSSQL
+
+#### Specify a schema
+
+If the schema is `dbo`, simply write:
+
+```
+mssql://username:password@host/database
+```
+
+Or, specify the schema name by providing an extra `currentSchema` query param.
+
+```
+mssql://username:password@host/database?currentSchema=my_schema
+```
+
+## 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);
+
+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?;
+```

SeaORM-X/docs/02-install-and-config/_category_.json

@@ -0,0 +1,4 @@
+{
+  "label": "Installation & Configuration",
+  "collapsed": false
+}

SeaORM-X/docs/03-migration/01-setting-up-migration.md

@@ -0,0 +1,62 @@
+# Setting Up Migration
+
+## Installing SeaORM X CLI
+
+Install `sea-orm-cli` with `cargo` locally.
+
+```shell
+cargo install --path "<SEA_ORM_X_ROOT>/sea-orm-x/sea-orm-cli"
+```
+
+## Workspace Structure
+
+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-x/tree/main/sea-orm-x/examples) for demonstration.
+
+### Migration Crate
+
+Import the `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"] }
+
+[dependencies.sea-orm-migration]
+version = "0.12"
+path = "<SEA_ORM_X_ROOT>/sea-orm-x/sea-orm-migration"
+features = [
+  # Enable at least one `ASYNC_RUNTIME` and `DATABASE_DRIVER` feature if you want to run migration via CLI.
+  # View the list of supported features at https://www.sea-ql.org/SeaORM/docs/install-and-config/database-and-async-runtime.
+  # e.g.
+  # "runtime-tokio-rustls",  # `ASYNC_RUNTIME` feature
+  # "sqlz-mssql",            # `DATABASE_DRIVER` feature
+]
+```
+
+### Entity Crate
+
+Specify SeaORM X dependency.
+
+```toml title="entity/Cargo.toml"
+[dependencies]
+sea-orm-x = { version = "0.12", path = "<SEA_ORM_X_ROOT>/sea-orm-x" }
+```
+
+### App Crate
+
+This is where the application logic goes.
+
+Create a workspace that contains app, entity and migration crates and import the entity crate into the app crate.
+
+If we want to bundle the migration utility as part of your app, you'd also want to import the migration crate.
+
+```toml title="./Cargo.toml"
+[workspace]
+members = [".", "entity", "migration"]
+
+[dependencies]
+entity = { path = "entity" }
+migration = { path = "migration" } # depends on your needs
+
+[dependencies]
+sea-orm-x = { version = "0.12", path = "<SEA_ORM_X_ROOT>/sea-orm-x", features = [..] }
+```

SeaORM-X/docs/03-migration/03-running-migration.md

@@ -0,0 +1,22 @@
+# Running Migration
+
+## Running Migration on Any MSSQL Schema
+
+By default migration will be run on the `dbo` schema, you can now override it when running migration on the CLI or programmatically.
+
+For CLI, you can specify the target schema with `-s` / `--database_schema` option:
+* via sea-orm-cli: `sea-orm-cli migrate -u mssql://root:root@localhost/database -s my_schema`
+* via SeaORM migrator: `cargo run -- -u mssql://root:root@localhost/database -s my_schema`
+
+You can also run the migration on the target schema programmatically:
+
+```rust
+// With the default `dbo` schema
+let connect_options = ConnectOptions::new("mssql://root:root@localhost/database");
+// Or, override the default schema
+let connect_options = ConnectOptions::new("mssql://root:root@localhost/database?currentSchema=my_schema");
+
+let db = Database::connect(connect_options).await?
+
+migration::Migrator::up(&db, None).await?;
+```

SeaORM-X/docs/03-migration/_category_.json

@@ -0,0 +1,5 @@
+{
+    "label": "Migration",
+    "collapsed": false
+  }
+