Que迁移指南：从0.x到2.x的无缝升级策略

Que迁移指南：从0.x到2.x的无缝升级策略

【免费下载链接】queA Ruby job queue that uses PostgreSQL's advisory locks for speed and reliability.项目地址: https://gitcode.com/gh_mirrors/qu/que

Que作为一款基于PostgreSQL advisory locks的Ruby任务队列，从0.x版本到2.x版本经历了重大架构升级。本指南将帮助你安全、平稳地完成从旧版本到最新版的迁移，避免常见陷阱并确保业务连续性。

迁移前的关键准备

在开始升级流程前，请确保完成以下检查：

• 备份数据库：执行pg_dump命令备份整个数据库，特别是que_jobs表及其关联数据
• 检查Ruby版本：Que 2.x要求Ruby 3.0或更高版本，需先完成Ruby环境升级
• 更新依赖：确保Rails/ActiveRecord版本至少为6.0，Sequel版本至少为5.0

分阶段升级路线图

阶段一：升级至1.x最新版

直接跳至2.x版本会导致兼容性问题，必须先升级到1.x系列的最终版本：

# Gemfile gem 'que', '~> 1.0' # 更新至最新1.x版本

执行数据库迁移以添加关键的job_schema_version字段：

# db/migrate/[timestamp]_update_que_tables_to_version5.rb class UpdateQueTablesToVersion5 < ActiveRecord::Migration[6.0] def change Que.migrate! end end

该迁移会将现有任务的job_schema_version默认设为1，为后续2.x版本的任务区分奠定基础。

阶段二：部署与验证

完成1.x升级后，需要：

1. 部署更新后的代码并重启所有worker进程
2. 监控任务执行情况至少24小时，确保：
   • 新任务能正常入队和执行
   • que_jobs表中的job_schema_version字段正确设置为1
   • 错误率与升级前保持一致

阶段三：升级至2.x版本

当确认1.x版本稳定运行后，执行以下步骤：

# Gemfile gem 'que', '~> 2.0' # 更新至2.x版本

执行最终数据库迁移：

# db/migrate/[timestamp]_update_que_tables_to_version7.rb class UpdateQueTablesToVersion7 < ActiveRecord::Migration[6.0] def change Que.migrate! end end

处理重大变更

队列名称变更

Que 2.x将默认队列名称从空字符串改为"default"，迁移过程会自动将旧队列任务转移：

-- 迁移前后的队列名称转换 UPDATE que_jobs SET queue = 'default' WHERE queue = '';

错误处理机制升级

错误信息存储方式发生变化，原last_error字段被拆分为两个新字段：

• last_error_message(500字符限制)
• last_error_backtrace(10,000字符限制)

迁移工具会自动处理数据拆分，但需注意长错误信息可能被截断。

任务参数格式调整

2.x版本引入kwargs字段支持关键字参数，原有任务需逐步迁移至新格式：

# 旧格式 Que.enqueue(MyJob, 'arg1', 'arg2') # 新格式 Que.enqueue(MyJob, arg1: 'arg1', arg2: 'arg2')

故障排除与回滚策略

常见问题解决方案

1. 迁移时版本冲突：

   -- 手动设置数据库模式版本（替换VERSION为实际版本号） COMMENT ON TABLE que_jobs IS 'Que DB schema version: VERSION';

2. worker无法启动： 检查que可执行文件路径是否正确，2.x版本将二进制文件移至exe/que

安全回滚流程

如遇严重问题需要回滚：

1. 恢复Gemfile至1.x版本并重新部署
2. 回滚数据库迁移：

   rails db:rollback VERSION=[迁移文件版本号]

3. 重启所有worker进程

迁移后的优化建议

升级完成后，可考虑以下优化措施：

• 启用连接池：通过lib/que/connection_pool.rb配置合适的连接池大小
• 监控改进：集成lib/que/utils/logging.rb提供的增强日志功能
• 性能调优：根据lib/que/worker.rb中的参数调整worker并发数

总结

Que从0.x到2.x的迁移需要遵循严格的分阶段流程，核心是通过1.x版本作为过渡桥梁，实现零停机升级。关键步骤包括数据库模式更新、任务格式迁移和依赖版本调整。通过本指南的步骤，你可以确保升级过程平稳可靠，充分利用新版本带来的性能提升和功能增强。

官方迁移文档可参考项目中的docs/README.md，完整迁移脚本位于lib/que/migrations/目录。

【免费下载链接】queA Ruby job queue that uses PostgreSQL's advisory locks for speed and reliability.项目地址: https://gitcode.com/gh_mirrors/qu/que