用途
该技能要求在编写 PostgreSQL 查询时使用,配合 Windmill CLI 管理脚本的本地编辑、预览、运行与部署流程。
主要能力
- 本地脚本迭代:使用 wmill script preview <script_path> 在不部署的情况下运行本地文件,默认用于本地脚本迭代。
- 运行已部署脚本:使用 wmill script run <path>,仅当用户明确想测试已部署版本而非本地修改时使用。
- 元数据同步:使用 wmill generate-metadata 重新生成本地 .script.yaml(输入模式)和 .lock(已解析依赖),并刷新 wmill-lock.yaml 中的内容哈希。仅写入本地文件,不是部署。无路径参数时仅重新生成内容哈希漂移的条目;可用 --dry-run 列出过时项及原因;可用 wmill generate-metadata rehash 仅从磁盘重记哈希,不走后端。
- 部署:通过 git push 或 wmill sync push(取决于仓库接线方式),仅在用户明确要求部署、发布或推送时执行。
- 资源类型发现:使用 wmill resource-type list --schema 查看可用的资源类型。
使用方式
预览与运行的区分:如果用户说“运行脚本”“试试”“测试”“能行吗”,且脚本文件存在本地修改,应使用 script preview,不要先推送再运行。仅当用户明确说“运行已部署版本”或没有正在编辑的本地脚本时,才使用 script run。仅当用户明确要求部署、发布、推送或交付时,才使用 sync push。
元数据同步:编辑脚本内容(尤其是增删导入或更改 main 的参数)会使哈希失效。运行 wmill generate-metadata 后应对比重新生成的 .lock / .script.lock 文件,告知用户哪些依赖版本发生变化(例如 requests 2.31.0 → 2.32.0)。默认先提供该操作,用户同意后执行,除非项目的 AGENTS.md 选择自动运行。导入会传播:编辑被其他脚本导入的脚本会同时标记所有导入者为过时。
写完后的下一步:如果用户未主动要求运行、测试或预览,可以用一句话提出(例如“要我带示例参数运行 wmill script preview 吗?”),不要提供多选项菜单。如果用户已要求测试,直接执行 wmill script preview <path> -d '<args>',并从脚本声明的参数中选取合理参数。
PostgreSQL 参数:
参数直接在语句中获得,使用 $1::{type}、$2::{type} 等。通过在脚本开头添加注释命名参数(不指定类型):
-- $1 name1 -- $2 name2 = default_value SELECT * FROM users WHERE name = $1::TEXT AND age > $2::INT;
接收 S3Object 作为脚本参数:
用类型 (s3object) 声明参数。Windmill 会渲染 S3 文件选择器,下载文件,并将其绑定为 jsonb 参数——Parquet/CSV 文件在服务端解码为 JSON 记录数组,JSON/JSONL 直接传递。使用 jsonb_to_recordset(或任何 jsonb API)消费:
-- $1 file (s3object) SELECT * FROM jsonb_to_recordset($1::jsonb) AS r(id INT, name TEXT);
将查询结果流式写入 S3:
在脚本顶部添加 -- s3 指令,将结果集流式写入 S3 而不是返回行。Windmill 写入文件并将该文件的 S3Object 作为脚本结果返回。
-- s3 prefix=exports/users format=parquet SELECT id, name FROM users;
所有键均可选:prefix(对象键前缀)、storage(命名存储——省略则使用工作区默认)、format(json(默认)、parquet 或 csv)。用于大结果集——行直接流式写入 S3,而不是作为脚本返回值缓冲。
适用场景
需要编写并在 Windmill 中管理 PostgreSQL 查询脚本、按意图正确选择预览/运行/部署、以及处理 S3Object 参数或大结果集导出时。
限制
wmill script preview 不部署但仍会执行脚本代码并可能产生副作用;wmill generate-metadata 仅写本地文件(locks、schemas、hashes)但会重新解析依赖,可能提升未固定版本;部署(git push 或 wmill sync push)是唯一会改变远程状态的步骤。