mirrord 数据库分支(DB Branching)实战:为 Microsoft SQL Server 创建隔离开发分支
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 CLI3.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)。
工作流程:
- operator 创建分支数据库 Pod,并按
copy.mode克隆源 schema/数据(此步与迁移无关); - 分支库可接受连接后,operator 在旁边运行一个一次性 Kubernetes Job 执行迁移——Job 连接的是分支库,绝不连接源库,使用分支自己的管理员凭据;
- 只有 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"):
-
用 mirrord 运行应用,并在 mirrord 配置文件中设置
db_branches字段; -
复用已有分支:若提供的
id与现有分支匹配且 TTL 未过期,mirrord 复用该分支并提示:A branch with this ID already exists for the target database. You're about to use it!(这意味着你连接的是已有分支,而非全新的隔离分支。)若未指定
id或使用新的id,则创建全新的空分支; -
mirrord 会用分支的连接 URL 覆盖数据库环境变量,应用连接的是分支而非源库,从而降低误写源库的风险;
-
分支在 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 指向它。核心要点可归纳为:
- 版本门槛:operator
3.150.0+、CLI3.195.0+、Helm chart1.57.0+,并开启operator.mssqlBranching: true; - 三种复制模式:
empty(默认)、schema、all,其中all只适合小库; - 按表过滤:
tables.<表名>.filter可与schema/empty组合,但与all不兼容; - MSSQL 专属差异:不支持
dump_args(MySQL/PostgreSQL 才有);支持migrations(Flyway / Liquibase / container); - 连接默认值:端口
1433、用户sa、hostlocalhost;分支库默认关闭 SSL,客户端需与之匹配。
若想继续深入,可以阅读 DB Branching 总览(全部配置字段、分支存储、Branch Config Profiles)、Connection Modes(所有连接取值来源)以及 Schema Migrations(三种迁移 flavor 的完整配置)。