Schema Maintenance

BitzOrcas.SchemaMaintenance 是独立运维 EXE。它不启动 API Host DI，而是收集当前编译期 persistence metadata、构造 SqlSugar SQL Server adapter，再执行 drift check、SafeOnly 脚本生成、迁移应用或 Seed CSV 长度校验。它处理 schema 技术差异，不替代业务数据迁移和发布审批。

日常发版请先跑锁安全 --init-schema（只建缺表、补可空列）。本工具和 Host 控制面 /host/schema 负责残留差异：放宽长度、必填加列、已有表建索引。API Host 循环 operations-schema-drift-notify 会把同一份全量嗅探结果推给 host-admin。本地 persist 脏库整库重建走 AppHost BITZORCAS_ASPIRE_RESET_SCHEMA=true，不是本工具。完整三车道说明见数据库初始化与迁移。

五种模式

一次只能选择一个 mode；手动参数解析遇到多个 mode 时，后出现的覆盖前一个。Runbook 不应利用这种隐式行为，应只传一个。

配置与连接串优先级

Mode、--force、--dry-run 和 output 只从 CLI 解析。连接串优先使用 --connection，否则从 Configuration 读取 ConnectionStrings:Default，再回退 SqlSugar:ConnectionString。Provider 顺序是 appsettings、local、SCHEMA_ 环境变量、命令行。

# 推荐使用环境变量向 Configuration 提供 ConnectionStrings:Default。
export SCHEMA_ConnectionStrings__Default="$TARGET_SQLSERVER_CONNECTION"

# 只读检测；退出 2 表示发现 drift，不是工具崩溃。
dotnet run --project src/Tooling/BitzOrcas.SchemaMaintenance -- \
  --check-schema

源代码帮助文本写有 SCHEMA__ConnectionStrings__Default，但 provider prefix 是 SCHEMA_；自动化前应以隔离测试验证实际环境变量名称。最确定的敏感配置仍是 gitignored appsettings.local.json 或显式 --connection（后者注意 shell history）。

Drift 检测

Runner 通过 DeclaredMetadataCollector.CollectAll() 取得声明实体，比较目标数据库表、列和索引。报告把缺失表标为 blocker，列差异显示声明/实际类型和方向，缺失索引显示名称与列。

# 保存退出码和完整报告，供迁移评审引用。
set +e
dotnet run --project src/Tooling/BitzOrcas.SchemaMaintenance -- \
  --check-schema > schema-drift.log 2>&1
rc=$?
set -e
test "$rc" -eq 0 -o "$rc" -eq 2

Code 0 表示当前 detector 未发现已建模差异；不证明所有数据库对象、触发器、权限或数据质量都正确。Code 2 是“有 drift 且未迁移”的预期业务结果。

生成 SafeOnly 脚本

--generate-migration 固定使用 MigrationSafetyLevel.SafeOnly。--output 为空时 SQL 输出到 stdout；给出路径时直接 File.WriteAllTextAsync，因此目标文件会被覆盖。

# 输出到新建的证据目录，先评审再交给数据库变更流程。
mkdir -p .verify-output/schema
dotnet run --project src/Tooling/BitzOrcas.SchemaMaintenance -- \
  --generate-migration \
  --output .verify-output/schema/safe-migration.sql

# 查阅语句与潜在破坏动作；SafeOnly 也需人工复核锁与容量影响。
sed -n '1,240p' .verify-output/schema/safe-migration.sql
rg -n 'DROP|ALTER COLUMN|NOT NULL|CREATE.*INDEX' \
  .verify-output/schema/safe-migration.sql

无安全语句时工具返回 0，可能是完全无 drift，也可能只剩需确认项；必须同时阅读 drift report。

应用安全迁移

--apply-safe-migrations 只生成/执行 SafeOnly。先加 --dry-run 会打印待执行分类、描述和 SQL，但不调用 executor。

# 在和生产同版本的恢复副本上预演。
dotnet run --project src/Tooling/BitzOrcas.SchemaMaintenance -- \
  --apply-safe-migrations --dry-run

# 经审批后，仍先在隔离目标实际执行。
dotnet run --project src/Tooling/BitzOrcas.SchemaMaintenance -- \
  --apply-safe-migrations

“安全”指生成器分类，不等于零停机。加索引、放宽大表列等操作仍可能持锁、消耗日志和 IO；生产执行需要窗口、监控、备份与回滚策略。

Apply All 与 --force

--apply-all-migrations 未带 --force 使用 WithConfirm；带 --force 使用 FullForce。CLI 没有交互式逐项确认，具体语句由 generator safety level 与 executor 决定。

# 第一步永远 dry run，保存 FullForce 候选 SQL。
dotnet run --project src/Tooling/BitzOrcas.SchemaMaintenance -- \
  --apply-all-migrations --force --dry-run \
  > .verify-output/schema/full-force-preview.log

不要在生产自动化中直接组合 --apply-all-migrations --force。需要确认的数据收缩、删除或不可逆变化应拆成专用 migration、数据回填、兼容窗口与单独回滚计划。

Seed CSV 离线校验

--validate-seed 不需要连接串。它收集已知 seed assemblies，对 CSV 值与声明 metadata 长度比较，报告文件数、行数、表/列、声明长度、实际最大长度、样本和建议。

# Seed Exporter 输出合入候选 Assets 后执行。
dotnet run --project src/Tooling/BitzOrcas.SchemaMaintenance -- \
  --validate-seed

当前 validator 重点是长度问题；通过不证明业务键唯一、依赖完整、PII/Secret 安全或 replay 幂等。这些由 SeedRunner 与集成合同补齐。

独立 EXE 与 Host 的差异

工具手动构造 SqlSugarScope，数据库类型固定 SQL Server，并从编译程序集收集 metadata。它不会复用 API Host 的全部配置、license、tenant middleware 或运行时 provider switch。因此运行结果只适用于 SqlSugar SQL Server schema maintenance，不应宣传为 EF Core/Mongo 通用迁移器。

构建工具的 Commit 必须与目标发布制品一致，否则声明 metadata 可能来自另一个版本。运行前记录 git rev-parse HEAD、SDK、目标 database/schema 与备份标识。

退出码

Apply 方法内部执行失败也返回 99。自动化必须保留完整日志，不能只把非零统一解释为“存在 drift”。

推荐生产流程

1. 用目标发布 Commit 构建 Release 工具。
2. 对生产备份恢复副本运行 check，保存 report。
3. 生成 SafeOnly script，并由 DBA/owner 评审锁、容量和兼容性。
4. 在恢复副本 dry run、实际 apply、再次 check。
5. 运行应用 smoke、双 ORM 合同（若相关）和数据校验。
6. 创建生产前备份，记录 RPO/RTO 与回滚触发条件。
7. 在维护窗口执行批准脚本/安全模式，实时监控。
8. 再次 check，并把 Commit、命令、退出码和报告归档。

评审清单

• 单次命令只选择一个 mode；
• 工具 Commit 与部署版本一致；
• 目标确认是 SQL Server/SqlSugar 合同；
• check report 与 script 都已保存，而非只看退出码；
• --output 不会覆盖未备份的审批制品；
• FullForce 不是无人值守生产步骤；
• 大表索引/列变更有容量、锁与回滚评估；
• Seed validation 未被夸大为完整 seed 证明；
• 执行后再次 check 和应用 smoke 均通过。

另见

• 数据库迁移
• Seed Exporter
• 持久化
• 灾难恢复