write-script-postgresql_skill

Overview

This skill is required when writing PostgreSQL queries for scripts that will run on the platform. It enforces a clear pattern for parameter declaration and typed argument usage inside SQL statements. Use it to produce safe, maintainable queries that integrate with the platform's script deployment flow.

How this skill works

Arguments are passed into SQL using positional parameters like $1::{type}, $2::{type}, and so on. Human-friendly parameter names are declared in comments at the top of the script (no types in the comments). After writing scripts, generate metadata and deploy using the platform CLI commands to produce the required .script.yaml and lock files and push your scripts to the runtime.

When to use it

• Every time you write a SQL script that will run as a platform script or webhook.
• When you need typed parameters to prevent SQL injection and ensure correct casting.
• When you want to expose parameters to UIs, webhooks, or workflows in a predictable way.
• When preparing scripts for automated deployment with the platform CLI.

Best practices

• Declare parameter names in top-of-file comments using the $n name or $n name = default_value pattern.
• Always include explicit type casts in the statement (e.g., $1::TEXT, $2::INT) to ensure consistent behavior.
• Keep queries focused and return clear results; use views or CTEs for complex logic.
• Run wmill script generate-metadata after edits to update .script.yaml and lock files.
• Use wmill resource-type list --schema to discover available resource types and match parameter types.

Example use cases

• Select users by name and age with named parameters: declare names in comments and use $1::TEXT, $2::INT in the query.
• Create a query that accepts an optional default parameter: -- $2 name = default\_value then cast with $2::TEXT.
• Expose a data retrieval script as a webhook where the request payload maps to the commented parameter names.
• Bundle SQL scripts in a folder, generate metadata, and push them to the platform for scheduled workflows.