feat(migrations): 改进校验和错误提示和文档

- 增强迁移校验和不匹配的错误信息,提供具体解决方案
- 添加 migrations/README.md 文档说明迁移最佳实践
- 明确迁移不可变原则和正确的修改流程
This commit is contained in:
ianshaw
2025-12-31 18:06:42 -08:00
parent 0fd1e9c5e6
commit eee5c0ac0b
3 changed files with 188 additions and 7 deletions

View File

@@ -127,7 +127,15 @@ func applyMigrationsFS(ctx context.Context, db *sql.DB, fsys fs.FS) error {
if existing != checksum {
// 校验和不匹配意味着迁移文件在应用后被修改,这是危险的。
// 正确的做法是创建新的迁移文件来进行变更。
return fmt.Errorf("migration %s checksum mismatch (db=%s file=%s)", name, existing, checksum)
return fmt.Errorf(
"migration %s checksum mismatch (db=%s file=%s)\n"+
"This means the migration file was modified after being applied to the database.\n"+
"Solutions:\n"+
" 1. Revert to original: git log --oneline -- migrations/%s && git checkout <commit> -- migrations/%s\n"+
" 2. For new changes, create a new migration file instead of modifying existing ones\n"+
"Note: Modifying applied migrations breaks the immutability principle and can cause inconsistencies across environments.",
name, existing, checksum, name, name,
)
}
continue // 迁移已应用且校验和匹配,跳过
}