筑表师文档

中文

English
日本語

中文

English
日本語

Appearance

数据字典、结构对比与关联测试数据 ​

交接已有数据库、核对两个环境的结构或准备关联测试数据时，可以直接使用顶栏的「数据库工具」。空工作区也有入口，无需登录或先创建表。

准备输入 ​

数据字典和关联测试数据提供三种来源：

  • 已保存表：读取当前工作区的保存版本。先保存编辑，再点击「重新读取」并勾选需要的表。
  • 结构快照 JSON：上传从数据字典导出的文件。包含字段身份与标准业务摘要。
  • SQL：选择数据库，粘贴 SQL 或上传 .sql / .txt 文件，再点击「解析 SQL」。每份输入最多 50000 个字符。

SQL 会发送到现有解析服务。解析结果只用于本次工具，不写入工作区。关闭工具或切换账号会清除临时内容；导出文件由你自行保存。

这些工具使用严格解析：支持可完整保留的 CREATE TABLE、普通 CREATE INDEX，以及补充主键、唯一约束和外键的 ALTER TABLE ... ADD。请提供结构快照，不要直接粘贴含 INSERT、SET、DROP 或权限语句的完整数据库备份。

遇到无法保留的语法会停止处理，例如 CHECK、生成列、表达式或前缀索引、列级 REFERENCES。外键和唯一约束需要使用数据库中的实际名称，例如 CONSTRAINT fk_order_user FOREIGN KEY (user_id) REFERENCES users(id)。不要为了通过解析而删掉实际约束；应把支持的写法改为等价的表级约束，或为不支持的结构采用其他流程。

数据字典 ​

  1. 选择「数据字典」，解析 SQL 或勾选已保存表。
  2. 填写文档标题，使用搜索框查找表名、字段或业务说明。
  3. 点击「导出 Markdown」或「导出离线 HTML」。搜索不会缩小导出范围。

字典包含字段类型、可空性、主键、默认值、更新策略、注释、逻辑枚举、索引、物理外键和逻辑关系。字段关联了标准时，还会带上当前浏览器标准库中的名称、说明与单位；找不到的标准会标为缺失。

HTML 包含目录、表间导航和本地搜索，可直接在浏览器打开，不依赖网络。目标表未勾选的关系标为「选集外引用」。关系通过清单和链接展示。Markdown 适合存入仓库或继续编辑。

两份 SQL 的结构对比 ​

首版支持同一方言的 MySQL 或 PostgreSQL，不做跨数据库转换。

  1. 选择「结构对比」和数据库类型。
  2. 分别填写「当前结构」与「目标结构」。一侧留空表示空数据库。
  3. 点击「比较结构」，查看新增、删除、修改与未变更表。
  4. 如果删除字段和新增字段实际是一次改名，在「确认字段重命名」中显式匹配。未匹配的字段保持删除与新增。
  5. 导出 Markdown 对比报告或迁移 SQL。修改输入后，旧结果会清除。

表按 Schema 与表名匹配。迁移会先移除受影响的外键，再执行表和字段变化，最后重建外键。需要手动迁移的变化会阻止 SQL 下载，差异报告仍可导出。

SQL 只覆盖输入快照。执行前需要核查外部依赖、权限、存量数据和数据库版本；删除操作会丢失数据。工具不连接数据库、不执行脚本，也不提供整库数据回滚。

关联测试数据 ​

首版支持一组 MySQL 或 PostgreSQL 表。

  1. 选择「关联测试数据」，同时选中子表和引用的父表。
  2. 设置每表行数和固定种子。需要按业务关系造数时，勾选「同时按逻辑关系生成关联」。
  3. 点击「生成测试数据」，检查每表前 5 行预览。
  4. 下载完整 INSERT SQL 或按表分组的 JSON。

生成器先生成父表，再从父表实际生成的值中选取外键。复合外键整组复制，主键与唯一键按列组检查。一对一关系还会限制子表数量。相同结构、行数和种子可重复生成同一批数据。

范围与限制：

  • 每表 1–1000 行，总计最多 10000 行、250000 个字段值。
  • 支持常用整数、精确小数、浮点、字符、布尔、日期时间、UUID 和 JSON。逻辑枚举参与生成；不支持的类型会报错。
  • JSON 中 bigint 和精确小数使用字符串，避免精度丢失；SQL 中仍输出数值字面量。
  • 循环依赖、自引用、缺少父表、不兼容的引用类型、重叠外键及无法满足的唯一值数量会阻止生成。调整选集、行数或模型后重试。
  • 数据用于结构一致的空测试库。不会检查已有数据，也不会调整 PostgreSQL 序列当前位置。MySQL 字符串按默认反斜线转义模式输出。

单表造数仍可使用 Mock 数据与逻辑枚举。对比当前表和已保存版本，请查看 变更对比与回滚。

项目文档发布 ​

登录后，在数据字典底部的「发布与管理」填写发布标题和访问范围，点击「创建发布」。默认「仅自己」；选择「持链接可读」后，其他人无需登录即可阅读。阅读页包含版本、更新时间、搜索和关系导航，字段标准的名称、说明与单位随文档保存。

更新时重新选择最新表结构，在「已有发布」选中原文档，再点击「重新发布当前结构」。地址不变，版本递增。只修改标题或权限时，点击「保存标题与访问范围」。不同设备修改了同一版本时会拒绝覆盖，点击错误旁的「重新读取」，核对后重试。

「发布管理」可集中打开、复制链接、修改访问范围和删除已有发布。切回「仅自己」后，其他人的后续读取会被拒绝；已经打开或下载的内容无法远程收回。删除会同时删除提案下的留言。

每个账号最多 100 个发布；每份内容最多 512 KiB、200 张表、10000 个字段。超限时缩小选集，不会保存部分内容。发布内容与当前工作区独立，后续编辑不会自动改变阅读页。

结构快照与刷新 ​

在数据字典点击「导出结构快照」得到 JSON 文件。以后选择「结构快照 JSON」作为数据来源，可以重新使用字段身份、业务说明、关系与标准摘要。文件最多 2 MiB；未知版本、重复表或会丢失定义的内容会被拒绝。

刷新目前支持同一方言的 MySQL 或 PostgreSQL：

  1. 在「结构刷新」上传原有结构快照。
  2. 在「当前数据库结构」选择已保存表、SQL 或另一个结构快照。选择完整的更新范围；未选中的旧表会被视为移除。
  3. 查看新增/移除表和字段、索引、关系的差异明细。名称变化按删除与新增处理，不自动猜测改名。
  4. 下载对比报告和刷新后的结构快照，或选择原项目文档重新发布。

同名字段保留原字段身份、业务说明、逻辑枚举与标准引用，类型、默认值、可空性和物理约束采用新结构。原有逻辑关系只在两端仍存在时保留，失效关系会列出提示。刷新结果不会自动写入工作区。将结果文件作为下一次刷新的基线。

从本地数据库取得结构 ​

安装与源数据库匹配的客户端，在自己的电脑执行下面任意一组命令。替换地址、用户和数据库名；密码使用客户端提示或本地凭据文件。DDLBuilder 不接收数据库连接凭据。

sh
mysqldump --host=127.0.0.1 --user=reader --password \
  --no-data --skip-add-drop-table --no-tablespaces \
  --set-gtid-purged=OFF app_database > mysql-structure.sql
sh
pg_dump --host=127.0.0.1 --username=reader --dbname=app_database \
  --schema-only --no-owner --no-privileges --format=plain \
  --file=postgres-structure.sql

这些命令生成原始结构转储，不是可保证直接导入的 DDLBuilder 文件。检查客户端错误输出，并保留原文件。按本页「准备输入」的范围整理需要的表、索引和命名约束，再交给严格解析。转储中的会话设置、权限、序列、触发器等需要单独处理；不支持的约束不能通过删除后冒充完整结构。解析全部成功后，导出 DDLBuilder 结构快照作为刷新基线。

选取部分表时也要包含所需父表；对跨 Schema 依赖另行核对。客户端选项以 mysqldump 文档 和 pg_dump 文档 为准。

固定版本的变更提案 ​

在「结构对比」完成比较和字段改名确认后，填写「修改原因」，登录并创建发布。提案固定保存当前结构、目标结构和改名映射；后续要调整结构，应创建新提案。原提案只允许修改标题和访问范围。

持链接可读的提案允许匿名查看。登录读者可以填写对象位置（如 orders.amount）并留言；每份提案最多 200 条留言，每条最多 4000 个字符。作者可以「标记已处理」或「重新打开」。留言按文本展示，绑定当前固定版本；处理状态不代表批准执行 SQL。

读者可以下载对比报告；有生成器阻断项时不能下载迁移 SQL。关闭外部访问后，其他人无法继续读取或留言。

保存业务测试场景 ​

在「关联测试数据」展开「业务测试场景」，选择规则所属表、字段和生成方式：

规则输入与限制
空值比例0–100；表示每行生成 NULL 的概率，不保证小样本精确比例。主键和 NOT NULL 字段必须为 0
枚举权重每行 值=权重，例如 PAID=80、PENDING=20；权重为正，实际比例随样本波动
数值范围整数或精确小数字段的闭区间；精度须符合字段定义，跨度最多 MAX_SAFE_INTEGER 个最小精度单位
日期范围起止日期，格式 YYYY-MM-DD，按整天生成
日期偏移同一表的日期字段名与整数天数，例如 created_at 加 7 天；不允许循环依赖

点击「添加或替换字段规则」后再生成。物理外键以及启用的逻辑关系字段由父表数据决定，不接受覆盖规则；唯一值不足、类型不匹配或字段已不存在时会阻止导出。

填写场景名称后保存到当前浏览器，最多 50 份，同名覆盖需确认。「读取已保存场景」会恢复规则、种子、行数和逻辑关系选项；表选集仍需自己选择。JSON 导入/导出用于跨浏览器传递，导入文件最多 512 KiB。配置变更后必须重新生成；不支持运行任意代码或 SQL 公式。

MySQL → PostgreSQL 兼容性报告 ​

进入「迁移兼容性」，选择 MySQL 表。结果按「可映射」「人工核查」「范围外」逐项显示原定义、候选目标和下一步，支持导出 Markdown。

检查包含 unsigned 范围、自增、精确小数、字符比较、时间与时区、JSON、枚举、默认值、ON UPDATE、索引、外键和存储选项。视图查询和未知类型单独标记。报告不检查实际数据、应用查询和运行时行为，不提供自动迁移或可直接执行的跨库脚本。

查询设计与业务建模