@lumifai/harness-tool-pack-postgres 0.0.1 → 0.2.0

package/skills/postgres-write/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: postgres-write
+description: Deterministic PostgreSQL insert and update tools that read JSON from the workspace
+version: 1.1.0
+tags:
+  - database
+  - postgres
+  - write
+---
+
+# PostgreSQL Write Tools
+
+Use the `postgres` tool pack to persist workspace JSON files into PostgreSQL deterministically.
+Pair these tools with the `postgres` discovery workflow before unfamiliar tables.
+
+These tools do **not** run arbitrary SQL. Boot config must set `allowedTables` (and optionally `allowedColumns`).
+`postgres_validate_file` is registered only when `allowedTables` is set and only accepts those targets.
+
+## Tools
+
+| Tool                        | Purpose                                         |
+| --------------------------- | ----------------------------------------------- |
+| `postgres_validate_file`    | Validate table rows and quarantine invalid rows |
+| `postgres_insert_from_file` | JSON file → `INSERT` rows (optional upsert)     |
+| `postgres_update_from_file` | JSON patch → `UPDATE` one row                   |
+
+## Insert file format
+
+Path is **workspace-relative** (no leading `/`), e.g. `campaigns/123/brief.json`.
+
+Single row:
+
+```json
+{
+  "id": "campaign-123",
+  "name": "Fintech outreach",
+  "metadata": { "region": "US" }
+}
+```
+
+Multiple rows (every row must have the **same keys**):
+
+```json
+[
+  { "id": "c1", "name": "Campaign A", "metadata": {} },
+  { "id": "c2", "name": "Campaign B", "metadata": {} }
+]
+```
+
+Tool args:
+
+- `conflictColumns` — e.g. `["id"]` for idempotent saves
+- `onConflict` — `ignore` (default when conflictColumns set) or `update` (upsert non-key columns)
+
+Empty arrays are rejected.
+
+## Validation workflow
+
+Call `postgres_validate_file` after producing a JSON batch and before
+`postgres_insert_from_file`:
+
+```json
+{
+  "jsonFilePath": "batch.merged.json",
+  "schema": "public",
+  "table": "my_table",
+  "refreshSchema": false
+}
+```
+
+The validator derives the selected table schema from PostgreSQL and caches it under
+`.schema-cache/` for 24 hours (per connection fingerprint). It always writes a sibling
+`.valid.json` file; it writes `.rejected.json` only when at least one row fails. Only
+pass `validFilePath` to `postgres_insert_from_file`.
+
+Validation is schema-driven (nullability, defaults, generated columns, enums, basic
+SQL types, and batch uniqueness). Optional `formatRules` (`emailColumns` /
+`phoneColumns`) add application-level checks for `text`/`varchar` columns when the
+SQL type alone is not enough — omit them unless the pipeline needs that extra check.
+
+After a migration or DDL change, call with `"refreshSchema": true` (or wait for the
+TTL). Otherwise the workspace cache can accept shapes the live table no longer allows;
+`postgres_insert_from_file` remains the DB-level safety net.
+
+Boot `permissionRules` can auto-approve `postgres_validate_file` (and insert) when the
+pipeline must not pause on tool approval.
+
+The default batch uniqueness key is the first unique key, then the primary key.
+Pass `uniqueColumns` explicitly for composite or non-default keys.
+
+## Update file format
+
+Flat object — **only columns to change**:
+
+```json
+{
+  "name": "Updated campaign name",
+  "metadata": { "region": "EU", "status": "confirmed" }
+}
+```
+
+Lookup via tool args (not in the file):
+
+- `whereColumn` — defaults to `id`
+- `whereValue` — required unless `resolveWhereValue` is configured at server boot
+
+## Workflow
+
+1. Optionally inspect the table with `postgres_describe_table`.
+2. Write JSON to the workspace (`write_file`).
+3. Call `postgres_insert_from_file` or `postgres_update_from_file`.
+
+## Safety rules
+
+- Only write to tables/columns allowed in boot config.
+- Do not include the lookup column in update JSON files.
+- Writes require user approval by default.