River项目与Goose迁移工具的集成实践

背景介绍

River是一个基于Go语言的队列系统，而Goose是一个流行的数据库迁移工具。在实际开发中，很多项目已经使用Goose管理数据库迁移，当引入River时，如何将River的迁移与现有Goose迁移流程集成成为一个需要解决的问题。

迁移机制的变化

River最初提供了MigrateTx方法，允许在单个事务中执行所有迁移。然而，随着项目发展，某些迁移操作无法在单个事务中完成（如创建索引的CONCURRENTLY模式）。因此，River在后续版本中弃用了MigrateTx，改为每个迁移操作使用独立的事务。

当前最佳实践

对于已经使用Goose的项目，可以通过以下方式集成River的迁移：

1. 使用Goose的AddMigrationNoTxContext方法注册迁移函数
2. 在迁移函数中初始化River的迁移器
3. 明确指定目标版本号，确保迁移行为稳定

示例代码如下：

package migrations

import (
	"context"
	"database/sql"

	goose "github.com/pressly/goose/v3"
	"github.com/riverqueue/river/riverdriver/riverdatabasesql"
	"github.com/riverqueue/river/rivermigrate"
)

func init() {
	goose.AddMigrationNoTxContext(UpRiverMigration, DownRiverMigration)
}

func UpRiverMigration(ctx context.Context, db *sql.DB) error {
	migrator, err := rivermigrate.New(riverdatabasesql.New(db), nil)
	if err != nil {
		return err
	}

	_, err = migrator.Migrate(ctx, rivermigrate.DirectionUp, &rivermigrate.MigrateOpts{
		TargetVersion: 6, // 指定River的最新迁移版本
	})
	return err
}

func DownRiverMigration(ctx context.Context, db *sql.DB) error {
	migrator, err := rivermigrate.New(riverdatabasesql.New(db), nil)
	if err != nil {
		return err
	}

	// 回滚时完全移除River的schema
	_, err = migrator.Migrate(ctx, rivermigrate.DirectionDown, &rivermigrate.MigrateOpts{
		TargetVersion: -1,
	})
	return err
}

注意事项

1. 版本控制：必须明确指定TargetVersion参数，避免后续River版本升级时自动应用新迁移
2. 事务隔离：每个River迁移操作会在独立的事务中执行
3. 迁移顺序：建议将River迁移放在Goose迁移序列的适当位置
4. 测试验证：在生产环境使用前，务必在测试环境验证迁移和回滚流程

总结

通过上述方法，开发者可以优雅地将River的数据库迁移集成到现有的Goose迁移流程中。这种方案既保持了现有迁移流程的完整性，又充分利用了River的特有功能。随着River项目的持续发展，建议开发者关注其文档更新，及时调整迁移策略。