Improve the documentation about migrate workflow

mrdulin commented 4 years ago

Issue Description

It's unclear about how to create associations in migration files when the models have associations with each other.

What was unclear/insufficient/not covered in the documentation

I read the migrations docs and the code of sequelize express-example.

The docs just explain how to create a model and migration file using sequelize-cli. The thing is when people create models and migration files such as User and Task and define associations like this:

// user.js
// ...
  User.associate = function(models) {
    User.hasMany(models.Task);
  }
// ...

// task.js
// ...
  Task.associate = function(models) {
    // Using additional options like CASCADE etc for demonstration
    // Can also simply do Task.belongsTo(models.User);
    Task.belongsTo(models.User, {
      onDelete: "CASCADE",
      foreignKey: {
        allowNull: false
      }
    });
  }
// ...

Now, the models have associations. But, the migration file DOES NOT have associations. This means even if the UserId is added to the Task model. But in the migration file, the Task table doesn't have UserId at this moment.

Here are the workflow steps I current use:

Create migration and model files using sequelize-cli
Define the model and the associations manually based on my business logic.
Back to modify the generated migration file, add the UserId column to xxx-create-task.js file (This is where I'm not sure and confused. But I saw the express-example use this workflow)

So, what's the correct workflow to create associations in migration files?

If possible: Provide some suggestion on how we can enhance the docs

If I understand correctly, the migration file and the model are a different part. This means we have to keep both in sync manually, sequelize and sequelize-cli will not do it for us automatically.
Another issue is to create the join table, sequelize-cli will not create the join table, right? If so, what's the best way to create this join table migration file?

It's different from the sequelize.sync() API. For testing purposes, this API will create tables with correct associations, add UserId column to the Task table based on the models' associations we defined. Besides, it also create join table for many-to-many association too. It seems this API will keep the model and "migration" sync automatically

Additional context

I found a post about this in medium: https://medium.com/@andrewoons/how-to-define-sequelize-associations-using-migrations-de4333bf75a7

It seems the author uses the same workflow as mine

Issue Template Checklist

Is this issue dialect-specific?

[x] No. This issue is relevant to Sequelize as a whole.
[ ] Yes. This issue only applies to the following dialect(s): XXX, YYY, ZZZ
[ ] I don't know.

Would you be willing to resolve this issue by submitting a Pull Request?

[ ] Yes, I have the time and I know how to start.
[x] Yes, I have the time but I don't know how to start, I would need guidance.
[ ] No, I don't have the time, although I believe I could do it if I had the time...
[ ] No, I don't have the time and I wouldn't even know how to start.

readysetawesome commented 3 years ago

As a newcomer to Sequelize, this is a critically important issue with the documentation that is slowing me down more than any other single task as I spin up a new project.

I've regenerated and modified all my migrations and models twice now, inspecting the resulting schema through PG cli, just trying to figure out the "right" way.

I'm getting ready to start over on this project with a different language because of the lack of convention around migrations and models in Sequelize.

github-actions[bot] commented 3 years ago

This issue has been automatically marked as stale because it has been open for 7 days without activity. It will be closed if no further activity occurs. If this is still an issue, just leave a comment or remove the "stale" label. 🙂

sequelize / website