Jabra Xpress 数据库迁移工具

概述

Jabra Xpress 数据库迁移工具是一款专为自托管Xpress部署设计的数据库管理工具，主要用于数据库架构的创建与更新。该工具需在特定场景下运行：首次部署Xpress时创建数据库架构，或升级现有Xpress部署时更新数据库架构。建议每次升级Xpress部署时运行该工具，并通过-check选项检查待处理迁移，确保数据库结构与当前部署版本一致。

核心功能与特性

• 数据库状态检查：通过-check参数验证数据库是否为最新状态，识别待处理迁移
• 架构管理：支持首次部署时创建数据库架构，以及升级时更新现有架构
• 初始数据填充：通过-seed参数为新数据库填充初始测试数据
• 灵活操作模式：提供命令行参数模式（v4.12.***及以上）和交互式模式，适应不同使用场景

使用场景与适用范围

• 首次部署Xpress：初始化数据库架构，建立基础数据结构
• 升级现有Xpress部署：更新数据库架构，确保与新版本兼容
• 日常维护：升级前检查数据库状态，验证是否需要执行迁移

前提条件

运行工具前需满足以下条件：

• 已设置并运行SQL数据库
• SQL数据库已创建所需的数据库目录（如创建名为xpress的数据库）
• SQL数据库用户具有完全管理员权限，可执行创建、删除表等数据库修改操作
• 运行工具的机器已安装Docker

版本差异

• **v4.12.*及以上版本：支持命令行参数（如-check、-migrate等），可直接通过参数指定操作
• **v4.0.*及以下版本：不支持命令行参数，需通过-interactive进入交互式模式操作

使用方法与配置说明

运行迁移

通过Docker命令运行工具，需将¤CONNSTRING¤替换为SQL连接字符串，¤VERSION¤替换为镜像标签：

docker run -e MSSQLServerConnectionString="¤CONNSTRING¤" -it gnaudio/jabra-xpress-databaseconsoletool:¤VERSION¤ -ARGUMENT

参数说明

交互式模式

对于不支持命令行参数的版本，或需要手动选择操作时，可通过以下命令进入交互式模式：

docker run -e MSSQLServerConnectionString="¤CONNSTRING¤" -it gnaudio/jabra-xpress-databaseconsoletool:¤VERSION¤ -interactive

成功运行后，工具将显示以下选项：

Enter 1 to check the overall database status - if an error is shown the database is not up to date
Enter 2 to create the database or update the database schema
Enter 3 to seed the database - only do this once - if the database is not empty this will fail
Enter 0 to exit

操作步骤

1. 检查数据库状态：输入1，验证数据库是否为最新状态，若显示错误则需执行迁移
2. 执行数据库迁移：输入2，创建或更新数据库架构（首次部署或升级时使用）
3. 填充初始数据：输入3，为新数据库填充测试数据（仅空数据库可用）
4. 退出工具：操作完成且无错误后，输入0退出

故障排除

常见问题：连接失败

工具启动时不会验证连接字符串，仅在执行操作后检查连接。若连接失败，错误信息将输出到控制台，可按以下步骤排查：

1. 验证连接字符串：检查服务器地址、端口、数据库名称、用户名及密码是否正确
2. 网络连接检查：确认网络通畅，防火墙或IP过滤规则未阻止数据库连接
3. 用户权限检查：确保SQL用户具有执行数据库修改（如创建/删除表）的权限