数据库迁移

数据库迁移属于后端应用部署，不属于 Bundle 安装。db-service 提供数据库 Instance、Logical Database、 Profile、Allocation 和连接配置解析；rust-build-service 从项目 Git 的精确提交构建迁移制品并登记到 独立 Artifact Service；Hosted Service 读取已有 artifactId，在目标 Project Environment 上编排、执行 和审计迁移。

以下组件不参与这条链路：Bundle、Module、App Runtime、baijimu-agent、Control Plane 和 release-control。

制品与源码身份

一次带数据库变更的部署最多包含：

• 一个运行 Artifact：rust_binary 或 rust_bundle。
• 一个 Schema Migration Artifact：liquibase_bundle。
• 零个或多个有明确顺序的 Data Migration Artifact：data_migration_bundle。

所有 Artifact 必须属于同一 workspace、同一 Project，并来自同一个非空的完整 sourceCommitId。 平台不接受“运行代码来自一个 commit、迁移来自另一个 commit”的组合，也不会在部署阶段重新构建。

Schema Migration

Schema 迁移目录根部必须包含 changelog.yaml 和 migration.json。migration.json 使用固定协议：

{
  "protocolVersion": "1.0.0",
  "migrationKey": "business-schema",
  "migrationVersion": "2.1.0",
  "ownerComponentKey": "business-service"
}

migrationVersion 必须是规范的 SemVer 2.0.0。构建命令示例：

baijimu rust-build job create <workspaceId> <projectId> \
  --git-commit-id <fullCommitId> \
  --artifact-type liquibase_bundle \
  --binary-path <schemaMigrationDirectory>

Data Migration

Data 迁移目录中只能有一个 manifest.json，当前支持 migration-agent 1.0.0 和 2.0.0 协议。 清单使用与 Schema 迁移相同的四个身份字段，并声明数据库方言、事务、前置检查和有界更新步骤。 精确清单结构以对应 CLI 固定版本文档和构建错误为准，不要从其他版本复制字段。

baijimu rust-build job create <workspaceId> <projectId> \
  --git-commit-id <fullCommitId> \
  --artifact-type data_migration_bundle \
  --binary-path <dataMigrationDirectory>

迁移 BuildJob 成功后读取其真实 artifactId。不要使用 buildJobId、源码目录或对象存储 URI 代替。

随部署执行

baijimu hosted-service project deploy-artifact <workspaceId> <projectId> \
  --environment-id <environmentId> \
  --artifact-id <runtimeArtifactId> \
  --schema-migration-artifact-id <schemaArtifactId> \
  --data-migration-artifact-id <firstDataArtifactId> \
  --data-migration-artifact-id <secondDataArtifactId>

省略迁移参数表示本次部署不执行迁移。多个 Data Migration 参数的出现顺序就是执行顺序。平台在数据库 Allocation 维度串行执行 Schema → Data，全部成功后才部署运行 Artifact 并切换 Endpoint。Data Migration 先 dry-run、冻结候选数，再在单个事务中 apply；同一不可变制品重试幂等，不同制品复用同一迁移版本会失败。

凭据只在当前执行内存和受控子进程中存在，不会写入迁移 Operation、Attempt 或日志。不要把数据库 URL、 密码或 Profile Token 放入源码、Artifact、普通环境 JSON 或部署参数。

状态、失败与恢复

Deployment 记录中的 databaseMigrations 保存按顺序创建的 Migration Operation；每次执行形成只追加的 Attempt。部署请求被接受不代表迁移或服务已成功，必须持续查询 deployment，直到迁移和运行部署都进入 终态，并完成真实业务验证。

迁移失败时，新的运行 Artifact 和 Endpoint 不会切换，旧部署继续服务；但此前已成功提交的数据库变更 不会自动回滚。应用和迁移必须采用 expand/contract 兼容策略，并把失败恢复设计为新的向前迁移：

1. 先增加兼容结构或数据，使新旧程序都可运行。
2. 部署并验证新程序。
3. 确认旧程序和旧数据路径不再使用后，在后续版本中收缩。

不要把破坏性逆向 SQL、手工修改生产库或在应用启动时补跑迁移当作标准回滚机制。