用途
write-script-mssql 是一个用于编写 MS SQL Server(MSSQL)查询的 Windmill 技能/插件,来源为 windmill-labs/windmill-claude-plugin。其描述明确要求:在编写 MS SQL Server 查询时使用它。
主要能力
- MSSQL 参数占位符:MSSQL 参数使用 @P1、@P2 等。可通过在语句前添加注释来命名参数,例如:
-- @P1 name1 (varchar)
-- @P2 name2 (int) = 0
SELECT * FROM users WHERE name = @P1 AND age > @P2;
- 接收 S3Object 作为脚本参数:可将参数声明为 (s3object) 类型。Windmill 会为其渲染一个 S3 文件选择器,下载该文件,并将其绑定为 nvarchar(max) JSON 文本;Parquet/CSV 文件会在服务端解码为 JSON 记录数组,JSON/JSONL 则直接传递。可用 OPENJSON 解析:
-- @P1 file (s3object)
SELECT id, name
FROM OPENJSON(@P1)
WITH (id INT, name NVARCHAR(200));
- 将查询结果流式写入 S3:在脚本顶部添加 -- s3 指令,即可将结果集流式写入 S3 而非返回行。Windmill 会写入文件并将该 S3Object 作为脚本结果返回。
-- s3 prefix=exports/users format=parquet
SELECT id, name FROM users;
所有键均为可选:prefix(对象键前缀)、storage(命名的存储,省略则使用工作区默认值)、format(json(默认)、parquet 或 csv)。适用于大结果集——行会直接流式写入 S3,而不是缓存在脚本返回值中。
使用方式(CLI 命令)
将脚本放在一个文件夹中。编写完成后,应告知用户哪个命令适合其意图:
- wmill script preview <script_path>:默认用于迭代本地脚本。运行本地文件而不部署。
- wmill script run <path>:运行已部署到工作区的脚本。仅在用户明确想要测试已部署版本而非本地编辑时使用。
- wmill generate-metadata:为改动的脚本重新生成本地 .script.yaml(输入 schema)和 .lock(解析后的依赖),并刷新 wmill-lock.yaml 中对应的内容哈希。仅写本地文件,不是部署。
- 部署本地改动到工作区:通过 git push 或 wmill sync push(取决于仓库接线方式,参见 AGENTS.wmill.md 的 Deploying 部分)。仅在用户明确要求 deploy/publish/push 时才建议或运行部署。
Preview 与 run 按意图选择
若用户说“运行脚本”“试试”“测试一下”“能用吗”,且脚本文件存在本地编辑,应使用 script preview。不要先 push 再 script run——push 即部署,仅为测试而部署会用未测试的改动覆盖工作区版本。
仅在以下情况使用 script run:用户明确说“运行已部署版本”“运行服务器上的版本”;没有正在编辑的本地脚本(只是调用一个已有脚本)。
仅在以下情况使用 sync push:用户明确要求部署、发布、push 或 ship;preview 已验证改动且用户希望其进入工作区。
编辑后保持元数据同步
wmill-lock.yaml 为每个条目记录内容哈希。编辑脚本内容(尤其是增删导入或修改 main 的参数)会使该哈希失效,导致 .lock、.script.yaml 输入 schema 与哈希行过期。此类编辑后应运行 wmill generate-metadata(限定于改动范围),使解析后的 lock、由 .script.yaml 驱动的自动生成参数 UI 以及 wmill-lock.yaml 都与代码一致。保持过期会在 git-sync 与 CI 中产生虚假 diff。
该命令只写本地文件(不是部署),但会重新解析依赖,因此可能提升未固定版本(与从 UI 部署相同,属预期而非 bug)。因此默认先提供它、在用户同意后运行,而不是每次编辑后静默运行——除非项目的 AGENTS.md 选择自动运行元数据。无论哪种方式,都由你运行该命令,而非用户。运行后,对比重新生成的 .lock / .script.lock 文件并告知用户哪些依赖版本发生变化(例如 requests 2.31.0 → 2.32.0),以便在部署前发现不想要的版本提升。可在代码中固定版本以保持不变。
不带路径参数时,generate-metadata 仅重新生成内容哈希发生漂移的条目,而非全部。导入会传播:编辑一个被他人导入的脚本会使所有导入者也标记为过期,因此对共享模块的一行改动可能重新生成许多 lock(这是设计使然——其 lock 必须反映被导入的代码)。若影响超出预期,可运行 wmill generate-metadata --dry-run,它会列出每个过期条目及原因(内容改变或依赖 <path>)而不改动任何内容,然后用路径参数缩小范围(wmill generate-metadata f/foo)或使用 --strict-folder-boundaries。
若磁盘上的 .lock 与 .script.yaml 已正确,只有 wmill-lock.yaml 需要刷新哈希,使用 wmill generate-metadata rehash——它从磁盘重新记录哈希,无后端往返且不改变依赖。
编写后主动提出测试
若用户尚未要求运行/测试/预览脚本,应以一句话提出下一步(例如“要我用示例参数运行 wmill script preview 吗?”),不要给出多选项菜单。
若用户已在原始请求中要求测试/运行/尝试脚本,则跳过提议,直接执行 wmill script preview <path> -d '<args>',从脚本声明的参数中选取合理的参数。参数形态因语言而异:代码语言为 main(...);SQL 方言使用其自身的占位符语法(PostgreSQL 为 $1,MySQL/Snowflake 为 ?,MSSQL 为 @P1,BigQuery 为 @name 等);Bash 为位置参数 $1, $2, …;PowerShell 为 param(...)。
wmill script preview 不部署,但仍会执行脚本代码并可能产生副作用;当用户要求测试/预览时(或在确认确实要执行后)自行运行。wmill generate-metadata 也不部署——它只写本地文件(lock、schema、哈希)——但按上文在运行前先提供(或在项目 AGENTS.md 选择自动时自动运行)。部署到工作区(git push 或 wmill sync push)是唯一会改变远程状态的步骤——仅在用户明确要求 deploy/publish/push 时执行。
若需要可视化的“在开发页打开脚本”预览(而非 script preview 的运行并打印结果),使用 preview 技能。
使用 wmill resource-type list --schema 可发现可用的资源类型。
适用场景
- 在 Windmill 中编写 MSSQL 查询脚本。
- 需要在本地迭代、预览与测试脚本,而不部署到工作区。
- 需要以 S3Object 作为脚本参数,并用 OPENJSON 解析文件内容。
- 需要将大结果集流式导出到 S3。
限制与注意
- 资料未提供该技能的安装步骤、收费或价格信息。
- preview 会执行脚本代码,可能产生副作用。
- 部署(git push 或 wmill sync push)会改变远程状态,仅在明确要求时执行。
- generate-metadata 可能提升未固定版本依赖。
- 资料中未提供的具体平台、环境或效果信息,此处不予编造。