Idempotent writes for agents

Pass a stable Idempotency-Key to db.query() or db.batch() before any agent write. PerSQL caches the result for 24 hours and replays it on retry instead of re-executing the SQL. No UPSERT logic required.

import { PerSQL } from "@persql/sdk";

const persql = new PerSQL({ token: process.env.PERSQL_TOKEN! });
const db = persql.database("acme/tasks");

// Stable key derived from the work unit — same retry, same key.
const idempotencyKey = `ingest-${jobId}-${chunkIndex}`;

await db.query(
  "INSERT INTO task_log (task_id, result) VALUES (?, ?)",
  [taskId, JSON.stringify(result)],
  { idempotencyKey }
);

// Batch writes use the same key for the whole batch.
await db.batch(
  [
    { sql: "INSERT INTO events (id, payload) VALUES (?, ?)", params: [id1, p1] },
    { sql: "INSERT INTO events (id, payload) VALUES (?, ?)", params: [id2, p2] },
  ],
  { transaction: true, idempotencyKey: `batch-${runId}` }
);

Use a key that includes the agent run identifier and the logical step. Replaying the same write by mistake returns the cached rowsWritten instead of creating duplicates.

Next step

Resume agent plans without duplicate work