datapull은(는) 무엇을 하나요?
通过 DataPull CLI 读取数据库逻辑结构,按对象保存 SQL 文件。Skill 负责目标解析、安全调用和结果验收;连接、凭证、官方工具适配与文件事务由 CLI 维护。
只导出结构,不导出表内业务数据、用户、角色、授权、密码或服务器级配置。数据库事件可作为引擎支持的结构对象导出。使用具备目标对象元数据与定义读取权限的账户;连接测试成功不代表具备全部对象权限。
环境检查
- 检查 Node.js 是否为
>=22.12、NPM 是否可用、datapull --version是否成功。 - CLI 缺失时,提供
npm install --global @yg-toolkit/datapull,由用户亲自执行全局安装。 - CLI 可执行后运行
datapull doctor --json。同时检查healthy与每项checks[].ok;退出码为零和ok:true不代表所有诊断通过。按目标引擎处理工具缺失,其他引擎工具缺失不阻止当前任务。
安装或下载数据库工具前,向用户说明 CLI 返回的 actionPlan.installation 中的工具、来源、命令、权限和下载影响。已有授权覆盖该安装计划时直接继续;否则获得明确授权后,才在下一次调用中加入 --install-missing --yes。无法安装或读取对象时停止,保留错误和旧文件。
连接与凭证
datapull connection list --json 列出脱敏登记连接。连接别名描述服务器、认证和安全策略;数据库名是每次拉取单独指定的真实名称,二者不得混用。别名必须精确匹配,不能用数据库名或模糊子串代替。
尚未登记连接时,让用户在自己的交互终端运行 datapull connection add。CLI 隐藏输入秘密并校验连接,成功后可输入目标数据库名立即拉取全部支持的对象。临时运行可使用 npx --yes --package=@yg-toolkit/datapull@latest datapull connection add;说明首次运行会下载 NPM 包。Agent 的自动化调用使用子命令与 --json,不代填隐藏输入。
密码和含秘密 URL 只由用户在 CLI 隐藏输入中填写,或手工更新 CLI 显示的 credentials.env。不读取该文件,不在聊天中索要、复述或传递秘密,不把秘密放入命令参数。连接与凭证由 CLI 在用户目录保存,不复制到项目、Skill 目录或 Git。
确定目标并拉取
- 用户明确提供连接别名和数据库名时直接使用;缺少的信息可从当前任务上下文或 CLI 脱敏结果确定,无法唯一确定时再询问。
- 需要发现数据库时运行
datapull database list --connection <alias> --json。检查enumerationError;收藏或最近使用项不证明数据库当前可访问。 - 用户要求完整结构、结构快照或未限定对象类型时,省略
--include,拉取当前引擎支持的全部类型。用户明确要求部分类型时,用逗号分隔的--include <types>;范围含糊且会影响覆盖结果时再询问。对象类型以当前 CLI 的帮助与校验回执为准。 - Git 项目以 Git 顶层目录为根,非 Git 项目使用当前工作目录。运行前说明连接别名、数据库名、对象范围与项目根;目标明确且已授权时直接执行,无需重复确认。
全部结构:
datapull pull --connection <alias> --database <database> --yes --json
只更新指定类型:
datapull pull --connection <alias> --database <database> --include table,view --yes --json
输出固定在 .database-schema/<连接别名>/<数据库名>/<对象类型>/[schema/]<对象>.sql。CLI 处理跨平台文件名与同名、重载冲突;Agent 不自行生成 DDL 或改写目录结构。
本次所选类型作为一个文件事务整体替换,清除这些类型中已删除对象的旧文件;未选类型保持原样。任一对象读取或校验失败即本次失败,不跳过无权读取的对象。清理与异常中断恢复由 CLI 处理;遇到锁或回滚错误,保留现场并按回执恢复,不手工删除其他运行的锁、备份或临时文件。
SQL Server 证书异常
返回 SQLSERVER_TLS_CERTIFICATE_UNTRUSTED 时停止自动重试。说明传输仍可加密,但信任服务器证书会失去服务器身份验证。正式、生产或公网连接优先修复可信证书或本机 CA 链。
只有用户明确选择后,才执行对应操作;已有授权仅适用于其指定连接和范围:
- 安装可信 CA:说明证书来源与系统信任变更,按用户批准的方案处理,再保持严格校验重试。
- 仅本次信任:在
connection test、database list或pull中加入--trust-server-certificate --yes;这是单次覆盖,不修改保存的连接。 - 保存到连接:
datapull connection update --alias <alias> --trust-server-certificate --yes --json。 - 恢复验证:
datapull connection update --alias <alias> --verify-server-certificate --yes --json。
始终保持加密,不以关闭加密解决证书异常。使用信任模式成功后,明确说明“传输已加密,但服务器身份未校验”,以及本次未修改保存配置或连接将持续保留信任设置。
验收与失败处理
只有同时满足以下条件,才报告拉取成功:
- CLI 退出码为零,JSON 中
ok:true;connectionAlias、database、projectRoot和outputPath与目标一致。 updatedTypes与请求范围一致,preservedTypes只表示未选类型,不能宣称这些类型本次也已刷新。- 按
objectCounts逐个核对本次更新类型中的 SQL 文件数,包含 schema 子目录;文件存在且非空。零对象允许零文件,不伪造对象。 - 解释
warnings;锁或清理警告应作为待处理事项保留。检查 SQL Server 的安全警告,披露未校验服务器身份及其生效范围。 - 检查输出与回执不含凭证;如发现疑似泄露,停止传播,不复述秘密值。
DataPull 不生成旧版 manifest.json 或 last-run.json,不以这些文件作为验收条件。失败时保留稳定 error.code(数据库枚举还需检查 enumerationError.code),依据回执和 --help 给出下一条恢复命令。CLI 已负责有限的只读瞬态重试;Agent 不额外循环重试认证、权限、TLS、SQL 或解析错误。
完成汇报区分本地静态/模拟测试、CLI 可执行、连接成功和真实结构文件验收;部分类型更新只报告该范围。旧 database-schema 的连接配置与快照不会自动迁移,首次切换需通过 CLI 登记连接;保留项目中已有旧文件。