Skip to content

Plans to Revamp SeaORM Tutorial #8

Open

Description

@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

Activity

  1. nahuakang commented on May 25, 2022

    @nahuakang
    Contributor

    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.

  2. billy1624 commented on May 26, 2022

    @billy1624
    MemberAuthor

    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 :)

  3. billy1624 commented on May 31, 2022

    @billy1624
    MemberAuthor

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

  4. shpun817 commented on May 31, 2022

    @shpun817
    Member

    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
  5. linked a pull request that will close this issueRevamp SeaORM Tutorials (Issue #8) #9on Jun 2, 2022
  6. moved this from Triage to In Progress in SeaQL Dev Trackeron Jun 7, 2022
  7. added a commit that references this issue on Jun 27, 2022
  8. billy1624 commented on Jun 27, 2022

    @billy1624
    MemberAuthor

    We still have chapter 3 and more

  9. Repository owner moved this from In Progress to Triage in SeaQL Dev Trackeron Jun 27, 2022
  10. linked a pull request that will close this issueAdd Chapter 3 - GraphQL Integration Example #14on Jul 15, 2022
  11. billy1624 commented on Jul 18, 2022

    @billy1624
    MemberAuthor

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

  12. nahuakang commented on Jul 18, 2022

    @nahuakang
    Contributor

    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 :)

  13. billy1624 commented on Jul 19, 2022

    @billy1624
    MemberAuthor

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

  14. nahuakang commented on Jul 19, 2022

    @nahuakang
    Contributor

    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 😄

  15. billy1624 commented on Jul 25, 2022

    @billy1624
    MemberAuthor

    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.

  16. timuchen commented on Jun 7, 2024

    @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.

  17. billy1624 commented on Jun 27, 2024

    @billy1624
    MemberAuthor

    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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

Type

No type

Projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions