Add parameterized query support to run_sql and expand db docs

- MCP run_sql tool and CLI projects sql now accept optional params array
- When params provided, sends JSON body { sql, params } instead of text/plain
- CLI accepts --params '[1, "hello"]' flag with JSON validation
- SKILL.md expanded with db.sql() return type, parameterized examples,
  and full db.from() chainable API documentation

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: MajorTal

SKILL.md

@@ -206,10 +206,18 @@ Deploy a serverless function (Node 22) to a project. Functions are invoked via H
 **DB access inside functions:**
 ```typescript
 import { db } from '@run402/functions';
-const users = await db.from('users').select('*');
-const result = await db.sql('SELECT count(*) FROM orders');
 ```
 
+**db.sql(query, params?)** — raw SQL, returns `{ status, schema, rows, rowCount }`.
+- SELECT: `rows` = matching rows, `rowCount` = row count
+- INSERT/UPDATE/DELETE: `rows` = `[]`, `rowCount` = affected rows
+- Parameterized: `db.sql('SELECT * FROM t WHERE id = $1', [42])`
+
+**db.from(table)** — PostgREST-style queries (service_role, bypasses RLS). Returns a plain array of row objects.
+Chainable read methods: `.select(cols?)`, `.eq(col, val)`, `.neq()`, `.gt()`, `.lt()`, `.gte()`, `.lte()`, `.like()`, `.ilike()`, `.in(col, [vals])`, `.order(col, { ascending? })`, `.limit(n)`, `.offset(n)`
+Chainable write methods: `.insert(obj | obj[])`, `.update(obj)`, `.delete()` — all return array of affected rows.
+Column narrowing: `.insert({...}).select('col1, col2')` returns only specified columns.
+
 **Secrets:** Access via `process.env.SECRET_NAME`. Set with `set_secret`.
 
 ### invoke_function

cli/lib/projects.mjs

@@ -13,7 +13,7 @@ Subcommands:
   list                                    List all your projects (IDs, URLs, active marker)
   info  <id>                              Show project details: REST URL, keys
   keys  <id>                              Print anon_key and service_key as JSON
-  sql   <id> "<query>" [--file <path>]     Run a SQL query against a project's Postgres DB
+  sql   <id> "<query>" [--file <path>] [--params '<json>']  Run a SQL query (supports parameterized queries)
   rest  <id> <table> [params]             Query a table via the REST API (PostgREST)
   usage <id>                              Show compute/storage usage for a project
   schema <id>                             Inspect the database schema
@@ -29,6 +29,7 @@ Examples:
   run402 projects list
   run402 projects info abc123
   run402 projects sql abc123 "SELECT * FROM users LIMIT 5"
+  run402 projects sql abc123 "SELECT * FROM users WHERE id = $1" --params '[42]'
   run402 projects sql abc123 --file setup.sql
   run402 projects rest abc123 users "limit=10&select=id,name"
   run402 projects usage abc123
@@ -121,13 +122,23 @@ async function sqlCmd(projectId, args = []) {
   const p = findProject(projectId);
   let file = null;
   let query = null;
+  let paramsRaw = null;
   for (let i = 0; i < args.length; i++) {
     if (args[i] === "--file" && args[i + 1]) { file = args[++i]; }
+    else if (args[i] === "--params" && args[i + 1]) { paramsRaw = args[++i]; }
     else if (!query && !args[i].startsWith("--")) { query = args[i]; }
   }
   const sql = file ? readFileSync(file, "utf-8") : query;
   if (!sql) { console.error(JSON.stringify({ status: "error", message: "Missing SQL query. Provide inline or use --file <path>" })); process.exit(1); }
-  const res = await fetch(`${API}/projects/v1/admin/${projectId}/sql`, { method: "POST", headers: { "Authorization": `Bearer ${p.service_key}`, "Content-Type": "text/plain" }, body: sql });
+  let params;
+  if (paramsRaw) {
+    try { params = JSON.parse(paramsRaw); } catch { console.error(JSON.stringify({ status: "error", message: "Invalid JSON for --params. Expected a JSON array, e.g. '[42, \"hello\"]'" })); process.exit(1); }
+    if (!Array.isArray(params)) { console.error(JSON.stringify({ status: "error", message: "--params must be a JSON array, e.g. '[42, \"hello\"]'" })); process.exit(1); }
+  }
+  const useParams = params && params.length > 0;
+  const headers = { "Authorization": `Bearer ${p.service_key}`, "Content-Type": useParams ? "application/json" : "text/plain" };
+  const body = useParams ? JSON.stringify({ sql, params }) : sql;
+  const res = await fetch(`${API}/projects/v1/admin/${projectId}/sql`, { method: "POST", headers, body });
   console.log(JSON.stringify(await res.json(), null, 2));
 }
 

openspec/changes/archive/2026-03-28-parameterized-sql-and-docs/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-28

openspec/changes/archive/2026-03-28-parameterized-sql-and-docs/design.md

@@ -0,0 +1,42 @@
+## Context
+
+The run402 API endpoint `POST /projects/v1/admin/:id/sql` now accepts two content types:
+- `text/plain` — raw SQL string (existing behavior)
+- `application/json` — `{ "sql": "...", "params": [...] }` for parameterized queries (new)
+
+The `@run402/functions` Lambda runtime has expanded `db.sql()` to accept params and `db.from()` with a full chainable API. The SKILL.md documentation only shows a minimal 2-line example.
+
+This repo's MCP tool (`run-sql.ts`) and CLI (`projects.mjs`) currently send plain text only. They need a JSON path for params.
+
+## Goals / Non-Goals
+
+**Goals:**
+- MCP `run_sql` and CLI `projects sql` support optional parameterized queries
+- SKILL.md documents the full `db.sql()` and `db.from()` API matching llms.txt
+- Backward compatible — omitting params preserves existing plain-text behavior
+
+**Non-Goals:**
+- Changing the API endpoint behavior (already done in run402)
+- Adding params support to `rest_query` (uses PostgREST, not raw SQL)
+- Changing the response format (already returns `{ status, schema, rows, rowCount }`)
+
+## Decisions
+
+**1. JSON body when params present, plain text otherwise**
+
+When `params` is provided and non-empty, send `Content-Type: application/json` with `{ sql, params }`. When omitted, keep existing `text/plain` with raw SQL body. This maintains backward compatibility and avoids unnecessary format changes.
+
+Alternative: Always send JSON. Rejected because it changes behavior for all callers and the API still has the text/plain path documented.
+
+**2. CLI `--params` as JSON array string**
+
+The CLI accepts `--params '[1, "hello"]'` as a JSON string that gets parsed. This matches common CLI patterns (e.g., `aws --cli-input-json`). Alternative: positional args after `--` separator. Rejected as harder to parse and ambiguous with mixed types.
+
+**3. SKILL.md docs mirror llms.txt structure**
+
+Copy the expanded db.sql() and db.from() documentation directly from the llms.txt diff. This keeps the two sources consistent and avoids documentation drift.
+
+## Risks / Trade-offs
+
+- [Params type safety] CLI params arrive as a JSON string — invalid JSON will fail at parse time. → Mitigation: validate with `JSON.parse()` and give a clear error message.
+- [SKILL.md size] Adding ~15 lines of API docs. → Acceptable; this is the primary reference for agents using functions.

openspec/changes/archive/2026-03-28-parameterized-sql-and-docs/proposal.md

@@ -0,0 +1,26 @@
+## Why
+
+The run402 API now supports parameterized queries on `POST /projects/v1/admin/:id/sql` (accepts JSON `{ sql, params }`) and the `@run402/functions` Lambda runtime has expanded `db.sql(query, params?)` and `db.from(table)` APIs. The MCP tool, CLI command, and SKILL.md documentation are out of sync with these backend capabilities.
+
+## What Changes
+
+- **MCP `run_sql` tool**: Add optional `params` array to schema. When provided, send `Content-Type: application/json` with `{ sql, params }` instead of plain text.
+- **CLI `projects sql` command**: Add `--params` flag accepting a JSON array string. Same JSON body behavior.
+- **SKILL.md**: Expand "DB access inside functions" section to document `db.sql()` return type, parameterized query support, and full `db.from()` chainable API (matching llms.txt).
+- OpenClaw inherits CLI changes automatically via shims.
+
+## Capabilities
+
+### New Capabilities
+- `parameterized-sql`: Add parameterized query support to the `run_sql` MCP tool and CLI `projects sql` command
+- `functions-db-docs`: Expand SKILL.md documentation for `db.sql()` and `db.from()` runtime helpers
+
+### Modified Capabilities
+
+## Impact
+
+- `src/tools/run-sql.ts` — schema + handler changes (JSON body path)
+- `src/tools/run-sql.test.ts` — new test cases for params
+- `cli/lib/projects.mjs` — `sqlCmd` changes for `--params` flag
+- `SKILL.md` — expanded DB section (~15 lines replacing 2)
+- `sync.test.ts` — no surface changes (same tool names), but verify tests pass

openspec/changes/archive/2026-03-28-parameterized-sql-and-docs/specs/functions-db-docs/spec.md

@@ -0,0 +1,24 @@
+## ADDED Requirements
+
+### Requirement: SKILL.md documents db.sql with params and return type
+The SKILL.md "DB access inside functions" section SHALL document:
+- `db.sql(query, params?)` signature with optional params
+- Return type: `{ status, schema, rows, rowCount }`
+- SELECT behavior: `rows` = matching rows, `rowCount` = row count
+- INSERT/UPDATE/DELETE behavior: `rows` = `[]`, `rowCount` = affected rows
+- Parameterized example: `db.sql('SELECT * FROM t WHERE id = $1', [42])`
+
+#### Scenario: Agent reads SKILL.md for db.sql usage
+- **WHEN** an agent reads the SKILL.md functions section
+- **THEN** it finds documentation for parameterized queries with `db.sql(query, params?)` and understands the return type shape
+
+### Requirement: SKILL.md documents db.from chainable API
+The SKILL.md "DB access inside functions" section SHALL document:
+- `db.from(table)` returns a PostgREST-style query builder (service_role, bypasses RLS) that returns a plain array of row objects
+- Chainable read methods: `.select(cols?)`, `.eq(col, val)`, `.neq()`, `.gt()`, `.lt()`, `.gte()`, `.lte()`, `.like()`, `.ilike()`, `.in(col, [vals])`, `.order(col, { ascending? })`, `.limit(n)`, `.offset(n)`
+- Chainable write methods: `.insert(obj | obj[])`, `.update(obj)`, `.delete()` — all return array of affected rows
+- Column narrowing: `.insert({...}).select('col1, col2')` returns only specified columns
+
+#### Scenario: Agent reads SKILL.md for db.from usage
+- **WHEN** an agent reads the SKILL.md functions section
+- **THEN** it finds the full chainable API for `db.from()` including read methods, write methods, and column narrowing

openspec/changes/archive/2026-03-28-parameterized-sql-and-docs/specs/parameterized-sql/spec.md

@@ -0,0 +1,31 @@
+## ADDED Requirements
+
+### Requirement: MCP run_sql accepts optional params array
+The MCP `run_sql` tool schema SHALL accept an optional `params` field of type array. When `params` is provided and non-empty, the tool SHALL send the request as `Content-Type: application/json` with body `{ "sql": "<sql>", "params": [...] }`. When `params` is omitted or empty, the tool SHALL send `Content-Type: text/plain` with the raw SQL string as body (existing behavior).
+
+#### Scenario: Parameterized query via MCP
+- **WHEN** `run_sql` is called with `sql: "SELECT * FROM users WHERE id = $1"` and `params: [42]`
+- **THEN** the tool sends a POST to `/projects/v1/admin/:id/sql` with `Content-Type: application/json` and body `{"sql":"SELECT * FROM users WHERE id = $1","params":[42]}`
+
+#### Scenario: Plain SQL via MCP (backward compat)
+- **WHEN** `run_sql` is called with `sql: "SELECT 1"` and no `params`
+- **THEN** the tool sends a POST with `Content-Type: text/plain` and body `SELECT 1`
+
+#### Scenario: Empty params array treated as no params
+- **WHEN** `run_sql` is called with `sql: "SELECT 1"` and `params: []`
+- **THEN** the tool sends a POST with `Content-Type: text/plain` and body `SELECT 1`
+
+### Requirement: CLI projects sql accepts --params flag
+The CLI `projects sql` command SHALL accept an optional `--params` flag whose value is a JSON array string. When provided, the CLI SHALL parse the JSON and send the request as `application/json` with `{ sql, params }`. Invalid JSON SHALL cause the command to exit with an error message.
+
+#### Scenario: Parameterized query via CLI
+- **WHEN** user runs `run402 projects sql <id> "SELECT * FROM t WHERE id = $1" --params '[42]'`
+- **THEN** the CLI sends a JSON body with sql and params to the API
+
+#### Scenario: Invalid params JSON
+- **WHEN** user runs `run402 projects sql <id> "SELECT 1" --params 'not-json'`
+- **THEN** the CLI exits with an error message about invalid JSON params
+
+#### Scenario: CLI without params (backward compat)
+- **WHEN** user runs `run402 projects sql <id> "SELECT 1"` without `--params`
+- **THEN** the CLI sends `text/plain` with the raw SQL string

openspec/changes/archive/2026-03-28-parameterized-sql-and-docs/tasks.md

@@ -0,0 +1,20 @@
+## 1. MCP run_sql parameterized queries
+
+- [x] 1.1 Add optional `params` field (z.array(z.unknown()).optional()) to `runSqlSchema` in `src/tools/run-sql.ts`
+- [x] 1.2 Update `handleRunSql` to send JSON body when params is non-empty, plain text otherwise
+- [x] 1.3 Add test cases in `src/tools/run-sql.test.ts`: parameterized query sends JSON, no params sends plain text, empty params sends plain text
+
+## 2. CLI projects sql --params flag
+
+- [x] 2.1 Add `--params` flag parsing to `sqlCmd` in `cli/lib/projects.mjs`
+- [x] 2.2 Validate JSON.parse of params value, exit with error on invalid JSON
+- [x] 2.3 Send JSON body with `{ sql, params }` when params provided, plain text otherwise
+
+## 3. SKILL.md documentation
+
+- [x] 3.1 Replace the 2-line db example (lines 206-211) with expanded `db.sql(query, params?)` docs including return type and parameterized example
+- [x] 3.2 Add `db.from(table)` chainable API documentation (read methods, write methods, column narrowing)
+
+## 4. Verify
+
+- [x] 4.1 Run `npm test` — all unit and sync tests pass

openspec/specs/functions-db-docs/spec.md

@@ -0,0 +1,22 @@
+### Requirement: SKILL.md documents db.sql with params and return type
+The SKILL.md "DB access inside functions" section SHALL document:
+- `db.sql(query, params?)` signature with optional params
+- Return type: `{ status, schema, rows, rowCount }`
+- SELECT behavior: `rows` = matching rows, `rowCount` = row count
+- INSERT/UPDATE/DELETE behavior: `rows` = `[]`, `rowCount` = affected rows
+- Parameterized example: `db.sql('SELECT * FROM t WHERE id = $1', [42])`
+
+#### Scenario: Agent reads SKILL.md for db.sql usage
+- **WHEN** an agent reads the SKILL.md functions section
+- **THEN** it finds documentation for parameterized queries with `db.sql(query, params?)` and understands the return type shape
+
+### Requirement: SKILL.md documents db.from chainable API
+The SKILL.md "DB access inside functions" section SHALL document:
+- `db.from(table)` returns a PostgREST-style query builder (service_role, bypasses RLS) that returns a plain array of row objects
+- Chainable read methods: `.select(cols?)`, `.eq(col, val)`, `.neq()`, `.gt()`, `.lt()`, `.gte()`, `.lte()`, `.like()`, `.ilike()`, `.in(col, [vals])`, `.order(col, { ascending? })`, `.limit(n)`, `.offset(n)`
+- Chainable write methods: `.insert(obj | obj[])`, `.update(obj)`, `.delete()` — all return array of affected rows
+- Column narrowing: `.insert({...}).select('col1, col2')` returns only specified columns
+
+#### Scenario: Agent reads SKILL.md for db.from usage
+- **WHEN** an agent reads the SKILL.md functions section
+- **THEN** it finds the full chainable API for `db.from()` including read methods, write methods, and column narrowing

openspec/specs/parameterized-sql/spec.md

@@ -0,0 +1,29 @@
+### Requirement: MCP run_sql accepts optional params array
+The MCP `run_sql` tool schema SHALL accept an optional `params` field of type array. When `params` is provided and non-empty, the tool SHALL send the request as `Content-Type: application/json` with body `{ "sql": "<sql>", "params": [...] }`. When `params` is omitted or empty, the tool SHALL send `Content-Type: text/plain` with the raw SQL string as body (existing behavior).
+
+#### Scenario: Parameterized query via MCP
+- **WHEN** `run_sql` is called with `sql: "SELECT * FROM users WHERE id = $1"` and `params: [42]`
+- **THEN** the tool sends a POST to `/projects/v1/admin/:id/sql` with `Content-Type: application/json` and body `{"sql":"SELECT * FROM users WHERE id = $1","params":[42]}`
+
+#### Scenario: Plain SQL via MCP (backward compat)
+- **WHEN** `run_sql` is called with `sql: "SELECT 1"` and no `params`
+- **THEN** the tool sends a POST with `Content-Type: text/plain` and body `SELECT 1`
+
+#### Scenario: Empty params array treated as no params
+- **WHEN** `run_sql` is called with `sql: "SELECT 1"` and `params: []`
+- **THEN** the tool sends a POST with `Content-Type: text/plain` and body `SELECT 1`
+
+### Requirement: CLI projects sql accepts --params flag
+The CLI `projects sql` command SHALL accept an optional `--params` flag whose value is a JSON array string. When provided, the CLI SHALL parse the JSON and send the request as `application/json` with `{ sql, params }`. Invalid JSON SHALL cause the command to exit with an error message.
+
+#### Scenario: Parameterized query via CLI
+- **WHEN** user runs `run402 projects sql <id> "SELECT * FROM t WHERE id = $1" --params '[42]'`
+- **THEN** the CLI sends a JSON body with sql and params to the API
+
+#### Scenario: Invalid params JSON
+- **WHEN** user runs `run402 projects sql <id> "SELECT 1" --params 'not-json'`
+- **THEN** the CLI exits with an error message about invalid JSON params
+
+#### Scenario: CLI without params (backward compat)
+- **WHEN** user runs `run402 projects sql <id> "SELECT 1"` without `--params`
+- **THEN** the CLI sends `text/plain` with the raw SQL string