zzxCoding Flydb CLI 发布包使用
使用 Flydb 独立 CLI 发行包完成一次可追溯的数据库迁移操作。本技能自包含：命令、配置、错误码参考全部打包在 references/ 内，复制到任何目录都可独立工作，不依赖 GitHub 文档链接或 Flydb 源码仓库。
本技能属于 Flydb 技能族（总入口为 flydb 技能）：写迁移脚本用 flydb-migration-scripts，多环境/CI 自动化用 flydb-multi-environment。
参考文档（按任务读取）
| 文件 | 何时读取 |
|---|---|
references/release-package.md |
获取/安装发行包、Java 运行环境、配置文件查找顺序 |
references/commands.md |
选择子命令、核对全局选项与参数语义 |
references/configuration.md |
配置键、环境变量、优先级、版本选择/路径过滤规则 |
references/errors.md |
按错误码（FLYDB-xxxx）与退出码分类处理失败 |
references/drivers.md |
JDBC 驱动解析顺序、厂商驱动接入、FLYDB-1003 排查 |
references/jdbc-integration.md |
新数据库接入、驱动与方言区别、SPI JAR 与厂商验证边界 |
references/web.md |
启动本机 GUI、管理原配置、查看进度和同机 CLI 记录 |
references/web-api.md |
直接调用本机 API、配置冲突、确认引用、Run/SSE 状态 |
references/json-output.md |
CI/Agent 读取机器信封、protocolVersion、错误与状态 token |
references/plan-artifact.md |
核对 plan.id、计划内容摘要及其适用边界 |
references/mcp-tools.md |
MCP 定位与握手、工具白名单、写入开关、超时与诊断 |
核心契约
- 自包含与版本核验：运行参考随技能打包；先运行目标 CLI 的
version，优先采用其发行包内匹配版本的文档，再使用本技能副本。参数差异用<命令> --help核对，机器 schema 用对应版本文档核对；缺少证据时报告差异，不猜测选项。外部链接用于追溯和扩展阅读，不是常规执行的前置条件。 - 来源不等于发布：同步版本、提交和文件哈希见
references/upstream-sync.json。这是源码工作区快照，不证明该版本已公开发布；下载时另行核验实际 Release 资产。旧版本没有 Web 时说明需要 0.3.5+，不要直接套用新接口。 - 写入需授权：
migrate、baseline、repair、undo、clean都会改变数据库。本地/测试库的明确执行请求可作为授权，不重复询问；预发/生产库先展示 dry-run 清单和目标摘要，再取得针对该范围的写入授权。已有授权仅在目标或范围变化时重新核对。目标环境不明时停在只读检查。 - 密码纪律：优先
FLYDB_PASSWORD环境变量、${env:VAR}引用或密码文件；不把密码写进命令历史、日志、SQL 或最终汇报；输出中的 JDBC URL 一律脱敏。
工作流
1. 环境预检与获取发布包
先区分源码仓库、发行包和外部脚本仓库；脚本位于 Flyway 等项目不改变用户指定的 Flydb 执行入口。确认 Java 和 CLI：
java -version # 要求 ≥8；版本输出在 stderr
<发行包目录>/bin/flydb version # 不连数据库，验证发行包与 Java 均就绪
发行包按三步获取（详见 references/release-package.md）：
- 探测已有安装：先查用户给定路径、
FLYDB_HOME、PATH 和项目工具目录，再按需搜索常见安装位置。 - 复用本地 ZIP（如
~/Downloads/flydb-cli-*.zip），unzip解压 - 下载：GitHub URL 模式
https://github.com/zzxCoding/Flydb/releases/download/v<version>/flydb-cli-<version>.zip；国内网络 GitHub 不可达时用 Gitee 镜像同型 URLhttps://gitee.com/zzhenxuan/Flydb/releases/download/v<version>/flydb-cli-<version>.zip
Java 缺失时报告并停止（安装任意 JDK 8+ 并设置 JAVA_HOME 后重试）；发行包缺失且无法下载时如实报告，不要把源码目录当成已安装的 CLI。
2. 建立执行上下文
执行任何数据库命令前，明确并在回复中记录：
- 使用的 CLI 路径或发行包目录；
flydb.conf或--config来源；- JDBC URL 的脱敏摘要、目标数据库与方言标识；
- 迁移脚本位置（通常是
filesystem:db/migration；脚本在外部仓库时记录解析后的绝对位置和当前工作目录）； - 这是本地、测试、预发还是生产数据库；
- 用户要查看、校验、预演还是实际写入。
首次接入可用 init 生成 flydb.conf 与迁移目录（非交互加 --yes；已有文件冲突会报 FLYDB-4004，不要删除覆盖绕过）。
3. 选择命令
| 用户目标 | 命令 | 默认动作 |
|---|---|---|
| 创建配置和迁移目录 | init |
只生成本地文件，不连接数据库 |
| 本机图形化配置与执行进度 | web |
启动本机服务，启动本身不连接数据库 |
| 查看迁移状态 | info |
读取数据库和本地脚本，不持锁 |
| 校验 checksum、失败记录和迁移集合 | validate |
只读校验 |
| 预演迁移 | --dry-run migrate |
解析并打印 SQL，不执行 |
| 执行待迁移脚本 | migrate |
写入数据库并持锁 |
| 为存量库写入基线 | baseline |
写历史记录并持锁 |
| 清理失败记录或对齐 checksum | repair |
修改历史表并持锁 |
| 撤销最近一次版本化迁移 | undo（支持 --dry-run） |
执行 SQL 并持锁 |
| 清空目标 schema | clean |
高风险破坏性操作，默认禁用 |
选定命令后到 references/commands.md 核对参数；不确定时用 bin/flydb <命令> --help。
程序消费使用 --json：stdout 单行信封，stderr 为日志与执行遥测；检查进程退出码、protocolVersion、status 和 exitCode，忽略未知新增字段。web 不接受 --json，--help 始终是文本，中断可能没有信封。
4. 执行
只读任务（info、validate、version）：执行后报告退出码和关键结果；不要把只读任务自行扩展为写库命令。
迁移任务：
- 使用版本选择或路径过滤时，先读配置参考并列出预期集合；
target-version默认精确匹配，范围结束值不含该版本的子版本。显式版本选择排除 R 脚本，路径过滤还会改变 info/validate 等命令看到的集合。再运行validate。 - 再
--dry-run migrate，核对目标方言、待执行脚本、SQL 数量与顺序；任何未解释的缺失或多出脚本都应阻断实际写入。 - 按核心契约第 3 条取得授权后执行
migrate。 - 执行后用
info --color=never与validate核对状态，报告是否产生失败记录。
迁移失败时读 references/errors.md 和诊断通道的“迁移失败执行快照”，核对失败阶段、事务模式、JDBC 确认数、定位可信度及事务结果。确认执行不等于提交；仅明确“已回滚”时才能按整体回滚处理。非事务、提交未知、回滚失败先核验数据库现场，再决定脚本修正与历史修复；不自动重放或 repair。
长迁移：预计超过终端/SSH/工具存活时间时，先读 长时间迁移与后台运行，用其包装器启动已授权迁移，保留工作目录及完全一致的配置、版本选择和过滤参数，记录运行目录、日志、PID 与原子 exit-code 文件。工具超时或无新日志时保持进程，做有界状态检查；终止进程需明确授权。进程结束且退出码可读后再核验，PID 消失但无完成标记是结果未知，不重跑。CI 保持前台执行并设置足够的 Job 超时。
5. Web 工作台与 MCP
Web：按 references/web.md 启动，仅报告普通 127.0.0.1 地址与进程状态。已有配置直接导入，新建复用 init 规则；表单和文件编辑作用于原文件，外部修改先合并修订。文件编辑可能显示原文凭据，不复制到对话或报告。启动 GUI、修改配置、打开浏览器均不扩大数据库写入授权。
预览后使用对应确认引用执行；配置、目标或脚本变化、FLYDB-2011 或确认过期均需重新预览。Web planId 是临时确认引用，CLI plan.id 是内容摘要，两者不能互换。HTTP 200 只代表操作已提交，继续观察 Run 终态及独立 verification；关闭浏览器不取消任务，无可信终态按 UNKNOWN 核验。Web 不提供 clean。
MCP：先读 references/mcp-tools.md，检查 CLI 版本握手与宿主现有配置。数据库工具只接收绝对 workingDirectory、configPath；密码由宿主环境或密码文件注入，驱动提前准备（调用固定 --driver-download never）。默认仅有只读/计划工具；启用 FLYDB_MCP_ENABLE_WRITES=true 只是开放工具，不能替代本次写入授权。先 plan 核对 plan.id、SQL 与目标，再按授权调用写工具；不臆造 clean/init/execute_sql/rawArgs。
MCP 超时/取消会终止 CLI 子进程，与后台 CLI 分支不同；收到 FLYDB_MCP-0002/0003 后保留诊断并核验数据库，不能推断已回滚或自动重试。预计超出调用期限时先选择合适执行方式，不能静默更换用户指定的 MCP 入口。
6. 驱动与错误处理
- 驱动相关（
FLYDB-1003）按references/drivers.md的解析轨迹排查。 - 连接失败（
FLYDB-1001）先查 URL、账号、密码、网络与数据库状态，不要先改方言。 - 探测歧义（
FLYDB-1002）显式--database-type，不要把未识别数据库强标为mysql/oracle。 - JDBC 驱动只负责连接，方言负责历史表、锁、事务、引号和语句切分。复用兼容家族前核对这些语义；专有差异按 JDBC 接入指南使用独立 SPI。报告时区分本地模拟、MySQL 冒烟与目标厂商实例验证。
边界情况
- 参考与实际不符：以
bin/flydb --help为准执行，并向用户报告差异（参考副本可能滞后于已安装的 CLI 版本）。 - clean：默认禁用。除非用户明确要求并完成目标确认，不得追加
--clean-disabled=false --force（FLYDB-4003是防呆，不是故障）。 - 业务模板占位符：
${workDate}等要原样入库的运行时模板报FLYDB-2009时，用--placeholder-replacement=false，不要为模板变量随意赋值。 - 迁移目录切换：新旧位置逗号并列，避免已应用记录变
MISSING（FLYDB-2003）。 - 不下载、提交或重新分发厂商 JDBC 驱动；遵守厂商许可证与企业制品库规则。
汇报格式
完成后用简洁结构汇报：
- 目标：脱敏后的 CLI 路径、数据库/方言、环境和命令。
- 动作：实际执行的命令，是否包含 dry-run，是否写入数据库。
- 结果：退出码、预期与实际迁移集合核对、迁移数量/状态、失败记录或锁结果。
- 验证：
info、validate或 dry-run 分别验证了什么。 - 后续：只给与当前失败或用户目标直接相关的下一步。
项目来源
本技能族服务于开源项目 Flydb（Apache-2.0；国内镜像 Gitee）。开源不易，欢迎 Star 支持与参与贡献。