drizzle-team / drizzle-team/drizzle-orm

[DOCS]: Recommended workflow when migrations fail

Open
#4,639 3 comments 12 reactions 0 assignees View on GitHub
docs
Dominant language
TypeScript
Stars
35.8k
Forks
1.6k
Avg merge
2d 7h
Merged PRs (30d)
4

Description

### Enhancement hasn't been filed before.

- [x] I have verified this enhancement I'm about to request hasn't been suggested before.

### Describe the enhancement you want to request

There are multiple questions about how to debug failed migrations. I thought it would be helpful to aggregate these points and seek guidance on the current best practices for handling failed Drizzle migrations. This issue is therefore different to the others as it is about official documentation not code changes.

**Edit: the created_at timestamp acutally matches the when tag from the _journal.json. My assertion that I had more rows than migrations is wrong. I was just confused because the id had gaps. I assume those gaps come from me adjusting already run migrations (formatting).**

[1](https://github.com/drizzle-team/drizzle-orm/discussions/1696), [2](https://github.com/drizzle-team/drizzle-orm/issues/4422), [3](https://github.com/drizzle-team/drizzle-orm/issues/3410)

Current Challenges:

1. The logs do not clearly indicate which specific migration file failed.
2. It's not immediately obvious which migration was the last to succeed by simply inspecting the __drizzle_migrations table, as it only logs hashes. And in my case there are more rows in the table than I have migrations so I can't asume that the failed migration is the first id that is not in the table. If that is not expected than most of this issue actually not a problem.
3. There is no straightforward way to correlate a row in the __drizzle_migrations table with its corresponding migration file. The hash column doesn't seem to match any generated file content, and its calculation method isn't documented.
4. The official documentation lacks a dedicated section on debugging failed migrations.
5. There appears to be no official guidance on this topic in the project's GitHub issues or discussions.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.