Plans to Revamp SeaORM Tutorial

[billy1624]

We would like to rewrite SeaORM tutorial and align with SeaORM 0.8.0 and beyond.

We're going to have two types of tutorial:

1. The Basics of SeaORM: covers all essentials of SeaORM, including db setup and connection, db migration, generating entity files, CRUD operations, relational selects and mock testing
2. Integrating with SeaORM: showcase how to integrate SeaORM with other framework, including but not limited to Rocket, Actix, Async GraphQL

To make the tutorial more realistic and interesting, we could have theme across our tutorial.

• For example, a chain bakery shop?

The Basics of SeaORM

Table of Content

• Setting up the database: one of MySQL, PostgreSQL, SQLite
• Creating a Cargo workspace for the SeaORM project
• Writing database migration and applying it
• Generating entity files with sea-orm-cli
• Performing CRUD operations
• Selecting related models
• Writing tests with mock interface

Integrating with SeaORM

This would be split into multiple tutorials that depend on prior knowledge of "The Basics of SeaORM".

Frameworks to be included

• Rocket, Actix, Axum...etc (common Web API frameworks): The application could have interfaces for updating the product catalog of bakery shop, or even a point of sales system.
• gRPC, GraphQL (API endpoint): A API for accessing product catalog or sales data via a specific API.

---

Your comments, suggestions and feedbacks are appreciated!
Please leave a comment below and let us know your thoughts :)

CC @tyt2y3

[nahuakang]

I'd be happy to help work out the new tutorials as much as time allows 🥳

One general question:

• What should the style of this tutorial be? For example, should it be formal & concise or informal & verbose? Is there another section of the documentation that should serve as the basis of writing style for this new tutorial series?

Two specific questions:

• Any suggestion on the basic elements that should go into the chain bakery shop so that I or another contributor could start working off from (great idea btw)? 😆
• Do we want to include warp besides Rocket, Actix-Web and Axum? The 3 choices are perfect for me, but I don't know how the community feels given how segmented and unconsolidated (for lack of a better adjective) this part of the Rust ecosystem is. Or we could iterate on additional docs for warp et al. later on, after the entire tutorial is published.

From my part, I've not worked with gRPC or GraphQL yet. Could use support there.

[billy1624]

Hey @nahuakang,

• It's okay to be informal, and I would say the content should be verbose enough for newcomers but not lengthy. It's assumed reader have no prior knowledge on SeaORM but with basic understanding on ORM and Rust. We can point user to https://www.sea-ql.org/SeaORM/ for details and explanations.
• I would leave the design of db schema for your imagination lolll. To demonstrate relational selects, it requires at least two tables. We could starts with two tables that would be sufficient for the tutorial while keeping it simple.
• Definitely, we could include wrap in the integration tutorial. But yeah, we can focus on first part of the tutorial

Let me know your thoughts :)

[billy1624]

Hey @nahuakang, @shpun817 and I will take on this task :)

[shpun817]

Proposed outline of the revamped tutorial:

SeaORM Tutorials

Introduction

Chapter 1 - Building a Backend with SeaORM

• Chapter 1 - Building a Backend with SeaORM
  • Project Setup
  • Migration (CLI)
  • Migration (API)
  • Optional: Generate Entity from Existing Database
  • Basic CRUD Operations
  • Relational Select
  • Testing with Mock Interface
  • Optional: Building SQL Queries with SeaQuery

Chapter 2 - Integration with Rocket

• Chapter 2 - Integration with Rocket
  • Project Setup
  • Connect to Database
  • Error Handling
  • Web API Integration

Chapter 3 - Integration with GraphQL

• Chapter 3 - Integration with GraphQL

[billy1624]

We still have chapter 3 and more

[billy1624]

More tutorials are welcomed! e.g. advanced topics in SeaORM, step-by-step integration example for SeaORM with frameworks such as gRPC, etc.

[nahuakang]

The new tutorial looks amazing 🥇 (sorry I didn't help out at all). I'll read it as soon as I can and give feedback from the view of a new user :)

[billy1624]

Hey @nahuakang, no worries! Please let us know your thoughts on the new SeaORM tutorials :)

[nahuakang]

I left some edits on Chapter 1: #18. Overall this chapter gave a very smooth introduction to how to link up sea-orm with a cargo project and is a significant upgrade for me.

https://www.sea-ql.org/sea-orm-tutorial/ch01-08-sql-with-sea-query.html is perhaps the most confusing to me. Some lines, such as Invoke values_panic() for each row, seem confusing to me and I struggle to see the benefits of using SeaQuery over raw SQL or SeaORM. Maybe we could add some paragraphs on why and when SeaQuery will shine?

Edit: I think sea-query README emphasizes the advantage of SeaQuery very well so maybe a few sentences copied from the README would work already 😄

[billy1624]

I think using SeaQuery to construct query statement while executing it on SeaORM gives you flexibility over the query building while ease the difficulty of managing the connection and mapping query result into struct.

[timuchen]

Hello! I think you should pay attention to how Relational Query works.

https://www.sea-ql.org/sea-orm-tutorial/ch03-02-query.html

// src/schema.rs

+ #[ComplexObject]
+ impl bakery::Model {
+   async fn chefs(&self, ctx: &Context<'_>) -> Result<Vec<chef::Model>, DbErr> {
+       let db = ctx.data::<DatabaseConnection>().unwrap();
+
+       self.find_related(Chef).all(db).await
+   }
+ }

// src/entities/bakery.rs

#[derive(Clone, Debug, PartialEq, DeriveEntityModel, SimpleObject)]
+ #[graphql(complex, name = "Bakery")]
#[sea_orm(table_name = "bakery")]
pub struct Model {

I get:
Inherent impl cannot be defined for a type outside its containing crate [E0116]

Obviously, it is necessary to describe a different approach, since we want to move the GraphQl logic to another crate.

When we add a ComplexObject directly to an Entity, we lose context.

[billy1624]

Interesting. If you look at the full source code (https://www.sea-ql.org/sea-orm-tutorial/ch03-00-integration-with-graphql.html) The impl is actually on reside in the same crate where the entity is defined.