SonarQube数据库从AWS内部PostgreSQL迁移至RDS PostgreSQL遇阻

当前配置 #

Current SonarQube Version: 7.9 (Community Edition)
Current Database: Internal PostgreSQL 12
Target Database: AWS RDS PostgreSQL 13
New SonarQube Instance: 9.9 (Community Edition)

目标 #

将SonarQube 7.9使用的内部PostgreSQL 12数据库中的现有数据迁移至AWS RDS PostgreSQL 13实例，之后将其连接至新的SonarQube 9.9实例。

已执行步骤 #

• 使用pg_dump导出内部PostgreSQL 12数据库的数据；
• 将pg_dump导出的数据恢复至AWS RDS PostgreSQL 13实例；
• 更新SonarQube 9.9实例的sonar.properties文件，使其指向该AWS RDS PostgreSQL 13数据库；
• 尝试启动新的SonarQube 9.9实例。

遇到的问题 #

• Schema Mismatch Error：SonarQube 9.9实例因该错误无法启动；
• 数据不可见：新SonarQube实例中无法看到任何迁移的数据。

问题咨询 #

• 兼容性问题：从SonarQube 7.9（PostgreSQL 12）迁移至SonarQube 9.9（PostgreSQL 13）是否存在已知兼容性问题或遗漏的特定步骤？
• 解决Schema Mismatch错误：升级SonarQube版本并迁移数据库时，解决该错误的推荐步骤是什么？
• pg_dump最佳实践：使用pg_dump进行SonarQube数据库迁移（尤其是跨版本迁移）时，有哪些最佳实践或特定命令？
• SonarQube DB Copy工具：该工具是否适用于此场景？是免费还是需要许可证？
• 升级路径指导：SonarQube文档中提到的“Determining the server upgrade path”具体流程是什么？如何在迁移数据库的同时正确升级SonarQube版本？

解决方案与回答 #

1. 兼容性问题 #

SonarQube 7.9直接跳至9.9存在跨版本Schema差异，这是核心问题。PostgreSQL 12到13本身兼容，但SonarQube对数据库Schema版本要求严格，不能直接将旧版本数据库连接到新版本SonarQube，必须先通过中间LTS版本完成Schema升级，再迁移数据库。另外，SonarQube 9.9支持PostgreSQL 11及以上版本，所以数据库版本本身不存在兼容性问题。

2. 解决Schema Mismatch错误 #

按以下步骤修复：

• 回退操作：备份RDS上的现有数据库，重新搭建SonarQube 7.9实例并连接该数据库，确保和原环境一致；
• 分步升级SonarQube：从7.9 LTS升级到8.9 LTS，再从8.9 LTS升级到9.9 LTS。每一步启动SonarQube时，系统会自动执行Schema升级脚本，必须等升级完成且实例正常启动后，再进行下一步；
• 迁移数据库：升级完成后，用pg_dump导出8.9升级后的数据库，恢复到RDS PostgreSQL 13，最后连接SonarQube 9.9；
• 若要直接修复现有错误：停止SonarQube 9.9，删除RDS上的数据库，重新导入7.9的数据库备份，先启动对应版本的SonarQube完成Schema升级，再迁移。

3. pg_dump最佳实践 #

针对SonarQube数据库迁移，推荐以下命令和注意事项：

• 使用自定义格式导出，保证完整性：

  pg_dump -U sonar_user -Fc -f sonarqube_db.dump sonarqube_db
  

• 导出前必须停止SonarQube实例，避免数据写入导致备份不一致；
• 恢复到RDS时，确保数据库用户拥有完整权限：

  GRANT ALL PRIVILEGES ON DATABASE sonarqube_rds_db TO sonar_user;
  

• 使用pg_restore恢复数据：

  pg_restore -U rds_sonar_user -d sonarqube_rds_db -Fc sonarqube_db.dump
  

• 恢复后检查RDS参数组配置，确保max_connections、shared_buffers等关键参数与原环境兼容。

4. SonarQube DB Copy工具 #

该工具仅适用于同版本SonarQube之间的数据库迁移（比如同版本下从一个PostgreSQL实例迁移到另一个），不适用于跨SonarQube版本的迁移场景。它属于商业版（Developer、Enterprise、Data Center版）功能，社区版无法使用。

5. 升级路径指导 #

"Determining the server upgrade path"的核心流程：

1. 遵循LTS版本递进升级规则：社区版必须从一个LTS版本升级到下一个LTS版本，不能跨跳。比如7.9 LTS → 8.9 LTS → 9.9 LTS是唯一合法路径；
2. 每一步升级要求：
   • 停止旧版本SonarQube；
   • 备份数据库；
   • 安装新版本SonarQube，配置指向现有数据库；
   • 启动新版本，等待自动完成Schema升级（日志显示"Database migration succeeded"）；
   • 验证实例运行正常、数据完整；
3. 结合数据库迁移的正确流程：
   • 先在原数据库环境完成SonarQube分步升级；
   • 升级完成后停止SonarQube，导出升级后的数据库；
   • 将备份恢复到AWS RDS PostgreSQL 13；
   • 配置SonarQube 9.9指向RDS数据库并启动。

内容的提问来源于stack exchange，提问作者martin luther