mirrord 数据库分支(DB Branching)实战:为 Microsoft SQL Server 创建隔离开发分支

原创2026-10-12 13:49:572,311 阅读
文章标签:开发工具云原生CLI

mirrord 数据库分支(DB Branching)实战:为 Microsoft SQL Server 创建隔离开发分支

导读:本文讲解 mirrord 团队版/企业版中的 MSSQL 数据库分支(DB Branching) 功能——让本地进程(或 AI Agent 环境)像连接线上 SQL Server 一样连接一个隔离的克隆分支库,安全地跑迁移、改表结构、做实验,而不触碰共享环境。读完你将掌握 MSSQL 分支的版本要求、mirrord.json 配置写法、三种复制模式(empty / schema / all)、按表过滤数据的克隆方式,以及它与 MySQL/PostgreSQL 分支的关键差异。

一、MSSQL 分支是什么

DB Branching 是 mirrord 的 Team / Enterprise 功能。它的核心思路是:在会话启动时,由 mirrord 在 Kubernetes 集群中创建一个临时分支数据库 Pod,把远程数据库克隆进去,然后把应用读取的连接环境变量重定向到分支库。开发者(或 AI 编码 Agent)在分支上跑 schema 变更、迁移和实验,不会影响同事或共享环境。

对于 Microsoft SQL Server(MSSQL)分支,文档与配置的入口位于 db-branching/mssql.md,通用概念、全部配置字段与会话行为见 DB Branching 总览。

版本与 Helm 开关要求

MSSQL 分支不是开箱即用的,需要满足以下版本组合(db-branching/mssql.md 顶部说明):

组件 最低版本
mirrord operator 3.150.0
mirrord CLI 3.195.0
operator Helm chart 1.57.0

同时必须在 Helm chart 中开启开关:

operator:
  mssqlBranching: true

未开启时,会话会以类似 feature MSSQL branching is not enabled on this mirrord operator 的明确错误失败,而不是静默跳过。

分支落在哪里

与 MySQL、PostgreSQL 等引擎一致,MSSQL 分支位于 Remote (k8s)——即与当前会话 target 同一个 Kubernetes 集群中的临时 Pod(见 DB Branching 总览 的 "Branch Location" 章节)。它不像 Redis 那样支持本地(local)运行,也不像 S3 那样落在云厂商账户里。

二、基础配置:第一个 MSSQL 分支

在 mirrord.json 的 feature.db_branches 数组中添加一条 "type": "mssql" 的条目即可。基础配置示例(源自 db-branching/mssql.md):

{
  "feature": {
    "db_branches": [
      {
        "id": "users-mssql-db",
        "type": "mssql",
        "version": "2022-latest",
        "name": "users-database-name",
        "connection": {
          "url": "DATABASE_URL"
        },
        "copy": {
          "mode": "empty"
        }
      }
    ]
  }
}

各字段含义如下(结合 DB Branching 总览 的 Key Fields 表格):

  • id(可选):分支标识。复用相同 id 且 TTL 未过期时,mirrord 会重连到已有分支而非新建,因此多人可以共享同一个分支。建议使用唯一值(如 UUID)避免误用他人分支。从 mirrord CLI 3.267.0 起,两条会产生同一分支的条目会让 mirrord 拒绝启动会话。
  • type:数据库引擎,MSSQL 固定为 "mssql"。
  • version:数据库引擎版本,作为 operator 默认镜像的 tag。MSSQL 示例中为 "2022-latest"。
  • name(可选):要克隆的远程数据库名。设置后,重写后的连接 URL 形如 .../dbname;省略时 URL 只指向数据库服务器,由应用自行选择数据库。
  • connection.url:描述 mirrord 如何定位源数据库连接信息——可以是一个完整连接 URL 环境变量名,也可以用 params 拆成 host/port/user/password/database 逐个指定(详见下文"连接模式")。
  • copy.mode:克隆策略,默认 "empty",详见下文"复制模式"。

此外还支持通用字段:ttl_secs / ttl_mins(TTL 覆盖,默认 5 分钟,两者互斥)、creation_timeout_secs(分支创建超时,默认 60 秒,超时会返回超时错误,而 ImagePullBackOff 这类不可恢复的 Pod 故障会立即失败)、image(自定义镜像,与 version 互斥)、profile(管理员定义的分支配置模板)等。migrations 字段同样适用于 MSSQL(见下文)。

一个容易犯的错误:db_branches 必须嵌套在顶层 feature 对象下,放到顶层会被忽略。

配置结构在源码中的对应

配置结构的源码定义在 config/src/feature/database_branches/mssql.rs:MssqlBranchConfig 通过 #<a href="https://link.gitcode.com/i/5906aa12e057945b187e3be4d490a395" target="_blank">serde(flatten)] 组合了共享的 BranchBaseConfig(id、ttl_secs 等)、BranchPodConfig(version、image、profile)、DatabaseSourceConfig(connection、name)以及独立的 copy 与 migrations 字段,且带 #[serde(deny_unknown_fields)]——未知字段会被配置校验直接拒绝。operator 侧在 [operator/src/client/database_branches.rs 的 from_mssql 函数中把它转换为 BranchDatabaseSpec,并使用 deterministic_branch_name("mssql", target_namespace, id) 生成确定性的分支名,copy 配置则放入 MssqlOptions { copy } 下发给分支 CRD。

三、连接模式:mirrord 如何找到源数据库

connection 字段描述 mirrord 如何定位源数据库连接信息(Connection Modes 适用于所有引擎,包括 MSSQL)。支持两种形态:

1. 完整连接 URL

一个环境变量持有完整连接串,最简单:

{
  "connection": {
    "url": "DATABASE_URL"
  }
}

url 对象可选 type 字段控制环境变量来源:"env"(默认,target Pod spec 中的直接 env 条目)或 "env_from"(来自 Pod 的 envFrom 的 secretRef / configMapRef)。

2. 独立连接参数(params)

当应用把 host、port、user、password、database 存成独立环境变量时:

{
  "connection": {
    "params": {
      "host": "DB_HOST",
      "port": "DB_PORT",
      "user": "DB_USER",
      "password": "DB_PASSWORD",
      "database": "DB_NAME"
    }
  }
}

每个参数都单独可选——未指定的参数 mirrord 会用引擎默认值填充。MSSQL 的默认值(connection.md 的默认值表):

引擎 端口 用户
MSSQL 1433 sa

host 的默认值对所有数据库都是 localhost。

进阶取值来源

除普通环境变量外,任意参数还可以来自:

  • Kubernetes Secret(仅 params 模式):{ "secret": "rds-credentials", "key": "password", "env_var_name": "DB_PASSWORD" }
  • ConfigMap(仅 params 模式):从 ConfigMap 挂载的 JSON/YAML 配置文件中用 value_selector(如 .database.host)取值
  • Google Secret Manager / AWS Secrets Manager(url 和 params 均可):用 type: gcp_secret_manager / aws_secrets_manager + secret_ref 引用云上密钥
  • 字面量 value:{ "env_var_name": "DB_PASSWORD", "value": "..." },CLI 会把字面量存入 Kubernetes Secret
  • 复合环境变量:value_pattern 正则从单个变量中拆分多个参数(捕获组名须与参数名一致,如 (?P<host>...))
  • 多来源数组:url 或参数可传数组,第一个条目用于定位并克隆源库,会话期间每个条目都会被重写到分支 Pod

四、复制模式(Copy Modes)

copy 字段控制创建 MSSQL 分支时克隆什么数据。三种模式(db-branching/mssql.md):

模式 克隆内容 适用场景
"empty"(默认) 什么都不克隆——没有 schema 也没有数据的空数据库 应用启动时自行初始化 schema 或跑迁移的工作流
"schema" 仅源数据库的表结构(schema),不含数据 测试 schema 变更、只需要结构不需要数据的本地开发
"all" 源数据库的一切——schema 和数据 完整克隆环境数据,用于调试或复现类生产场景

⚠️ 谨慎使用 "mode": "all":只推荐用于非常小或空的数据库。复制大数据集会显著增加分支创建时间和存储占用。

源码中,MssqlBranchCopyConfig 是一个带 #[serde(tag = "mode", rename_all = "lowercase")] 的枚举,只有 Empty、Schema、All 三种变体,且默认值为 Empty(config/src/feature/database_branches/mssql.rs)。MSSQL 的复制机制走引擎内部 dump 流程,这一点在下一节与 MySQL/PostgreSQL 形成鲜明对比。

五、按表过滤的数据克隆(Filtered Data Clone)

开发者可以按表定制克隆内容,只复制特定行或数据子集。过滤配置与 "mode": "schema"(或 "empty")组合使用(db-branching/mssql.md):

{
  "copy": {
    "mode": "schema",
    "tables": {
      "users": {
        "filter": "name = 'alice' OR name = 'bob'"
      },
      "orders": {
        "filter": "created_at > 1759948761"
      }
    }
  }
}

示例效果:

  • 所有表的 schema 都会被克隆;
  • users 表只复制 alice 和 bob 的行;
  • orders 表只复制指定时间戳之后创建的行。

过滤同样可以与 "mode": "empty" 组合:此时只创建并复制列出的表(及其过滤后的数据),其余表全部排除。

注意:过滤与 "mode": "all" 不兼容。如果同时指定,mirrord 会忽略 tables 配置。

在源码层面,每个表的过滤配置是共享的 BranchItemCopyConfig(仅含一个可选 filter: Option<String> 字段,config/src/feature/database_branches.rs),MssqlBranchTableCopyConfig 就是它的类型别名。e2e 测试 tests/go-e2e-mssql-branching/main.go 也验证了这一行为:测试应用连接分支库后对 users 表执行 SELECT COUNT(*) FROM users WHERE active = 1,与全表计数比对,以确认"只复制了过滤后的行"。

MSSQL 与 MySQL/PostgreSQL 的关键差异:不支持 dump_args

{% hint style="info" %} dump_args 字段不支持 MSSQL。 MSSQL 分支使用自己的内部 dump 机制,只有 MySQL 和 PostgreSQL 分支接受自定义 dump 参数(mysqldump / pg_dump 的参数透传,见 MySQL / PostgreSQL 的 Custom Dump Arguments 章节)。 {% endhint %}

六、在分支上自动跑 schema 迁移(migrations)

MSSQL 是支持 migrations 字段的五个引擎之一(MySQL、MariaDB、PostgreSQL、CockroachDB、MSSQL)。该字段让 mirrord 在分支创建时自动对其运行 schema 迁移,使分支带着你的工作区所期望的 schema 就绪(详见 Schema Migrations)。

工作流程:

  1. operator 创建分支数据库 Pod,并按 copy.mode 克隆源 schema/数据(此步与迁移无关);
  2. 分支库可接受连接后,operator 在旁边运行一个一次性 Kubernetes Job 执行迁移——Job 连接的是分支库,绝不连接源库,使用分支自己的管理员凭据;
  3. 只有 Job 成功后分支才变为 Ready,你的会话才在"已迁移完成的分支"上启动;Job 失败则会话中止并打印 Job 日志,应用永远不会跑在半迁移状态的 schema 上。

使用 migrations 要求设置分支的 name 字段。flavor 可选:

{
  "migrations": {
    "flavor": "flyway",
    "path": "./migrations",
    "image": "flyway/flyway:12"
  }
}
  • flyway:版本化 SQL 文件,通过 Flyway 执行;path(本地目录,与 locations 互斥)或 locations + image(镜像内路径)二选一;
  • liquibase:Liquibase changelog,需要 changelog_file(根 changelog),path 与 search_path 互斥;默认镜像 liquibase/liquibase:4.33 自带 SQL Server 驱动;
  • container:运行你自己的迁移镜像/框架 CLI。

由于 "copy": { "mode": "schema" } 只复制表定义而不复制行,若想让迁移工具的历史记录表(如 Flyway 的 flyway_schema_history)跟着迁移历史一起上分支,需要在 copy.tables 中指名该表:

{ "copy": { "mode": "schema", "tables": { "flyway_schema_history": {} } } }

分支的 creation_timeout_secs 覆盖整个启动过程(克隆 + 拉迁移镜像 + 跑迁移),迁移慢或镜像大时记得调大。

七、会话期间的运行行为与分支管理

开启 DB Branching 后,mirrord 会按以下规则运行(DB Branching 总览 的 "Running With DB Branches"):

  1. 用 mirrord 运行应用,并在 mirrord 配置文件中设置 db_branches 字段;

  2. 复用已有分支:若提供的 id 与现有分支匹配且 TTL 未过期,mirrord 复用该分支并提示:

    A branch with this ID already exists for the target database.
    You're about to use it!
    

    (这意味着你连接的是已有分支,而非全新的隔离分支。)若未指定 id 或使用新的 id,则创建全新的空分支;

  3. mirrord 会用分支的连接 URL 覆盖数据库环境变量,应用连接的是分支而非源库,从而降低误写源库的风险;

  4. 分支在 TTL 到期且无人使用时被自动销毁(重连同一分支会延长其生命周期)。

端口转发(Portforwards)

DB Branching 启用时,mirrord 会在会话期间自动为分支 Pod 建立端口转发,例如用 DBeaver、DataGrip 等 GUI SQL 客户端访问分支库。查看当前活跃的分支端口转发:

mirrord db-branches connections

(S3 这类在云账户中创建、没有 Pod 的分支不会建立端口转发。)

分支生命周期与存储

分支管理命令(详见 Branch Management):

# 查看运行中分支的状态(-n 指定命名空间,-A 查看所有)
mirrord db-branches [-n <namespace>] status [name...]

# 销毁分支
mirrord db-branches [-n <namespace>] destroy <name...>
mirrord db-branches [-n <namespace>] destroy --all

从 operator 3.194.0 起,每个分支默认使用独立的 PersistentVolumeClaims(数据目录与 dump 暂存各 20Gi),随分支创建与删除;集群没有默认 StorageClass 时自动回退到节点本地 emptyDir(数据 1Gi / dump 100Mi 上限)。分支 Pod 默认内存上限为 2Gi,复制大库时如需调大可让集群管理员通过 <engine>BranchConfig.dbPod.resources 调整。MSSQL 的对应 Helm 配置块是 operator.mssqlBranchConfig。

FAQ:连接超时

Q:为什么我的连接会超时?

A:默认情况下分支数据库 SSL 是关闭的。请检查你的客户端是否显式请求了 SSL。这正是 e2e 测试 tests/go-e2e-mssql-branching/main.go 中连接串要带 TrustServerCertificate=true 的原因——应用侧需与分支库的 TLS 状态匹配。

八、小结

MSSQL 数据库分支为 SQL Server 开发者提供了一条"既隔离又真实"的本地开发路径:通过 type: "mssql" 一条配置,mirrord 即可在集群中拉起一个克隆分支库,并把应用的 DATABASE_URL 指向它。核心要点可归纳为:

  1. 版本门槛:operator 3.150.0+、CLI 3.195.0+、Helm chart 1.57.0+,并开启 operator.mssqlBranching: true;
  2. 三种复制模式:empty(默认)、schema、all,其中 all 只适合小库;
  3. 按表过滤:tables.<表名>.filter 可与 schema / empty 组合,但与 all 不兼容;
  4. MSSQL 专属差异:不支持 dump_args(MySQL/PostgreSQL 才有);支持 migrations(Flyway / Liquibase / container);
  5. 连接默认值:端口 1433、用户 sa、host localhost;分支库默认关闭 SSL,客户端需与之匹配。

若想继续深入,可以阅读 DB Branching 总览(全部配置字段、分支存储、Branch Config Profiles)、Connection Modes(所有连接取值来源)以及 Schema Migrations(三种迁移 flavor 的完整配置)。

登录后查看全文
mirrord