用途:这是 CockroachDB 仓库中针对系统表(system table)结构变更的操作清单。当需要新增、删除或修改系统表的列或索引时,多个文件与 golden 测试产物必须同步更新,遗漏任何一项都会引发难以调试的测试失败。
主要能力与步骤:
- Schema 定义:更新 pkg/sql/catalog/systemschema/system.go 中的建表 schema 字符串与描述符字面量(列、列 ID、family 列名/ID、索引存储列名/ID、NextColumnID)。NextColumnID 必须为最大列 ID 加 1;增删列时需同时更新 family 描述符中的 ColumnNames 与 ColumnIDs;若列需存入二级索引,需同步更新 schema 字符串的 STORING 子句与描述符的 StoreColumnNames/StoreColumnIDs。
- 新表注册(仅新建表时):在 catconstants/constants.go 添加 SystemTableName 常量,在 catprivilege/system.go 注册权限,在 bootstrap/metadata.go 加入描述符,在 backup/system_schema.go 定义备份恢复行为,并在 cli/zip_table_registry.go 决定是否纳入 debug zip。
- 版本门控:在 clusterversion/cockroach_versions.go 新增版本常量并在 versionTable 中映射(Internal 值须为偶数、每次递增 2),同时更新 systemschema/system.go 的 SystemDatabaseSchemaBootstrapVersion。
- 迁移:在 pkg/upgrade/upgrades/ 创建迁移文件与测试文件,在 upgrades.go 注册;必要时在 schema_changes.go 添加旧描述符构造器;新增文件后运行 ./dev gen bazel。
- Golden 文件:必须重新生成而非手工编辑。先更新哈希,再用 --rewrite 运行测试。涉及 bootstrap/testdata/testdata、bootstrap_system、bootstrap_tenant、pg_catalog、crdb_internal_catalog、initial_keys、catkv 测试数据等;新增表时还可能涉及 information_schema、system、doctor、spanconfig 等。
- 文档:新增版本常量会改变版本集群设置默认值,需运行 ./dev gen docs 重新生成。
- 运行时门控:若变更的列/索引在运行时使用,需用 settings.Version.IsActive(ctx, clusterversion.V26_2_MyChange) 判断,保证滚动升级期间混合版本集群可用。
- 验证:去掉 --rewrite 重跑相关测试,并运行迁移测试 ./dev test pkg/upgrade/upgrades -f TestMyMigration -v。
- Rebase 冲突:golden 文件常因并发修改系统表而冲突,处理方式是接受任一侧内容后重新生成,切勿手工合并。
限制:资料未提供该技能的具体安装方式、收费、平台支持或效果数据。