home / skills / windmill-labs / windmill / write-script-postgresql

write-script-postgresql skill

safe

/system_prompts/auto-generated/skills/write-script-postgresql

This skill helps you craft PostgreSQL queries with proper parameterization, clear input naming, and safe execution across scripts and workflows.

npx playbooks add skill windmill-labs/windmill --skill write-script-postgresql

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

670 B

---
name: write-script-postgresql
description: MUST use when writing PostgreSQL queries.
---

## CLI Commands

Place scripts in a folder. After writing, run:
- `wmill script generate-metadata` - Generate .script.yaml and .lock files
- `wmill sync push` - Deploy to Windmill

Use `wmill resource-type list --schema` to discover available resource types.

# PostgreSQL

Arguments are obtained directly in the statement with `$1::{type}`, `$2::{type}`, etc.

Name the parameters by adding comments at the beginning of the script (without specifying the type):

```sql
-- $1 name1
-- $2 name2 = default_value
SELECT * FROM users WHERE name = $1::TEXT AND age > $2::INT;
```

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.

FAQ

How do I name parameters?

Add single-line comments at the top of the script like `-- $1 name1` or `-- $2 name2 = default_value`.

Do I need to specify types in the comments?

No. Types must be specified inline in the SQL using the $n::{type} syntax.