SeaQL / SeaQL/seaql.github.io

Docs for Writing a Migration > Enums | Error + improvements needed

Open
#170 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

help wanted
Dominant language
HTML
Stars
24
Forks
68
PR merge metrics
No merged PRs in 30d

Description

I'm finding that the docs are quite vague and confusing, particularly around creating enums in migrations.

The following blocks of code are taken from:
https://www.sea-ql.org/SeaORM/docs/migration/writing-migration/#schema-creation-methods

First off; is there a typo? One section uses Store for the enum value/variant, and the other uses story? I'm assuming these should be the same.

A table is defined and it contains a column that uses an enum type. It's unclear what enumeration or enumeration_null actually does. My initial thought was that this creates the postgres enum type and assigns it to the column, but it doesnt. I now think that the first parameter is the column name, the second is the name of the postgres enum (which needs to be created separately), and the third parameter is the enum members/variants to generate on the generated rust enum? Total guess though.

manager
    .create_table(
        Table::create()
            .table("post")
            .if_not_exists()
            .col(pk_auto("id"))
            .col(string("title"))
            .col(string("text"))
            .col(enumeration_null("category", "category", ["Feed", "Store"]))
    )
    .await

There's a separate section to create a postgres enum data type. It's unclear what the relation is between the above section and the below section. It's also unclear what CategoryEnum is - it's not defined anywhere in the docs, so this example does not compile. Is it a rust enum type, does it require certain attributes or macros? Should it be a string? Why are the values different to the enumeration variants mentioned earlier (different case, and Store vs storey (latter is probably a typo))

manager
    .create_type(
        Type::create()
            .as_enum(CategoryEnum)
            .values(["feed", "story"])
            .to_owned()
    )
    .await?;

If both the second block is needed (to create the postgres type) and the second block is needed (to create a column that uses the type), do we really need to duplicate the values/variants? I cant get my head around why we need to specify the variants when calling enumeration_null if we're specifying the name of the type that it uses - surely they can (and should) be inferred from the type, rather than duplicated whenever we reference that type?

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start at the migration writing page's schema creation methods section and compare the enumeration_null example with the PostgreSQL enum creation example. Clarify the parameters, the role of CategoryEnum, how the two operations relate, and whether the duplicated values are required; correct the inconsistent enum names and ensure the examples compile.

Written by the indexing model from the issue text.

Assessment

Tech stack
postgresql, rust
Domain
databases, documentation
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.