ProjectAGiPrompt/24-版本升级标准流程/3-命令总览.md

4.1 命令总览

db-operator <command> [connection-flags] [command-flags]

Commands:
  export-structure   导出目标数据库的表结构基线（DDL）
  import-structure   向目标数据库导入表结构基线
  reset-database     重置数据库到基线状态（DROP + CREATE + 重新导入）
  run-upgrade        执行增量升级 SQL 脚本
  verify-upgrade     验证升级结果，生成成功证明报告
  diff-schema        比对两份结构基线的差异
  pack               将交付物打包为标准交付包
  version            输出工具版本及内置 MySQL 客户端版本
  help               帮助信息

Connection Flags（需要连接数据库的命令通用）:
  -H, --host         数据库主机地址（默认: 127.0.0.1）
  -P, --port         数据库端口（默认: 3306）
  -u, --user         数据库用户名（默认: root）
  -p, --password     数据库密码（若未指定则交互式提示输入）
      --charset      字符集（默认: utf8mb4）

Global Flags:
  -v, --verbose      启用详细输出
      --dry-run      仅预览操作，不实际执行
      --yes          跳过确认提示，直接执行
      --mysql-bin    指定 MySQL 客户端二进制所在目录（默认使用内置客户端）

无状态设计（ADR-6）：工具不使用配置文件、不维护任何本地状态。每次调用通过 CLI 参数传入连接信息，仅连接单个数据库实例。密码也可通过环境变量 DB_OPERATOR_PASSWORD 传入以避免命令行暴露。

Docker 模式下的路径约定：容器中所有文件 I/O 路径均相对于 /data 工作目录。用户通过 -v 挂载宿主目录到 /data，容器内的路径引用即对应宿主目录下的相对路径。详见 §6。

4.2 命令详细规格

4.2.1 export-structure — 导出结构基线

属性	说明
用途	连接目标 MySQL，导出全部/指定数据库的表结构（不含数据）
底层调用	mysqldump --no-data --routines --triggers --events
输出	<output-dir>/<database>_structure_<timestamp>.sql
关键参数	--databases：指定数据库列表（逗号分隔），不指定则导出全部
	--output-dir：输出目录（默认: ./export/）

4.2.2 import-structure — 导入结构基线

属性	说明
用途	将 export-structure 产出的 SQL 文件导入到目标 MySQL
底层调用	mysql < structure.sql
输入	一个或多个 .sql 文件路径
关键参数	--input：SQL 文件路径（必填，支持 glob 模式如 ./export/*.sql）
	--create-db：若数据库不存在则自动创建（默认: true）

4.2.3 reset-database — 重置数据库到基线状态

属性	说明
用途	将目标数据库销毁并从基线 SQL 文件重新创建，恢复到 import-structure 的初始状态
适用场景	研发人员调试 migration 脚本时多次重试，每次需要干净的起点
执行逻辑	1. DROP DATABASE IF EXISTS <database>
	2. CREATE DATABASE <database> DEFAULT CHARSET=<charset>
	3. mysql <database> < baseline.sql（重新导入基线结构）
关键参数	--database：目标数据库名（必填）
	--baseline：基线 SQL 文件路径（必填，即 export-structure 的产物）
安全约束	执行前输出 "即将销毁数据库 xxx，是否继续？[y/N]" 确认提示
	使用 --yes 可跳过确认（适用于脚本化场景）
	--dry-run 模式下仅输出将要执行的操作，不实际执行

⚠️ 风险警告：此命令会彻底销毁目标数据库的所有数据与结构。仅应在临时库/开发环境使用，严禁在生产环境执行。

4.2.4 run-upgrade — 执行增量升级脚本

属性	说明
用途	按顺序执行研发维护的增量 migration SQL 脚本
底层调用	mysql < migration.sql（按文件名自然排序依次执行）
输入	migration 脚本目录
关键参数	--migration-dir：脚本目录（默认: ./migrations/）
	--database：目标数据库名（必填）
	--from：起始版本号（可选，按文件名前缀过滤）
	--to：结束版本号（可选）
执行逻辑	1. 扫描目录中所有 .sql 文件，按文件名自然排序
	2. 若指定 --from/--to，过滤文件名范围
	3. 逐个执行，任一脚本失败立即中止，输出失败脚本名及错误信息
	4. 执行结果写入日志文件

4.2.5 verify-upgrade — 验证升级结果

属性	说明
用途	升级后重新导出结构，与预期结构进行比对，生成验证报告
输出	<output-dir>/verify_report_<timestamp>.json
报告内容	执行时间、执行环境（OS/Arch）、数据库版本、各脚本执行状态、
	升级前后表数量对比、结构差异摘要
关键参数	--baseline：升级前的结构文件（用于对比）
	--database：目标数据库名（必填）
	--output-dir：报告输出目录（默认: ./reports/）

4.2.6 diff-schema — 结构差异比对

属性	说明
用途	比对两份结构 SQL 文件的差异，输出人可读的差异报告
定位	仅做校验辅助，不生成可执行的 DDL SQL（遵循 ADR-4）
输入	两份 .sql 结构文件
输出	终端输出差异摘要 + 可选写入文件
关键参数	--source：源结构文件（升级前）
	--target：目标结构文件（升级后）
	--output：差异报告输出文件（可选）
比对维度	表级别：新增表、删除表、表名变更
	列级别：新增列、删除列、类型变更、默认值变更
	索引级别：新增索引、删除索引、索引列变更
	约束级别：外键、唯一约束变更

注意：diff-schema 是纯文件比对，不需要连接数据库，因此不需要 Connection Flags。

4.2.7 pack — 打包交付物

属性	说明
用途	将升级脚本、结构快照、验证报告等交付物打包为标准交付包
输出	<output-dir>/db-upgrade-pack_<project>_<version>_<timestamp>.tar.gz
关键参数	--project：项目名称（必填）
	--version：本次升级版本号（必填）
	--include-dirs：需要打包的目录列表（默认包含 export/、migrations/、reports/）
	--output-dir：输出目录（默认: ./dist/）

注意：pack 是纯文件操作，不需要连接数据库，因此不需要 Connection Flags。