diff --git a/CHANGELOG.md b/CHANGELOG.md index d53594e..7d8daa7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,36 @@ Flydb 的重要变更记录在本文件中。版本遵循语义化版本；正 ## [Unreleased] +## [0.3.7] - 2026-09-08 + +本次重点完善本机工作台的日常使用：大变更预览更流畅，多配置更易整理，问题上下文可直接交给 Agent；修复大记录读取与迁移状态显示问题。 + +### 新增 + +- Web 配置名称旁新增“复制给 Agent”：整理脱敏配置、迁移状态与最近执行摘要，标明过期状态、未保存草稿和截断范围；剪贴板不可用时提供手动复制。 +- Web 侧边栏支持分组折叠、新建、重命名、删除、拖拽排序及跨组移动配置，提供无需拖拽的移动入口；分组目录与顺序持久化，删除组只移入未分组。 +- Web 迁移列表、当前项目执行记录和全部执行记录每页 10 条，顶部与底部均支持翻页、直接输入页码，后台刷新保留当前页。 +- Web 高级操作支持 clean：显示生效目标和当前 schema 删除范围，要求风险勾选、输入 `CLEAN` 与最终确认；后端以五分钟单次引用绑定配置和目标，单次解除禁用保护，复用 Core clean 和执行记录，不修改配置文件。 +- 随包提供独立 `flydb-analysis` Skill preview，支持离线材料的方言预检、结构漂移、依赖和引用分析；这是独立技能工作流，不代表迁移内核已交付完整影响分析引擎。 + +### 修复 + +- 修复分组新建、重命名和配置移动弹窗因内容根节点与焦点管理不兼容，导致输入框或选择框无法获得键盘焦点的问题。 +- clean 确认弹窗不再因周期刷新返回内容相同的配置对象而清空输入和风险勾选；仅在配置、目标或凭据实际变化、或主动重新确认时重置。 +- 大迁移预览改用只读虚拟滚动编辑器，支持全文查找、长行横向滚动和完整 SQL 下载；脚本列表分页，原始报告详情按需渲染。Web 轮询使用不含 SQL 正文的摘要，完整记录仅在打开时加载，避免反复传输和渲染大结果。 +- Web 遇到 `MISSING` / `FUTURE` 时直接解释历史与本地脚本不匹配，提供连接配置入口，并明确修复历史、基线及临时测试重新开始的边界。 +- 修复大迁移预览记录写入成功后因超过 8 MiB 而无法读取的问题；Run 采用文件流读取完整记录，配置登记文件继续保留大小限制。 +- 修复 GUI 将 `OUT_OF_ORDER` 误标为“乱序已执行”并计入已执行数量的问题，按状态区分待执行与成功历史；当前版本包含本地缺失的成功历史，不再因 `FUTURE` / `MISSING` 而遗漏。 +- 执行失败面板直接展示脱敏后的具体错误详情，无需展开原始 JSON 才能看到脚本与原因。 +- Web 正确显示无法读取的执行记录：缺失的核验结果显示“未知”，缺失或无效时间的耗时显示“—”，修复中英文界面及导出报告中的 `undefined`、`NaN:NaN`；明确区分本地记录读取失败与数据库执行失败。 + +### 使用与升级 + +- 停止旧的 `flydb web`，解压新版 ZIP，保留原配置和驱动位置后用新版启动。工作台登记兼容既有 profiles.json，新增 groups 保存空分组及顺序；执行记录不迁移或自动删除。 +- 执行记录列表覆盖最近 200 条，分页不代表全量历史查询；预览 SQL 完整保留，Agent 交接内容使用有界摘要。 +- 版本同步为 0.3.7，MCP Adapter 独立版本仍为 0.1.0，CLI JSON 协议不变。README 更新为 GUI、CLI 与 Agent 使用场景，并保留数据库验证矩阵。 +- 本轮 clean 的新增确认入口由隔离测试验证，未在用户数据库执行清理，也不新增厂商数据库认证声明。 + ## [0.3.6] - 2026-09-06 ### 安全修复 diff --git a/README.en.md b/README.en.md index ab78501..e63f3d5 100644 --- a/README.en.md +++ b/README.en.md @@ -1,56 +1,84 @@ English | [中文](./README.md)

- Flydb Data Courier mascot + Flydb Data Courier mascot

# Flydb +**Database migrations you can see. Context your Agent can use.** + [![CI](https://github.com/zzxCoding/Flydb/actions/workflows/ci.yml/badge.svg)](https://github.com/zzxCoding/Flydb/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/zzxCoding/Flydb)](https://github.com/zzxCoding/Flydb/releases/latest) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE) ![Java 8+](https://img.shields.io/badge/Java-8%2B-blue) -[![LINUX DO](https://img.shields.io/badge/LINUX-DO-FFB003.svg?logo=data:image/svg%2bxml;base64,DQo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgd2lkdGg9IjEwMCIgaGVpZ2h0PSIxMDAiPjxwYXRoIGQ9Ik00Ni44Mi0uMDU1aDYuMjVxMjMuOTY5IDIuMDYyIDM4IDIxLjQyNmM1LjI1OCA3LjY3NiA4LjIxNSAxNi4xNTYgOC44NzUgMjUuNDV2Ni4yNXEtMi4wNjQgMjMuOTY4LTIxLjQzIDM4LTExLjUxMiA3Ljg4NS0yNS40NDUgOC44NzRoLTYuMjVxLTIzLjk3LTIuMDY0LTM4LjAwNC0yMS40M1EuOTcxIDY3LjA1Ni0uMDU0IDUzLjE4di02LjQ3M0MxLjM2MiAzMC43ODEgOC41MDMgMTguMTQ4IDIxLjM3IDguODE3IDI5LjA0NyAzLjU2MiAzNy41MjcuNjA0IDQ2LjgyMS0uMDU2IiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZWNlY2VjO2ZpbGwtb3BhY2l0eToxIi8+PHBhdGggZD0iTTQ3LjI2NiAyLjk1N3EyMi41My0uNjUgMzcuNzc3IDE1LjczOWE0OS43IDQ5LjcgMCAwIDEgNi44NjcgMTAuMTU3cS00MS45NjQuMjIyLTgzLjkzIDAgOS43NS0xOC42MTYgMzAuMDI0LTI0LjM4N2E2MSA2MSAwIDAgMSA5LjI2Mi0xLjUwOCIgc3R5bGU9InN0cm9rZTpub25lO2ZpbGwtcnVsZTpldmVub2RkO2ZpbGw6IzE5MTkxOTtmaWxsLW9wYWNpdHk6MSIvPjxwYXRoIGQ9Ik03Ljk4IDcwLjkyNmMyNy45NzctLjAzNSA1NS45NTQgMCA4My45My4xMTNRODMuNDI2IDg3LjQ3MyA2Ni4xMyA5NC4wODZxLTE4LjgxIDYuNTQ0LTM2LjgzMi0xLjg5OC0xNC4yMDMtNy4wOS0yMS4zMTctMjEuMjYyIiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZjlhZjAwO2ZpbGwtb3BhY2l0eToxIi8+PC9zdmc+)](https://linux.do) -Flydb is a versioned schema migration tool for databases with JDBC drivers: built-in dialects for mainstream databases, first-class support for Chinese Xinchuang databases, and extension to niche JDBC databases through the `DatabaseType` SPI. +[Website & demo](https://flydb.zzxcoding.dev) · [Download](https://github.com/zzxCoding/Flydb/releases/latest) · [GUI guide](./docs/getting-started/web.en.md) · [Agent setup](./flydb-skills/README.md) · [Documentation](./docs/getting-started/README.md) + +Flydb helps developers and operators manage versioned database changes. Use the local GUI to organize configurations, review SQL and watch execution; use the CLI in scripts and CI; copy context to an Agent when you want help. All three entry points share the same configuration and migration engine, while the GUI and local CLI share execution records. -**Today**, Flydb 0.2 is a reliable migration runtime: commands such as `migrate`, `info`, `validate`, `baseline`, `repair`, `undo`, and `clean`, backed by concurrency locks, transaction semantics, checksum validation, and failure blocking with recovery; eight built-in dialects; and Spring Boot 2/3 starters. **The long-term direction** is a database change capability shared safely by humans and AI agents: agents decide *what* changes; Flydb guarantees *how* it changes safely. See the [roadmap](./ROADMAP.md) (in Chinese) for stage goals and current progress. +MySQL, PostgreSQL, Oracle and Chinese databases including OceanBase, TiDB, DM8, KingbaseES and openGauss. **Run with Java 8+; the GUI needs no Node.js, network access or language model.** -> **Scope boundary:** Flydb manages migration versions, execution safety, and database dialect behavior. It does not translate arbitrary vendor SQL into every database syntax. Keep separate migration directories for database families when their dialects differ; see the [multi-environment guide](./docs/getting-started/multi-environment.md#4-脚本仓库按数据库家族分目录). +![Flydb local workbench with environment groups, migration state and Agent handoff](./docs/assets/flydb-workbench.en.png) +*Actual workbench UI using fictional demonstration configurations and migration records.* -## Why Flydb +## Choose how you work -- **Xinchuang databases as first-class citizens**: DM8 (Dameng), KingbaseES, openGauss, OceanBase, and TiDB ship as built-in dialects alongside MySQL, PostgreSQL, and Oracle. The CLI never bundles vendor drivers; it resolves them from `drivers/`, the runtime classpath, or a Maven repository, which fits drivers that cannot be distributed publicly. -- **Zero-dependency Java 8 core**: `flydb-core` has no third-party runtime dependencies (enforced by Maven Enforcer) and drops into any legacy Java 8 system; Boot 3 / Java 17 environments use a separate starter. -- **Friendly to humans and agents alike**: stable exit and error codes, `--dry-run` previews, non-interactive operation; the distribution ships an Agent Skill and docs matched to the CLI version. -- **Safe defaults**: `clean` is disabled by default and needs a double opt-in; failed migrations block subsequent runs; passwords come from environment variables or password files, never commands, logs, or SQL. +| Your workflow | What Flydb provides | +|---|---| +| Manage development, staging and production configurations | Collapsible groups, drag-and-drop organization, forms and an advanced editor for the original files | +| Review an upgrade before applying it | SQL previews, version search, pagination, full-text search and complete SQL downloads | +| Follow execution and diagnose failures | Script progress, transaction outcomes and post-run verification; unknown outcomes stay explicit | +| Bring in an Agent | “Copy for Agent” packages redacted settings, migration state and recent errors; Skills, JSON and MCP offer further integration | +| Automate migrations in an application or pipeline | CLI for CI, a Java API and Spring Boot 2/3 starters sharing the same engine | -## Quick start +## Open the GUI with one command -Prerequisites: Java 8 or newer, an existing target database, and a Java 8-compatible JDBC driver. +Download the ZIP from [Releases](https://github.com/zzxCoding/Flydb/releases/latest), extract it and run: ```bash -curl -LO https://github.com/zzxCoding/Flydb/releases/download/v0.3.6/flydb-cli-0.3.6.zip -unzip flydb-cli-0.3.6.zip -cd flydb-cli-0.3.6 +cd flydb-cli-0.3.7 +bin/flydb web +``` -# Example: place mysql-connector-j.jar into drivers/ -cp /path/to/mysql-connector-j.jar drivers/ +On Windows, use `bin\flydb.bat web`. Import an existing `flydb.conf` or create a configuration in the browser, then provide the JDBC driver for your database. No account setup; Chinese / English and light / dark themes are included. Starting the workbench does not run migrations. + +Open an existing configuration directly: + +```bash +bin/flydb --config /path/to/project/flydb.conf web +``` + +See the [GUI guide](./docs/getting-started/web.en.md). Vendor JDBC drivers are supplied by the user under their respective licenses, not bundled in the ZIP. + +
+Prefer a terminal? Start with the CLI -bin/flydb init \ - --url 'jdbc:mysql://127.0.0.1:3306/demo' \ - --user flydb_user \ - --database-type mysql \ - --yes +For an existing MySQL database: +```bash +cp /path/to/mysql-connector-j.jar drivers/ +bin/flydb init --url 'jdbc:mysql://127.0.0.1:3306/demo' --user flydb_user --database-type mysql --yes export FLYDB_PASSWORD='replace-me' +bin/flydb validate bin/flydb --dry-run migrate +# Review the SQL and target before applying bin/flydb migrate bin/flydb info -bin/flydb validate ``` -`init` generates `flydb.conf`, `db/migration/V1__init.sql`, and `drivers/README.md`, and never overwrites existing files. Passwords can also be supplied through `flydb.password=${env:DB_PASSWORD}` or `flydb.password.file=/run/secrets/db_password`; a plaintext `flydb.password` is only recommended for local throwaway testing. +`init` generates `flydb.conf`, `db/migration/V1__init.sql` and `drivers/README.md`, refusing to overwrite existing files. The V1 sample contains `SELECT 1;`; replace it with your actual changes. Environment variables and password files are also supported. + +
+ +## One migration engine across every entry point + +- **Review before execution**: checksum validation, concurrency locks, transaction handling and failure blocking. Changes to configuration or scripts after a preview are rechecked. +- **Fit existing environments**: a Java 8 core with zero third-party runtime dependencies, a standalone CLI ZIP, and Spring Boot 2/3 starters. +- **Work across database families**: built-in dialects and driver loading, extensible through `DatabaseType` SPI. Verification levels are documented below. +- **Share facts with your Agent**: structured JSON, Plan Artifacts and execution records. Unknown or interrupted migrations are never automatically replayed. GUI clean requires risk acknowledgment and typing `CLEAN`. + +Flydb manages migration workflow and database dialect behavior. It does not translate arbitrary vendor SQL into other database syntaxes; keep separate migration directories where dialects differ. ## Database support @@ -72,7 +100,8 @@ See the [database getting-started guides](./docs/getting-started/README.md) for - [x] **Reliable migration runtime**: engine, 8 built-in dialects, CLI, Spring Boot starters, Agent Skill, the `v0.2.0` GitHub Release, and the `v0.2.1` Maven Central publishing - [x] **DX and machine contract**: `--json` machine-readable output, protocolVersion contract versioning, CI integration docs, an Agent Plugins 1.0 package (`v0.3.0`; package managers and a Docker image on demand) -- [x] **Agent distribution**: an MCP adapter (TypeScript, nine domain tools, writes unregistered by default) plus the Plan Artifact v1 plan digest; the npm package ships with the next release +- [x] **Agent distribution**: an MCP adapter (TypeScript, nine domain tools, writes unregistered by default) plus the Plan Artifact v1 plan digest; a built adapter ships in the CLI ZIP +- [x] **Local workbench**: multiple configurations, groups, migration previews, execution records and Agent handoff - [ ] **Brownfield change intelligence**: impact analysis, application reference scanning, coverage with explicit unknowns - [ ] **Agent-safe change runtime**: a Plan → Validate → Risk → Approval → Apply → Verify protocol @@ -114,7 +143,7 @@ Plain Java applications depend on `flydb-core`: io.github.zzxcoding flydb-core - 0.3.6 + 0.3.7 ``` @@ -125,13 +154,13 @@ Spring Boot applications pick the matching starter; it runs `migrate` during con io.github.zzxcoding flydb-spring-boot-3-starter - 0.3.6 + 0.3.7 io.github.zzxcoding flydb-spring-boot-2-starter - 0.3.6 + 0.3.7 ``` @@ -175,7 +204,7 @@ The full reactor, including the Boot 3 modules, is built with Java 17; the Boot ./mvnw verify ``` -The CLI distribution is generated at `flydb-cli/target/flydb-cli-0.3.6.zip`. The core module enforces an 80% JaCoCo line-coverage gate and zero non-test runtime dependencies via Maven Enforcer. +The CLI distribution is generated at `flydb-cli/target/flydb-cli-0.3.7.zip`. The core module enforces an 80% JaCoCo line-coverage gate and zero non-test runtime dependencies via Maven Enforcer. Database integration contracts are skipped by default. Set `-Pmysql`/`-Ppostgresql` and `-Dflydb.integration.database=` explicitly to start temporary databases and run the selected tests. The full matrix runs in `.github/workflows/ci.yml`. diff --git a/README.md b/README.md index 6402d3c..5fdcb3c 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,84 @@ [English](./README.en.md) | 中文

- Flydb 数据飞行兽吉祥物 + Flydb 数据飞行兽

# Flydb +**数据库迁移，让人看得清，也让 Agent 接得上。** + [![CI](https://github.com/zzxCoding/Flydb/actions/workflows/ci.yml/badge.svg)](https://github.com/zzxCoding/Flydb/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/zzxCoding/Flydb)](https://github.com/zzxCoding/Flydb/releases/latest) [![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](./LICENSE) ![Java 8+](https://img.shields.io/badge/Java-8%2B-blue) -[![LINUX DO](https://img.shields.io/badge/LINUX-DO-FFB003.svg?logo=data:image/svg%2bxml;base64,DQo8c3ZnIHhtbG5zPSJodHRwOi8vd3d3LnczLm9yZy8yMDAwL3N2ZyIgd2lkdGg9IjEwMCIgaGVpZ2h0PSIxMDAiPjxwYXRoIGQ9Ik00Ni44Mi0uMDU1aDYuMjVxMjMuOTY5IDIuMDYyIDM4IDIxLjQyNmM1LjI1OCA3LjY3NiA4LjIxNSAxNi4xNTYgOC44NzUgMjUuNDV2Ni4yNXEtMi4wNjQgMjMuOTY4LTIxLjQzIDM4LTExLjUxMiA3Ljg4NS0yNS40NDUgOC44NzRoLTYuMjVxLTIzLjk3LTIuMDY0LTM4LjAwNC0yMS40M1EuOTcxIDY3LjA1Ni0uMDU0IDUzLjE4di02LjQ3M0MxLjM2MiAzMC43ODEgOC41MDMgMTguMTQ4IDIxLjM3IDguODE3IDI5LjA0NyAzLjU2MiAzNy41MjcuNjA0IDQ2LjgyMS0uMDU2IiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZWNlY2VjO2ZpbGwtb3BhY2l0eToxIi8+PHBhdGggZD0iTTQ3LjI2NiAyLjk1N3EyMi41My0uNjUgMzcuNzc3IDE1LjczOGE0OS43IDQ5LjcgMCAwIDEgNi44NjcgMTAuMTU3cS00MS45NjQuMjIyLTgzLjkzIDAgOS43NS0xOC42MTYgMzAuMDI0LTI0LjM4N2E2MSA2MSAwIDAgMSA5LjI2Mi0xLjUwOCIgc3R5bGU9InN0cm9rZTpub25lO2ZpbGwtcnVsZTpldmVub2RkO2ZpbGw6IzE5MTkxOTtmaWxsLW9wYWNpdHk6MSIvPjxwYXRoIGQ9Ik03Ljk4IDcwLjkyNmMyNy45NzctLjAzNSA1NS45NTQgMCA4My45My4xMTNRODMuNDI2IDg3LjQ3MyA2Ni4xMyA5NC4wODZxLTE4LjgxIDYuNTQ0LTM2LjgzMi0xLjg5OC0xNC4yMDMtNy4wOS0yMS4zMTctMjEuMjYyIiBzdHlsZT0ic3Ryb2tlOm5vbmU7ZmlsbC1ydWxlOmV2ZW5vZGQ7ZmlsbDojZjlhZjAwO2ZpbGwtb3BhY2l0eToxIi8+PC9zdmc+)](https://linux.do) -Flydb 是面向任意支持 JDBC 驱动的数据库的 Schema 版本化迁移工具：内置主流数据库方言，以国产信创数据库支持为特色，并通过 `DatabaseType` SPI 扩展小众 JDBC 数据库。 +[官网与演示](https://flydb.zzxcoding.dev) · [下载](https://github.com/zzxCoding/Flydb/releases/latest) · [GUI 上手](./docs/getting-started/web.md) · [Agent 接入](./flydb-skills/README.md) · [文档](./docs/getting-started/README.md) + +Flydb 是给开发、运维和实施人员使用的数据库版本迁移工具。用本机 GUI 管理多套配置、核对 SQL 和查看执行进度；用 CLI 接入脚本与 CI；有 Agent 时，一键复制上下文继续处理。三种入口使用同一份配置与迁移引擎，GUI 和同机 CLI 共用执行记录。 -**现在**，Flydb 0.2 是一个可靠的迁移运行时：`migrate`、`info`、`validate`、`baseline`、`repair`、`undo`、`clean` 等命令，配合并发锁、事务语义、checksum 校验、失败阻断与恢复，内置主流与信创共 8 个数据库方言，并提供 Spring Boot 2/3 starter。**长期方向**，是让人类与 AI Agent 共用同一套安全的数据库变更能力：Agent 决定“改什么”，Flydb 保证“怎么改是安全的”。各阶段目标与当前进度见[路线图](./ROADMAP.md)。 +支持 MySQL、PostgreSQL、Oracle 及多种国产数据库；**Java 8+ 即可运行，GUI 无需 Node.js、外网或大模型**。 -> **能力边界：** Flydb 负责迁移版本、执行安全与数据库方言适配，不会把任意一套厂商 SQL 自动转换成所有数据库语法。存在方言差异时，请按数据库家族维护迁移目录，具体组织方式见[多环境自动化指南](./docs/getting-started/multi-environment.md#4-脚本仓库按数据库家族分目录)。 +![Flydb 本机工作台：多环境分组、迁移状态与 Agent 交接](./docs/assets/flydb-workbench.png) +*实际工作台界面，使用虚构的演示配置与迁移记录。* -## 为什么选 Flydb +## 选择适合你的用法 -- **信创数据库一等公民**：达梦 DM8、人大金仓 KingbaseES、openGauss、OceanBase、TiDB 与 MySQL、PostgreSQL、Oracle 同为内置方言；CLI 不捆绑厂商驱动，从 `drivers/`、运行时 classpath 或 Maven 私服外置解析加载，适配不能公开分发的驱动。 -- **零依赖的 Java 8 内核**：`flydb-core` 无任何第三方运行时依赖（由 Maven Enforcer 强制），可直接进入任何存量 Java 8 系统；Boot 3 / Java 17 环境使用独立 starter。 -- **对人和 Agent 同样友好**：稳定退出码与错误码、`--dry-run` 预览、非交互可用；发行包随附与 CLI 版本匹配的 Agent Skill 和文档。 -- **安全默认**：`clean` 默认禁用且需双重开关；失败迁移阻断后续执行；密码支持环境变量与密码文件，不落命令行、日志和 SQL。 +| 使用场景 | Flydb 怎么帮你 | +|---|---| +| 管理多套开发、测试和生产配置 | 按分组折叠、拖拽整理；表单与高级文件编辑直接维护原配置 | +| 实施升级前核对变更 | 先预览 SQL；大量版本可搜索、分页，大 SQL 可全文查找与完整下载 | +| 跟踪执行、排查失败 | 查看脚本进度、事务结果与执行后核验；保留记录，不把未知结果当成成功 | +| 让 Agent 接着处理 | “复制给 Agent”整理脱敏配置、迁移状态和最近错误；也可通过 Skill、JSON 与 MCP 接入 | +| 在应用或流水线里自动迁移 | CLI 适配 CI，Java API 与 Spring Boot 2/3 starter 复用同一迁移引擎 | -## 快速上手 +## 一条命令打开 GUI -前置条件：Java 8 或更高版本、一个已创建的目标数据库，以及与 Java 8 兼容的 JDBC 驱动。 +从 [Releases](https://github.com/zzxCoding/Flydb/releases/latest) 下载 ZIP，解压后运行： ```bash -curl -LO https://github.com/zzxCoding/Flydb/releases/download/v0.3.6/flydb-cli-0.3.6.zip -unzip flydb-cli-0.3.6.zip -cd flydb-cli-0.3.6 +cd flydb-cli-0.3.7 +bin/flydb web +``` -# 示例：把 mysql-connector-j.jar 放入 drivers/ -cp /path/to/mysql-connector-j.jar drivers/ +Windows 使用 `bin\flydb.bat web`。浏览器中导入已有 `flydb.conf`，或新建配置；添加对应 JDBC 驱动后即可连接数据库。无需注册账号，支持中文 / English、明暗主题。启动工作台不会执行迁移。 + +已有配置也可以直接打开： + +```bash +bin/flydb --config /path/to/project/flydb.conf web +``` + +详见 [GUI 指南](./docs/getting-started/web.md)。驱动由使用者按厂商许可提供，不随 ZIP 捆绑。 -bin/flydb init \ - --url 'jdbc:mysql://127.0.0.1:3306/demo' \ - --user flydb_user \ - --database-type mysql \ - --yes +
+更习惯终端？从 CLI 开始 + +以下以已创建的 MySQL 数据库为例： +```bash +cp /path/to/mysql-connector-j.jar drivers/ +bin/flydb init --url 'jdbc:mysql://127.0.0.1:3306/demo' --user flydb_user --database-type mysql --yes export FLYDB_PASSWORD='replace-me' +bin/flydb validate bin/flydb --dry-run migrate +# 核对 SQL 与目标后执行 bin/flydb migrate bin/flydb info -bin/flydb validate ``` -`init` 会生成 `flydb.conf`、`db/migration/V1__init.sql` 和 `drivers/README.md`，并拒绝覆盖已有文件。密码也可通过 `flydb.password=${env:DB_PASSWORD}` 或 `flydb.password.file=/run/secrets/db_password` 提供；明文写入 `flydb.password` 仅建议本地临时测试。 +`init` 生成 `flydb.conf`、`db/migration/V1__init.sql` 和 `drivers/README.md`，拒绝覆盖已有文件。V1 示例为 `SELECT 1;`，请按实际变更替换；配置也支持环境变量与密码文件。 + +
+ +## 迁移能力，贯穿三种入口 -## 本机 GUI +- **先核对，再执行**：checksum 校验、并发锁、事务处理与失败阻断；预览后配置或脚本发生变化时重新核验。 +- **适应现有部署环境**：Java 8 零第三方运行时依赖内核，独立 CLI 发行包，以及 Spring Boot 2/3 starter。 +- **覆盖主流与国产数据库**：内置方言与驱动加载机制，支持 `DatabaseType` SPI 扩展；各数据库的验证层级见下表。 +- **人和 Agent 共用事实**：结构化 JSON、Plan Artifact 与执行记录；未知或中断的迁移不会自动重放。GUI 高级操作中的 clean 需风险确认和输入 `CLEAN`。 -0.3.5 起提供 `bin/flydb web`，支持配置导入与编辑、迁移预览、真实执行进度、CLI 记录共用、 -中英文和明暗主题。只做本机 GUI，不设账户、角色或审批页面。使用方法见 [GUI 指南](docs/getting-started/web.md)。 +Flydb 管理迁移流程与数据库方言行为，不会把任意厂商 SQL 自动翻译成其他数据库语法。存在语法差异时，请按数据库家族维护迁移目录。 ## 数据库支持 @@ -77,7 +100,8 @@ bin/flydb validate - [x] **可靠的迁移运行时**：迁移引擎、8 个内置方言、CLI、Spring Boot starter、Agent Skill、`v0.2.0` GitHub Release、`v0.2.1` Maven Central 发布 - [x] **开发体验与机器契约**：`--json` 机器输出、protocolVersion 契约版本化、CI 接入文档、Agent Plugins 1.0 插件包（`v0.3.0`；包管理器与 Docker 镜像按需启动） -- [x] **Agent 分发**：MCP 适配（TypeScript Adapter + 九个领域工具，写入默认不注册）与 Plan Artifact v1 计划摘要；npm 包随下一个 Release 发布 +- [x] **Agent 分发**：MCP 适配（TypeScript Adapter + 九个领域工具，写入默认不注册）与 Plan Artifact v1 计划摘要；CLI ZIP 内附已构建 Adapter +- [x] **本机图形工作台**：多配置、分组、迁移预览、执行记录与 Agent 上下文交接 - [ ] **存量变更智能**：影响分析、应用引用扫描、覆盖率与未知项标注 - [ ] **Agent 安全变更运行时**：Plan → Validate → Risk → Approval → Apply → Verify 协议 @@ -119,7 +143,7 @@ flydb.migrate(); io.github.zzxcoding flydb-core - 0.3.6 + 0.3.7 ``` @@ -130,13 +154,13 @@ Spring Boot 应用选择对应 starter，容器初始化期间执行 `migrate` io.github.zzxcoding flydb-spring-boot-3-starter - 0.3.6 + 0.3.7 io.github.zzxcoding flydb-spring-boot-2-starter - 0.3.6 + 0.3.7 ``` @@ -180,7 +204,7 @@ bin/flydb clean --clean-disabled=false --force # clean 默认禁用；非交 ./mvnw verify ``` -CLI 构建产物位于 `flydb-cli/target/flydb-cli-0.3.6.zip`。core 的 JaCoCo 行覆盖率门禁为 80%，并由 Maven Enforcer 保证零非测试运行时依赖。 +CLI 构建产物位于 `flydb-cli/target/flydb-cli-0.3.7.zip`。core 的 JaCoCo 行覆盖率门禁为 80%，并由 Maven Enforcer 保证零非测试运行时依赖。 数据库集成契约默认跳过；显式设置 `-Pmysql`/`-Ppostgresql` 与 `-Dflydb.integration.database=` 后，才会启动临时数据库执行对应测试。完整矩阵由 `.github/workflows/ci.yml` 执行。 diff --git a/docs/assets/flydb-workbench.en.png b/docs/assets/flydb-workbench.en.png new file mode 100644 index 0000000..c929ad0 Binary files /dev/null and b/docs/assets/flydb-workbench.en.png differ diff --git a/docs/assets/flydb-workbench.png b/docs/assets/flydb-workbench.png new file mode 100644 index 0000000..6445a7c Binary files /dev/null and b/docs/assets/flydb-workbench.png differ diff --git a/docs/design/12-web-workbench.md b/docs/design/12-web-workbench.md index 64ebc6d..3627612 100644 --- a/docs/design/12-web-workbench.md +++ b/docs/design/12-web-workbench.md @@ -59,7 +59,7 @@ Web 复用相同迁移运行时。通用 SQL IDE、数据库对象编辑器、 | G11 | 普通 CLI / Agent 调用在同一台机器的同一状态目录登记执行；GUI 可以在执行期间及结束后查看；CLI 不要求先启动 Web | | G12 | 结束后核验 info / validate，分别展示执行和核验结果；失败给出错误码、原始诊断、确认/回滚/未知状态及后续建议；不自动重放或 repair | | G13 | 本地执行历史、事件恢复、详情、脱敏报告导出和诊断复制；重启时没有可信终态的任务显示结果待核验 | -| G14 | 存量库 baseline 有解释、版本输入与独立确认；repair、undo 提供独立的高级处置流程和明确影响提示；clean 无 Web 写入入口 | +| G14 | 存量库 baseline 有解释、版本输入与独立确认；repair、undo 提供独立的高级处置流程和明确影响提示；clean 作为危险高级操作，必须展示目标与当前 schema 删除范围、风险勾选、输入 CLEAN，并使用绑定生效配置的短期单次确认引用（2026-09-07 按用户确认扩展原先无 Web clean 入口的边界） | | G15 | 识别和选择已有 JDBC 驱动，显示实际驱动来源与失败建议，支持离线目录/企业私服；不捆绑或主动下载厂商驱动 | | G16 | 中英文完整切换，记住偏好；所有界面、表单错误、应用提示、状态说明及导出报告可切换；SQL、路径、原始厂商错误保留原文 | | G17 | 明暗主题、键盘操作、焦点、对比度、减少动态效果、单配置和多配置、窄屏布局；美观和内容密度有实际截图证据 | diff --git a/docs/getting-started/ci-integration.md b/docs/getting-started/ci-integration.md index 03994d6..da59657 100644 --- a/docs/getting-started/ci-integration.md +++ b/docs/getting-started/ci-integration.md @@ -22,7 +22,7 @@ jobs: migrate: runs-on: ubuntu-latest env: - FLYDB_HOME: ${{ runner.temp }}/flydb-cli-0.3.6 # ZIP 内的版本化根目录 + FLYDB_HOME: ${{ runner.temp }}/flydb-cli-0.3.7 # ZIP 内的版本化根目录 CONF: deploy/flydb.mysql.uat.conf steps: - uses: actions/checkout@v4 @@ -30,7 +30,7 @@ jobs: - name: 安装 Flydb CLI（版本随仓库锁定） run: | curl -fsSL -o flydb.zip \ - "https://github.com/zzxCoding/Flydb/releases/download/v0.3.6/flydb-cli-0.3.6.zip" + "https://github.com/zzxCoding/Flydb/releases/download/v0.3.7/flydb-cli-0.3.7.zip" unzip -q flydb.zip -d "$RUNNER_TEMP" "$FLYDB_HOME/bin/flydb" version diff --git a/docs/getting-started/mcp-adapter.md b/docs/getting-started/mcp-adapter.md index 81d36dd..8e21276 100644 --- a/docs/getting-started/mcp-adapter.md +++ b/docs/getting-started/mcp-adapter.md @@ -52,7 +52,7 @@ npx flydb-mcp # 一次性启动（发布后可用；registry 名称以发 "command": "npx", "args": ["flydb-mcp"], "env": { - "FLYDB_CLI": "/opt/flydb-cli-0.3.6/bin/flydb", + "FLYDB_CLI": "/opt/flydb-cli-0.3.7/bin/flydb", "FLYDB_PASSWORD": "由宿主 secret 注入" } } diff --git a/docs/getting-started/web.en.md b/docs/getting-started/web.en.md index 78e3c25..4aa50cd 100644 --- a/docs/getting-started/web.en.md +++ b/docs/getting-started/web.en.md @@ -97,7 +97,13 @@ inspect the database and history before deciding what to do. No write is automat Advanced actions separately explain and confirm baseline, undo and repair. Undo previews the matched `U__` script. Baseline records an existing version; repair changes history and does not reverse SQL. -There is no Web `clean` action. +“Clean database” removes tables, views, sequences, and Flydb history/lock tables in the connection’s current +schema according to its dialect, including objects not managed by Flydb. Check the displayed target, account +and backups, acknowledge the warning, type `CLEAN`, then select “Confirm clean”. Confirmation is bound to +effective settings, expires after five minutes, and is single-use. The confirmation page does not connect or +enumerate objects; the connection determines the actual schema. Local configuration and SQL files are retained. +Clean is enabled for this invocation only; `flydb.conf` is not changed. Failure may leave partial deletions; +inspect the database before deciding what to do next. ## CLI and Agent interoperability @@ -120,15 +126,35 @@ diagnostics. Passwords, secret URL parameters and configuration values named wit credential are redacted. Unmarked sensitive business literals cannot be exhaustively inferred; review reports according to your project's data policy before sharing. The list shows the most recent 200 records; older files remain on disk without automatic deletion. +Project and all-run histories show 10 entries per page, with navigation and direct page entry above and below the list. Background refresh preserves the page; switching projects resets project history to page one. ## Preferences and troubleshooting +“Copy for Agent” appears beside the configuration name across all three tabs, or below it on narrow screens. +It copies file and working-directory paths, redacted connection settings, the latest inspection statistics and up to +50 scripts, plus 10 recent execution summaries and errors. Stale state, excluded unsaved drafts and truncation are explicit. +It does not read raw configuration files or include temporary passwords or SQL bodies. Nothing is automatically sent to an Agent. +Add your specific request when pasting; the Agent needs access to the local paths and must verify current state first. +Copying context does not authorize database writes. A manual-copy dialog is available when clipboard access fails. + +Create empty groups in the sidebar; click a group name to collapse it. Its menu supports rename, +move up/down and delete. Drag a group before another group to reorder, or onto Ungrouped to move it last. +Drag configurations into groups, or use the folder button beside a configuration to choose its group. +Deleting a group moves its configurations to Ungrouped and preserves files and database data. +Groups and order persist in the local workbench across restarts. Collapse preferences stay in the browser; +search temporarily expands matching groups. + Use the bottom-left controls for Chinese/English and dark/light themes. Preferences persist in the browser. Narrow screens use the top-left configuration menu; SQL scrolls within its preview. +Large previews use a read-only editor that renders the visible region. Use `Ctrl/⌘ F` to search the full +SQL and scroll horizontally for long lines. “Download full SQL” exports every preview statement in the +selected script. Migration lists show 10 entries per page with controls above and below the list; preview directories show 50, with full-set version/script +search and direct page-number entry. Filtering and pagination never change totals or the execution set. - Driver failure: check the JAR, Java version, class, coordinate and offline setting. - Connection failure: check the effective URL, credentials and network, then inspect again. - Validation or SQL failure: read the original details and [error reference](../reference/errors.md). +- Unreadable execution record (`UNREADABLE_RECORD`): the local record could not be read; this does not mean the database is empty or the migration failed. Preserve `runs//summary.json` and `events.jsonl` in the state directory, check file size, integrity and access permissions, and verify database state before deciding what to do next. - Unavailable page: keep the local process running, check the port, then refresh or select Retry. - Configuration conflict: merge external changes before saving; the original file was not overwritten. diff --git a/docs/getting-started/web.md b/docs/getting-started/web.md index e98626d..5ca58eb 100644 --- a/docs/getting-started/web.md +++ b/docs/getting-started/web.md @@ -101,7 +101,13 @@ Windows 使用 `bin\flydb.bat web`。只需要 Java 8+ 和浏览器；发行包 先检查目标库和迁移历史，再决定处置。没有自动重放、自动 repair 或模拟进度。 “高级操作”中的基线、撤销、修复分别说明影响并确认目标。撤销先预览匹配的 `U__` 脚本； -基线只登记存量版本；修复历史不撤销已执行 SQL。Web 不提供 `clean`。 +基线只登记存量版本；修复历史不撤销已执行 SQL。 + +“清空数据库（clean）”会按方言删除当前连接 schema 的表、视图、序列及 Flydb 历史/锁表， +不限于 Flydb 管理的对象，不是只删除迁移记录。先核对弹窗中的目标连接、账号和备份， +勾选风险确认并输入 `CLEAN`，再点击“确认清空”。此确认五分钟内单次有效；配置变化后必须重新确认。 +确认页面不连接数据库或枚举对象，实际 schema 由连接决定。本地配置和 SQL 文件会保留。 +只对本次操作解除 clean 禁用保护，不改写 `flydb.conf`；失败也可能已删除部分对象，核对现场后再决定后续操作。 ## 与 CLI / Agent 共用 @@ -121,15 +127,31 @@ CLI 的 `--json` stdout 仍为既有机器契约的一行 JSON。 导出和复制采用当前界面语言，保留 SQL、路径和厂商错误原文。密码、URL 秘密参数及名称含 password/secret/token/credential 的配置值会脱敏；业务 SQL 中未标识的敏感常量不可能自动穷尽识别， 分享报告前按项目数据要求检查。记录保留在本地；当前列表显示最近 200 条，旧记录文件不会自动删除。 +当前项目和全部执行记录每页 10 条，顶部和底部都可翻页或直接输入页码。后台刷新保留当前页，切换项目后项目记录回到第一页。 ## 语言、主题与问题定位 +配置名称右侧的“复制给 Agent”在三个页签均可使用，窄屏位于名称下方。复制内容包含原配置路径、 +工作目录、脱敏连接信息、最近一次检查的迁移统计与最多 50 条脚本、最近 10 条执行摘要及错误。 +内容标明状态过期、未保存草稿未包含、记录或错误截断等情况，不读取原文件正文、不包含临时密码或 SQL 正文。 +复制只写入本机剪贴板，不会自动发送给 Agent；粘贴时可补充具体诉求。Agent 需能访问这些本地路径， +并先核验最新现场，复制上下文本身不授权数据库写入。浏览器禁止自动复制时可在弹窗中手动复制。 + +侧边栏可新建空分组，点击组名折叠或展开，组旁菜单可重命名、上移、下移或删除。 +拖动组名到另一组前可排序，拖到“未分组”可排在末尾；拖动配置到目标组可移动配置， +也可用配置旁的文件夹按钮选择分组。删除分组仅将配置移到“未分组”，保留配置文件及数据库数据。 +分组与顺序随工作台保存在本机，重启后保留；折叠状态在当前浏览器记忆。搜索会临时展开匹配组。 + 左下角可随时切换中文/English 和明暗主题，偏好保存在浏览器。切换语言不会清空当前草稿。 窄屏从左上角菜单选择配置，长 SQL 在预览区域内滚动。 +大预览使用只读编辑器，仅渲染可见区域；`Ctrl/⌘ F` 查找完整 SQL，长行可横向滚动。 +“下载完整 SQL”导出当前脚本的全部预览语句；迁移列表每页 10 项，预览目录每页 50 项，支持搜索全部版本、脚本和直接输入页码。迁移列表顶部和底部均有分页入口。 +筛选与分页只改变显示范围，总数统计与确认执行仍使用完整集合。 - 驱动不可用：核对现有 JAR、Java 版本、驱动类名、坐标和离线配置。 - 连接失败：核对实际 JDBC URL、数据库凭据与网络；保留输入后修正再检查。 - 校验或迁移失败：打开原始详情，按[错误码参考](../reference/errors.md)定位，不自动修复历史。 +- 执行记录无法读取（`UNREADABLE_RECORD`）：表示本地记录读取失败，不代表数据库为空或迁移失败。保留状态目录中的 `runs/<报告 id>/summary.json` 与 `events.jsonl`，排查文件大小、完整性和访问权限；核对数据库状态后再决定后续操作。 - 页面未连接：保持终端进程运行，确认端口后刷新或点击“重试”；换端口时使用新的本机地址。 - 配置冲突：先合并文件变化再保存；原文件未被覆盖。 diff --git a/docs/reference/commands.md b/docs/reference/commands.md index 7d6471f..d3ab48b 100644 --- a/docs/reference/commands.md +++ b/docs/reference/commands.md @@ -158,6 +158,9 @@ MySQL/Oracle 家族虽然不支持 DDL 事务，但一份脚本若解析后的 `clean` 默认禁用。非交互环境必须同时设置 `--clean-disabled=false` 和 `--force`： +本机 Web 工作台在“高级操作 → 清空数据库”提供独立警示和确认流程，单次授权不会改写此默认配置， +见 [GUI 指南](../getting-started/web.md)。 + ```bash bin/flydb clean --clean-disabled=false --force ``` diff --git a/docs/reference/compatibility.md b/docs/reference/compatibility.md index 04aeb66..3726ada 100644 --- a/docs/reference/compatibility.md +++ b/docs/reference/compatibility.md @@ -9,8 +9,8 @@ Maven 坐标 groupId 统一为 `io.github.zzxcoding`（Central Portal 经 GitHub | 模块 | 坐标 | Java 运行时 | 依赖框架 | 发布到 Central | |---|---|---:|---|---| | Core（Java API） | `io.github.zzxcoding:flydb-core` | 8+ | 无（零第三方运行时依赖） | 是 | -| Runtime（待发布） | `io.github.zzxcoding:flydb-runtime` | 8+ | Core、Jackson 2 | 用户验收后随下一版发布 | -| Web（待发布） | `io.github.zzxcoding:flydb-web` | 8+ | Runtime、JDK HttpServer、内嵌静态界面 | 用户验收后随下一版发布 | +| Runtime | `io.github.zzxcoding:flydb-runtime` | 8+ | Core、Jackson 2 | 是（0.3.5 起） | +| Web | `io.github.zzxcoding:flydb-web` | 8+ | Runtime、JDK HttpServer、内嵌静态界面 | 是（0.3.5 起） | | CLI | `io.github.zzxcoding:flydb-cli` | 8+ | picocli | 是（jar；发行 ZIP 经 GitHub Release 分发） | | Spring Boot 2 Starter | `io.github.zzxcoding:flydb-spring-boot-2-starter` | 8+ | Spring Boot 2.7.x（以 2.7.18 验证） | 是 | | Spring Boot 3 Starter | `io.github.zzxcoding:flydb-spring-boot-3-starter` | 17+ | Spring Boot 3.x（以 3.5.16 验证） | 是 | diff --git a/docs/reference/json-output.md b/docs/reference/json-output.md index 315e4bd..5de9125 100644 --- a/docs/reference/json-output.md +++ b/docs/reference/json-output.md @@ -55,6 +55,10 @@ $ bin/flydb --json migrate 取值约定：状态 token 为 `PENDING`、`OUT_OF_ORDER`、`SUCCESS`、`FAILED`、`MISSING`、`OUTDATED`、`FUTURE`、`BASELINE`、`UNDONE`；类型 token 为 `SQL`、`JDBC`、`BASELINE`、`UNDO_SQL`；`installedOn` 为 ISO-8601 本地时间；可重复迁移的 `version` 为 `null`；未知或不适用的数值为 `null`。 +`info.current` 为仍有效的成功历史记录中的最高版本，包含本地脚本缺失时的 `MISSING` / `FUTURE`， +不计失败或已撤销的记录。`OUT_OF_ORDER` 表示本地存在、数据库尚未应用的低版本脚本，属于待执行， +不能将它显示为“乱序已执行”。校验是否允许执行仍由 Core 决定，不由统计数量决定。 + ## 稳定性承诺 同一 `protocolVersion` 内只新增字段、不改名、不删除、不改类型或语义；**消费者必须忽略未知字段**。破坏性变更会递增 `protocolVersion` 并在 CHANGELOG 说明。字段顺序固定但消费者不得依赖。 diff --git a/docs/reference/web-api.md b/docs/reference/web-api.md index 9da277a..234925f 100644 --- a/docs/reference/web-api.md +++ b/docs/reference/web-api.md @@ -22,6 +22,7 @@ POST 操作提交成功返回 HTTP 200 和 Run 快照，不代表数据库执行 | `POST /api/profiles` | mode 为 import/create/discover/duplicate；返回登记数组 | | `PUT /api/profiles/:id` | name/group/environment/workingDirectory，可选 driversDirectory | | `DELETE /api/profiles/:id` | 只移除登记 | +| `POST /api/groups` | 分组组织操作：create/rename/delete/move/moveProfile，见下文；只修改本机登记 | | `GET /api/profiles/:id/config` | revision/values/effective/sources/secretKeys，可含配置 error | | `PUT /api/profiles/:id/config` | `{revision, values:{key:string或null}}` 或 `{revision, content}`；整文件保存强制校验，返回脱敏快照 | | `POST /api/profiles/:id/actions` | 提交预定义操作，返回 Run | @@ -32,6 +33,14 @@ POST 操作提交成功返回 HTTP 200 和 Run 快照，不代表数据库执行 discover 使用 `paths` 数组；duplicate 使用 `sourceId/configPath`。显示元数据是可选的， 同一真实文件路径去重。配置内容保存到原文件，登记只保存路径和显示信息。 +bootstrap 的 `groups` 为有序分组名称数组，包括空分组；旧登记的 profile.group 自动纳入列表。 +`POST /groups` 输入 `action`：create 使用 `newName`；rename 使用 `name/newName`；delete 使用 `name`； +move 使用 `name/before`（空 before 表示末尾）；moveProfile 使用 `profileId/name`（空 name 表示未分组）。 +新增名称去除首尾空白，最多 80 字符，不允许空白或重名。重名返回 GROUP_EXISTS，分组不存在返回 GROUP_NOT_FOUND。 +删除分组将其配置移到未分组；重命名同步修改组内配置显示元数据。所有操作在 profiles.lock 下原子写入 +profiles.json 的 profiles/groups，不修改原配置、SQL 或数据库。未分组是空字符串代表的内置归属，不可删除或重命名。 +折叠状态按状态目录存于当前浏览器，搜索临时展开匹配分组，不覆盖折叠偏好。 + 文档转换的 `validate:false` 仅用于模式切换时保留待修正的字段，不绕过创建/保存时的校验。 新建草稿与 CLI 共用 `InitScaffolder.configurationDraft`；确认创建时完整原文交给同一个 `InitScaffolder.create`，使用 CREATE_NEW 生成 `flydb.conf`、`db/migration/V1__init.sql` 和缺失的 @@ -43,10 +52,19 @@ HTTP 409 / FLYDB-4004，已有驱动说明保留。默认迁移路径为绝对 错误包含所在逻辑行的起始行号。整文件保存仍校验 revision、使用文件锁及原子替换。 操作正文公共字段为 `command`、`revision`、`requestId`（调用方生成的 UUID），可选临时 `password`。 -command 只允许 inspect、validate、plan、migrate、undo-plan、undo、baseline、repair。 +command 只允许 inspect、validate、plan、migrate、undo-plan、undo、baseline、repair、clean。 baseline 增加 `baselineVersion` 和 `confirmed:true`；repair 增加 `confirmed:true`。 migrate/undo 必须使用对应 plan/undo-plan 结果中的 `planId`。 +`clean` 先 POST `/api/profiles//clean-confirmation`，携带当前 `revision` 和可选临时 `password`。 +该步骤只读取生效配置，不连接数据库或枚举对象；返回脱敏 `target`、`user`、`scope=CURRENT_SCHEMA`、 +`token` 与 `expiresInSeconds=300`。界面必须说明将按方言清理当前 schema 的表、视图、序列及历史/锁表， +不限于 Flydb 创建的对象，且失败可能留下部分删除结果。用户勾选风险并输入 `CLEAN` 后， +通过 actions 提交 `command=clean`、`cleanToken`、`confirmed:true`、`confirmationText:"CLEAN"`。 +后端校验确认引用与配置、目标绑定，引用单次有效，重启或五分钟后失效；旧迁移预览也会失效。 +仅对本次调用设置 `flydb.clean-disabled=false`，不改写配置文件；底层仍复用 Core clean、锁与执行记录。 +同一 requestId 重试返回原记录，不重复执行。失败或结果未知时必须先核对现场，不能自动重放。 + planId 是本服务内存中的一次确认引用，30 分钟后或重启后失效，不是 Plan Artifact 的内容摘要。 同一请求标识会返回已有记录，不重放。最近 1,000 条持久化记录用于重启后的去重查找， 浏览器每次新意图使用新 UUID；过期请求不能当作永久幂等 API。 @@ -72,8 +90,16 @@ SQL/Java 回调不在迁移预览清单内，且沿用原生命周期。 ## Run 与事件 +Web 使用 `GET /api/bootstrap?compact=true` 轮询：省略记录中的 SQL `statements` 数组， +并以 `detailsOmitted=true` 标记。不带参数的 bootstrap 保持完整响应。 +打开预览或报告后通过 `GET /api/runs/` 获取完整记录；详情未加载成功前不允许确认执行或导出不完整报告。 +终态摘要按文件身份、大小及修改时间缓存，运行中记录继续检查文件锁。摘要不改变原始记录、计划 ID 或执行集合。 + 状态目录布局：`profiles.json`、`profiles.lock`、`runs/<时间戳-UUID>/`。 每次 Run 包含 `summary.json`、`events.jsonl`、`run.lock`。 +`summary.json` 包含完整预览结果，读取时不采用配置登记文件的 8 MiB 限制； +采用文件流解析并保留 JSON 结构约束，不截断 SQL，也不修改旧记录。结果仍需在内存中解析， +该修复不表示无限大小的预览；配置登记文件继续保留 8 MiB 限制。 进程持有 OS 文件锁表示执行仍在运行，心跳超时不能推断它失败。 快照字段包括 schemaVersion=1、id、source=CLI/WEB、command、configPath、configRevision、 @@ -82,6 +108,9 @@ Web 还记录 profileId/profileName/requestId；执行中按实际事件更新 p 状态为 RUNNING、SUCCEEDED、FAILED、UNKNOWN；进程消失且没有终态时，读取返回 UNKNOWN 和 recovery=NO_TERMINAL_RESULT，不改写原证据。记录无法读取为 UNREADABLE_RECORD。 +列表中的不可读记录仅保证包含 id、status=UNKNOWN 和 recovery=UNREADABLE_RECORD； +调用方不得假定命令、目标、时间或核验结果存在。Web 对缺失核验结果显示“未知”， +对无法计算的耗时显示“—”，不会将缺失值解释为成功、失败或未执行核验。 INTERRUPTED 是前端可识别的保留状态，当前无法确认数据库结果的进程中断采用 UNKNOWN。 verification 独立为 NOT_RUN、PASSED、FAILED；CLI 不隐式增加执行后数据库命令，因此默认为 NOT_RUN。 diff --git a/flydb-cli/src/main/java/com/flydb/cli/FlydbCli.java b/flydb-cli/src/main/java/com/flydb/cli/FlydbCli.java index 5454b4c..af82927 100644 --- a/flydb-cli/src/main/java/com/flydb/cli/FlydbCli.java +++ b/flydb-cli/src/main/java/com/flydb/cli/FlydbCli.java @@ -750,7 +750,7 @@ private static void put(Map values, String key, Object value) { private static String version() { Package pkg = FlydbCli.class.getPackage(); String implementation = pkg == null ? null : pkg.getImplementationVersion(); - return implementation != null ? implementation : "0.3.6"; + return implementation != null ? implementation : "0.3.7"; } private static Path detectInstallDirectory() { diff --git a/flydb-cli/src/test/java/com/flydb/cli/FlydbCliTest.java b/flydb-cli/src/test/java/com/flydb/cli/FlydbCliTest.java index 3acbd9f..afa9487 100644 --- a/flydb-cli/src/test/java/com/flydb/cli/FlydbCliTest.java +++ b/flydb-cli/src/test/java/com/flydb/cli/FlydbCliTest.java @@ -44,7 +44,7 @@ void versionCommandReturnsSuccess() { int exitCode = cli.execute("version"); assertThat(exitCode).isZero(); - assertThat(standardOutput.toString()).contains("flydb 0.3.6"); + assertThat(standardOutput.toString()).contains("flydb 0.3.7"); assertThat(errorOutput.toString()).isEmpty(); } @@ -63,7 +63,7 @@ void jsonVersionEmitsSingleLineEnvelope() { assertThat(exitCode).isZero(); assertThat(standardOutput.toString()) .isEqualTo("{\"protocolVersion\":1,\"command\":\"version\"," - + "\"status\":\"success\",\"exitCode\":0,\"version\":\"0.3.6\"}\n"); + + "\"status\":\"success\",\"exitCode\":0,\"version\":\"0.3.7\"}\n"); assertThat(errorOutput.toString()).isEmpty(); } diff --git a/flydb-core/src/main/java/com/flydb/core/api/MigrationInfoService.java b/flydb-core/src/main/java/com/flydb/core/api/MigrationInfoService.java index 10b4eaa..00f1441 100644 --- a/flydb-core/src/main/java/com/flydb/core/api/MigrationInfoService.java +++ b/flydb-core/src/main/java/com/flydb/core/api/MigrationInfoService.java @@ -8,6 +8,7 @@ import com.flydb.core.migration.AppliedMigration; import com.flydb.core.migration.MigrationInfo; import com.flydb.core.migration.MigrationState; +import com.flydb.core.migration.MigrationType; import com.flydb.core.migration.MigrationVersion; import com.flydb.core.migration.ResolvedMigration; @@ -53,11 +54,11 @@ public List applied() { public MigrationVersion current() { MigrationVersion current = null; for (MigrationInfo info : all) { - if (info.state() != MigrationState.SUCCESS && info.state() != MigrationState.BASELINE) { + AppliedMigration applied = info.applied(); + if (applied == null || !applied.success() || applied.type() == MigrationType.UNDO_SQL) { continue; } - AppliedMigration applied = info.applied(); - MigrationVersion version = applied == null ? null : applied.version(); + MigrationVersion version = applied.version(); if (version != null && (current == null || version.compareTo(current) > 0)) { current = version; } diff --git a/flydb-core/src/test/java/com/flydb/core/api/MigrationInfoServiceTest.java b/flydb-core/src/test/java/com/flydb/core/api/MigrationInfoServiceTest.java index bfa4e4c..fc8a31c 100644 --- a/flydb-core/src/test/java/com/flydb/core/api/MigrationInfoServiceTest.java +++ b/flydb-core/src/test/java/com/flydb/core/api/MigrationInfoServiceTest.java @@ -17,6 +17,29 @@ @DisplayName("MigrationInfoService") class MigrationInfoServiceTest { + @Test void currentIncludesSuccessfulHistoryMissingFromTheLocalCheckout() { + MigrationInfo future = MigrationInfo.derive(null, applied("20260901.3"), version("20260901.3"), version("20260227.3")); + MigrationInfo older = MigrationInfo.derive(resolved("20260101.1"), null, version("20260901.3"), version("20260227.3")); + MigrationInfoService service = new MigrationInfoService(Arrays.asList(older, future)); + assertThat(service.current()).isEqualTo(version("20260901.3")); + assertThat(service.pending()).containsExactly(older); + MigrationInfo missing = MigrationInfo.derive(null, applied("2"), version("2"), version("3")); + assertThat(new MigrationInfoService(Arrays.asList(missing)).current()).isEqualTo(version("2")); + } + + @Test void currentExcludesFailedAndUndoneHistory() { + AppliedMigration failed = AppliedMigration.of(2, version("4"), "failed", MigrationType.SQL, + "V4__failed.sql", 1, "u", new Timestamp(0), 1, false); + AppliedMigration undone = AppliedMigration.of(3, version("5"), "undone", MigrationType.UNDO_SQL, + "U5__undone.sql", 1, "u", new Timestamp(0), 1, true); + MigrationInfoService service = new MigrationInfoService(Arrays.asList( + MigrationInfo.derive(null, applied("2"), version("2"), version("1")), + MigrationInfo.derive(null, failed, version("2"), version("1")), + MigrationInfo.derive(null, undone, version("2"), version("1")))); + assertThat(service.current()).isEqualTo(version("2")); + } + + @Test @DisplayName("提供 pending/applied/current 只读视图") void exposesFilteredViewsAndCurrentVersion() { diff --git a/flydb-runtime/src/main/java/com/flydb/runtime/state/RunStore.java b/flydb-runtime/src/main/java/com/flydb/runtime/state/RunStore.java index 06c5719..a237427 100644 --- a/flydb-runtime/src/main/java/com/flydb/runtime/state/RunStore.java +++ b/flydb-runtime/src/main/java/com/flydb/runtime/state/RunStore.java @@ -5,6 +5,10 @@ import java.nio.channels.*; import java.nio.charset.StandardCharsets; import java.nio.file.*; +import java.nio.file.attribute.BasicFileAttributes; +import com.fasterxml.jackson.core.JsonParser; +import com.fasterxml.jackson.core.filter.FilteringParserDelegate; +import com.fasterxml.jackson.core.filter.TokenFilter; import java.time.Instant; import java.util.*; import com.fasterxml.jackson.databind.JsonNode; @@ -15,6 +19,9 @@ /** Cross-process local execution journal. A held OS lock, not a heartbeat, proves liveness. */ public final class RunStore { private final Path directory; + private final Map summaries = new LinkedHashMap(16, .75f, true) { + @Override protected boolean removeEldestEntry(Map.Entry entry) { return size() > 200; } + }; public RunStore(Path stateDirectory) throws IOException { this.directory = stateDirectory.resolve("runs"); Files.createDirectories(directory); @@ -31,7 +38,15 @@ public Writer start(ObjectNode metadata, String... secrets) throws IOException { } public ObjectNode read(String id) throws IOException { Path run = path(id); - ObjectNode summary = StateJson.read(run.resolve("summary.json")); + // Run results contain full migration previews, so they cannot share the + // small configuration-file size limit. Stream the file to avoid a second + // full byte-array copy; keep the mapper's JSON structure constraints. + ObjectNode summary; + try (InputStream input = Files.newInputStream(run.resolve("summary.json"))) { + JsonNode node = StateJson.MAPPER.readTree(input); + if (node == null || !node.isObject()) throw new IOException("Expected JSON object"); + summary = (ObjectNode) node; + } if ("RUNNING".equals(summary.path("status").asText()) && !isLive(run)) { summary.put("status", "UNKNOWN"); summary.put("recovery", "NO_TERMINAL_RESULT"); @@ -39,6 +54,13 @@ public ObjectNode read(String id) throws IOException { return summary; } public List list(int limit) throws IOException { + return list(limit, false); + } + /** SQL-free polling view. Full records remain available through read(id). */ + public List listSummaries(int limit) throws IOException { + return list(limit, true); + } + private List list(int limit, boolean compact) throws IOException { List paths = new ArrayList(); try (DirectoryStream stream = Files.newDirectoryStream(directory)) { for (Path path : stream) if (Files.isDirectory(path) && Files.exists(path.resolve("summary.json"))) paths.add(path); @@ -47,7 +69,7 @@ public List list(int limit) throws IOException { List result = new ArrayList(); for (Path path : paths) { if (result.size() >= limit) break; - try { result.add(read(path.getFileName().toString())); } + try { result.add(compact ? readSummary(path.getFileName().toString()) : read(path.getFileName().toString())); } catch (IOException e) { ObjectNode damaged = StateJson.object().put("id", path.getFileName().toString()) .put("status", "UNKNOWN").put("recovery", "UNREADABLE_RECORD"); @@ -56,6 +78,43 @@ public List list(int limit) throws IOException { } return result; } + private synchronized ObjectNode readSummary(String id) throws IOException { + Path run = path(id), file = run.resolve("summary.json"); + BasicFileAttributes attributes = Files.readAttributes(file, BasicFileAttributes.class); + SummaryCache cached = summaries.get(id); + if (cached != null && cached.matches(attributes)) return cached.value.deepCopy(); + final boolean[] omitted = { false }; + TokenFilter filter = new TokenFilter() { + @Override public TokenFilter includeProperty(String name) { + if ("statements".equals(name)) { omitted[0] = true; return null; } + return this; + } + }; + ObjectNode summary; + try (InputStream input = Files.newInputStream(file); + JsonParser parser = new FilteringParserDelegate(StateJson.MAPPER.getFactory().createParser(input), filter, + TokenFilter.Inclusion.INCLUDE_ALL_AND_PATH, true)) { + JsonNode node = StateJson.MAPPER.readTree(parser); + if (node == null || !node.isObject()) throw new IOException("Expected JSON object"); + summary = (ObjectNode) node; + } + if (omitted[0]) summary.put("detailsOmitted", true); + if ("RUNNING".equals(summary.path("status").asText())) { + if (!isLive(run)) summary.put("status", "UNKNOWN").put("recovery", "NO_TERMINAL_RESULT"); + } else if (SummaryCache.same(attributes, Files.readAttributes(file, BasicFileAttributes.class))) { + summaries.put(id, new SummaryCache(attributes, summary.deepCopy())); + } + return summary; + } + private static final class SummaryCache { + final BasicFileAttributes attributes; + final ObjectNode value; + SummaryCache(BasicFileAttributes attributes, ObjectNode value) { this.attributes = attributes; this.value = value; } + boolean matches(BasicFileAttributes other) { return same(attributes, other); } + static boolean same(BasicFileAttributes a, BasicFileAttributes b) { + return a.size() == b.size() && a.lastModifiedTime().equals(b.lastModifiedTime()) && Objects.equals(a.fileKey(), b.fileKey()); + } + } public List events(String id, long after, int limit) throws IOException { List result = new ArrayList(); Path events = path(id).resolve("events.jsonl"); diff --git a/flydb-runtime/src/test/java/com/flydb/runtime/state/RunStoreTest.java b/flydb-runtime/src/test/java/com/flydb/runtime/state/RunStoreTest.java index 7bf1bef..25be904 100644 --- a/flydb-runtime/src/test/java/com/flydb/runtime/state/RunStoreTest.java +++ b/flydb-runtime/src/test/java/com/flydb/runtime/state/RunStoreTest.java @@ -9,6 +9,53 @@ class RunStoreTest { @TempDir Path state; + @Test void summaryCacheTracksReplacementAndDoesNotCacheLiveness() throws Exception { + RunStore store = new RunStore(state); + String id; + try (RunStore.Writer writer = store.start(StateJson.object().put("command", "plan"))) { + id = writer.id(); + assertThat(store.listSummaries(1).get(0).path("status").asText()).isEqualTo("RUNNING"); + writer.finish("SUCCEEDED", StateJson.object().put("planId", "first"), "NOT_RUN"); + } + assertThat(store.listSummaries(1).get(0).path("status").asText()).isEqualTo("SUCCEEDED"); + ObjectNode changed = store.read(id).put("status", "FAILED"); + StateJson.write(state.resolve("runs").resolve(id).resolve("summary.json"), changed); + assertThat(store.listSummaries(1).get(0).path("status").asText()).isEqualTo("FAILED"); + changed.put("status", "RUNNING"); + StateJson.write(state.resolve("runs").resolve(id).resolve("summary.json"), changed); + assertThat(store.listSummaries(1).get(0).path("recovery").asText()).isEqualTo("NO_TERMINAL_RESULT"); + } + @Test void malformedRecordsStillHaveUnknownOutcomes() throws Exception { + RunStore store = new RunStore(state); + String id; + try (RunStore.Writer writer = store.start(StateJson.object())) { id = writer.id(); } + Path file = state.resolve("runs").resolve(id).resolve("summary.json"); + for (String invalid : new String[] { "{", "[]", "{\"status\":\"FAILED\",\"status\":\"SUCCEEDED\"}" }) { + Files.write(file, invalid.getBytes(java.nio.charset.StandardCharsets.UTF_8)); + ObjectNode record = store.list(1).get(0); + assertThat(record.path("status").asText()).isEqualTo("UNKNOWN"); + assertThat(record.path("recovery").asText()).isEqualTo("UNREADABLE_RECORD"); + } + } + @Test void readsLargePreviewWrittenByTheSameStoreWithoutLosingOutcome() throws Exception { + RunStore store = new RunStore(state); + char[] chars = new char[9 * 1024 * 1024]; + java.util.Arrays.fill(chars, 'x'); + String sql = new String(chars); + String id; + try (RunStore.Writer writer = store.start(StateJson.object().put("command", "plan"))) { + id = writer.id(); + writer.finish("SUCCEEDED", StateJson.object().put("sql", sql), "NOT_RUN"); + } + assertThat(Files.size(state.resolve("runs").resolve(id).resolve("summary.json"))).isGreaterThan(8 * 1024 * 1024); + ObjectNode record = new RunStore(state).list(1).get(0); + assertThat(record.path("status").asText()).isEqualTo("SUCCEEDED"); + assertThat(record.path("result").path("sql").asText()).isEqualTo(sql); + assertThat(store.read(id)).isEqualTo(record); + assertThatThrownBy(() -> StateJson.read(state.resolve("runs").resolve(id).resolve("summary.json"))) + .isInstanceOf(java.io.IOException.class).hasMessageContaining("8 MiB"); + } + @Test void persistsOrderedRedactedEventsAndDetectsCrossInstanceLiveness() throws Exception { RunStore store = new RunStore(state); String id; diff --git a/flydb-skills/plugin.json b/flydb-skills/plugin.json index 9f182c8..1eaf4eb 100644 --- a/flydb-skills/plugin.json +++ b/flydb-skills/plugin.json @@ -1,7 +1,7 @@ { "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", "name": "flydb", - "version": "0.3.6", + "version": "0.3.7", "description": "面向 JDBC 数据库的 Schema 版本化迁移工具：flydb-cli 指导 Agent 使用本机 GUI 并安全执行迁移；flydb-analysis 提供方言预检、结构漂移、对象依赖、应用引用与变更影响分析。", "homepage": "https://github.com/zzxCoding/Flydb", "repository": "https://github.com/zzxCoding/Flydb", diff --git a/flydb-web/frontend/package-lock.json b/flydb-web/frontend/package-lock.json index cd4da22..a0b8bff 100644 --- a/flydb-web/frontend/package-lock.json +++ b/flydb-web/frontend/package-lock.json @@ -1,12 +1,12 @@ { "name": "@flydb/workbench", - "version": "0.3.6", + "version": "0.3.7", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@flydb/workbench", - "version": "0.3.6", + "version": "0.3.7", "dependencies": { "@codemirror/autocomplete": "6.20.3", "@codemirror/commands": "6.11.0", diff --git a/flydb-web/frontend/package.json b/flydb-web/frontend/package.json index b1f001b..3153cd9 100644 --- a/flydb-web/frontend/package.json +++ b/flydb-web/frontend/package.json @@ -1,7 +1,7 @@ { "name": "@flydb/workbench", "private": true, - "version": "0.3.6", + "version": "0.3.7", "type": "module", "engines": { "node": ">=22.12.0" diff --git a/flydb-web/frontend/src/App.vue b/flydb-web/frontend/src/App.vue index 1a75ece..fbc5163 100644 --- a/flydb-web/frontend/src/App.vue +++ b/flydb-web/frontend/src/App.vue @@ -1,5 +1,5 @@ +