TeamCity On-Premises 2025.07 Help

迁移到外部数据库

本文介绍了从一种类型的数据库迁移 TeamCity 数据所需的步骤。 有关从第一次启动 TeamCity 开始使用外部数据库，以及一般的外部数据库信息和特定数据库的配置步骤，请参阅 此文章。

最典型的迁移情况是，您使用默认的内部数据库评估了 TeamCity ，并需要切换到外部数据库，以便为您的 TeamCity 安装做好生产使用的准备。 当从一个外部数据库切换到另一个数据库时，也适用推荐的步骤。 您也可以按照它们在同类型的数据库服务器之间进行移动，但在这种情况下，数据库特定的数据传输通常更为可取。

有几种方式可以将数据迁移到新的数据库：

  • 没有数据迁移的切换 ：将保留构建配置设置，但不包括历史构建数据或用户。

  • 完全迁移 ：除了由第三方插件提供的任何数据库存储数据外，所有数据都会被保留。

  • 备份然后恢复 ：与全面迁移相同，但采用了两步方法。

无数据迁移的切换

如果您想快速切换到外部数据库并且 不想保留服务器上的现有数据 ，如用户和构建，请按照以下步骤操作。 切换后，服务器将以空数据库启动，但会保留存储在 TeamCity 数据目录下的所有 设置 （请参阅 详细信息了解存储位置）。

  1. 创建并配置一个外部数据库以供 TeamCity 使用。

  2. 关闭 TeamCity 服务器。

  3. 创建备份副本 ，供服务器使用的 <TeamCity Data Directory>。

  4. 清理 system 目录：您 必须 移除 消息 和 工件 目录，从 system 目录中删除 <TeamCity Data Directory> ；您 可能 删除旧的 HSQLDB 文件： buildserver.* 以移除不再需要的内部存储数据。

  5. 启动 TeamCity 服务器。

全面迁移

这些步骤描述了在保留所有数据的情况下切换到另一个数据库。 这是由 TeamCity 迁移工具 - maintainDB 命令行实用程序完成的。

maintainDB.[cmd|sh] shell/batch 脚本位于 <TeamCity 安装目录>/bin 目录中，用于迁移以及 备份和 恢复 TeamCity 数据。 该实用工具仅在 TeamCity .tar.gz 和 . exe 分发版中可用。

TeamCity 支持 HSQLDB、 MySQL、 Oracle、 PostgreSQL 和 Microsoft SQL Server ；可以在这些数据库之间进行迁移。

迁移过程开始前，目标数据库必须为空（即不得包含任何表）。

将所有现有数据迁移到新的外部数据库：

  1. 创建并配置一个外部数据库供 TeamCity 使用，并将数据库驱动安装到 TeamCity 中。 请勿在此阶段修改任何 TeamCity 设置.

  2. 关闭 TeamCity 服务器。

  3. 使用相应的模板（<TeamCity Data Directory>/config/database.<database_type>.properties.dist ）为目标数据库创建一个具有自定义名称的临时属性文件（例如， 数据库.<database_type>.属性）。 配置属性并将文件放置到任何临时目录中。 请勿修改原始 数据库.<database_type>.属性 文件.

  4. 运行 maintainDB 工具，使用 迁移 命令，并使用 -T 选项指定新创建的目标数据库属性文件的绝对路径：

    maintainDB.[cmd|sh] migrate -T <path to database.properties file>

    如果您没有指向 TeamCity Data Directory 的 TEAMCITY_DATA_PATH 环境，请在命令调用中添加 -A 参数：

    maintainDB.[cmd|sh] migrate -A <path to TeamCity Data Directory> -T <path to database.properties file>

    在数据库迁移成功完成后，临时文件将被复制到 <TeamCity Data Directory>/config/database.properties 文件中，该文件将由 TeamCity 使用。 临时文件可以安全地删除。 如果您正在进行外部数据库之间的迁移，源数据库的原始 database.properties 文件将被通过 -T 选项指定的文件替换。 原始的 database.properties 文件将自动重命名为 database.properties.before.<timestamp>。

  5. 启动 TeamCity 服务器。 这必须与上次运行的 TeamCity 版本相同（TeamCity upgrade 必须作为一个单独的程序进行）。

    在您确认迁移成功后，您 可能 删除旧的 HSQLDB 文件： buildserver.* 以移除不再需要的内部存储数据。

备份与恢复

您可以 创建备份 ，然后使用不同的目标数据库设置 进行恢复。 您可能需要指定恢复选项，以仅恢复数据库数据。

故障排查

  • 在执行迁移期间的扩展信息会被记录在 logs\teamcity-maintenance.log 文件中。 另外， logs\teamcity-maintenance-truncation.log 包含有关迁移过程中可能的数据截断的扩展信息。

  • 如果您遇到 "Out of memory" 错误，尝试增加 -Xmx512m 参数在 maintainDB 脚本中的数字。 在 32 位平台上，最大值约为 1300 MB。
    或者，通过独立模式运行 HSQLDB。

    java -Xmx256M -cp ..\webapps\ROOT\WEB-INF\lib\hsqldb.jar org.hsqldb.Server -database.0 <TeamCity Data Directory>\system\buildserver -dbname.0 buildserver

    然后运行迁移工具，将数据库作为源指向： jdbc:hsqldb:hsql://localhost/buildserver sa''

  • 如果您在运行工具时遇到 "输入行太长" 的错误，更改脚本以使用替代的类路径方法。
    对于 maintainDB.bat ，删除 "将所有 JAR 从 WEB-INF\lib 添加到类路径" 注释下方的行，并取消 "替代类路径：仅添加必要的 JAR" 注释下方行的注释。

最后修改日期： 2025年 8月 12日
设置外部数据库设置 TeamCity 与 MS SQL Server 的连接