Propose / apply

Some writes shouldn’t run blind. Propose / apply splits a single mutation into two steps:

1. propose(sql, params) — server EXPLAIN-validates the SQL, estimates the affected row count, and returns a single-use executionToken (default 10-minute TTL, max 1 hour).
2. apply(executionToken) — runs the proposed SQL through the same auto-snapshot + query-log + pricing pipeline as query.

Nothing mutates between the two calls. The token is pinned to (api token, databaseId, branchRef); a different bearer can’t redeem it.

SDK

const plan = await db.proposals.propose(
  "UPDATE users SET tier = ? WHERE company_id = ?",
  { params: ["enterprise", 42] }
);

console.log(plan.estimatedAffectedRows);  // e.g. 137
console.log(plan.plan);                   // EXPLAIN QUERY PLAN rows

// Show plan to a human / parent agent. On approval:
const result = await db.proposals.apply(plan.executionToken);

MCP

Two new tools:

• propose_mutation(database, sql, params?, ttlSec?) — returns { sql, plan, estimatedAffectedRows, executionToken, expiresAt, action }.
• apply_mutation(database, executionToken) — single-use redemption. A second call with the same token returns 404.

REST

POST /v1/db/{ns}/{slug}/propose
Authorization: Bearer psql_live_…
Content-Type: application/json

{ "sql": "DELETE FROM events WHERE created_at < ?", "params": [1700000000] }

Response:

{
  "success": true,
  "data": {
    "sql": "DELETE FROM events WHERE created_at < ?",
    "plan": [[0, 0, 0, "SCAN events"]],
    "estimatedAffectedRows": 248912,
    "executionToken": "pmut_…",
    "expiresAt": "2026-05-05T12:30:00.000Z",
    "action": "write"
  }
}

POST /v1/db/{ns}/{slug}/apply
{ "executionToken": "pmut_…" }

Estimated affected rows

For UPDATE … WHERE x and DELETE FROM t WHERE x, the server runs SELECT COUNT(*) FROM t WHERE x to estimate. For INSERT INTO t (...) VALUES (…), (…) it counts tuples. For INSERT … SELECT and other shapes the field is null — apply still works, but you don’t get a preview.

When to use this

• Schema-changing or row-count-amplifying writes you want gated.
• Anywhere a sub-agent should hand off to a parent for review.
• Pair with approval rules — deny rules trip at apply time, but propose lets the agent show the plan before asking the human.