Backstop

execute_query

The primary JSON-RPC tool for executing SQL through the Backstop gateway — request format, all response statuses, and safety_metadata fields.

execute_query is the primary tool for submitting SQL to the Backstop gateway. It classifies, applies policy, verifies recovery readiness when required, and executes only when allowed — returning the full classification metadata alongside the query result.

Request

POST/ query:execute scope

JSON-RPC 2.0 over HTTP POST. Content-Type must be application/json.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "execute_query",
    "arguments": {
      "query": "DELETE FROM sessions WHERE expires_at < NOW()",
      "agent_id": "cursor-local",
      "db_url": "postgresql://postgres:password@localhost:5432/mydb",
      "snapshot_id": "snap_a3f9e2c1"
    }
  }
}

Arguments

ParameterTypeDescription
queryREQUIRED
stringThe SQL statement to execute. Single statement only — batched statements are not supported.
agent_idREQUIRED
stringIdentifier for the submitting agent. Used in audit logs and quarantine tracking.
db_urlOPTIONAL
stringPostgreSQL connection string. If omitted, uses the gateway's default database URL.
snapshot_idOPTIONAL
stringSnapshot ID to include when resubmitting an approved CRITICAL query. Required for CRITICAL operations after approval.

Response statuses

executed

Query was classified, policy allowed it, and it executed successfully.

{
  "status": "executed",
  "risk_level": "SAFE",
  "result_type": "rows",
  "row_count": 1,
  "preview": [{ "count": 127 }],
  "safety_metadata": { ... }
}

Write queries that are approved and executed return command metadata:

{
  "status": "executed",
  "risk_level": "HIGH",
  "result_type": "command",
  "rows_affected": 127,
  "safety_metadata": { ... }
}

blocked

Query was classified and policy blocked it. No execution occurred.

{
  "status": "blocked",
  "risk_level": "CRITICAL",
  "message": "DROP TABLE is blocked by policy",
  "safety_metadata": { ... }
}

approval_required

Query requires operator approval. For table-recoverable CRITICAL operations, the response is bound to a verified recovery point. The agent must resubmit with the same snapshot_id after approval.

{
  "status": "approval_required",
  "risk_level": "CRITICAL",
  "approval_id": "appr_4f9e2c1a",
  "snapshot_id": "snap_a3f9e2c1",
  "message": "CRITICAL operation requires operator approval and verified recovery readiness.",
  "safety_metadata": { ... }
}

denied

An operator explicitly denied the approval. The query will not execute.

{
  "status": "denied",
  "approval_id": "appr_4f9e2c1a",
  "message": "Operator denied execution"
}

failed

Execution failed after approval and gating — a database-level error.

{
  "status": "failed",
  "error": "relation \"users\" does not exist",
  "risk_level": "CRITICAL"
}

safety_metadata fields

ParameterTypeDescription
risk_levelOPTIONAL
stringSAFE, HIGH, IMPACT_CRITICAL, or CRITICAL
operationOPTIONAL
stringSQL operation type: SELECT, INSERT, UPDATE, DELETE, DROP, TRUNCATE, DDL, WRITE, etc.
tableOPTIONAL
stringTarget table name
schemaOPTIONAL
stringTarget schema name (default: public)
table_recoverableOPTIONAL
booleanWhether the table can be recovered from a Parquet snapshot
recovery_requiredOPTIONAL
booleanWhether a snapshot is required before this operation can execute
recovery_possibleOPTIONAL
booleanWhether a valid snapshot currently exists for this table
policy_actionOPTIONAL
stringexecute, approve, or block
policy_reasonOPTIONAL
stringHuman-readable explanation of the policy decision
requires_approvalOPTIONAL
booleanWhether this query requires operator approval
parse_error_presentOPTIONAL
booleanTrue if the SQL could not be fully parsed
estimated_affected_rowsOPTIONAL
numberEstimated rows affected, from PostgreSQL EXPLAIN plan estimates
affected_percentOPTIONAL
numberEstimated percentage of the table affected (0–100)
protected_tableOPTIONAL
booleanTrue if the target table is in protected_tables
protected_columnsOPTIONAL
string[]Any protected columns referenced in this query

Rows response (SELECT)

{
  "status": "executed",
  "risk_level": "SAFE",
  "result_type": "rows",
  "columns": ["id", "email", "created_at"],
  "row_count": 3,
  "rows": [
    { "id": 1, "email": "alice@example.com", "created_at": "2026-01-01T00:00:00Z" },
    { "id": 2, "email": "bob@example.com",   "created_at": "2026-01-02T00:00:00Z" },
    { "id": 3, "email": "carol@example.com", "created_at": "2026-01-03T00:00:00Z" }
  ],
  "preview": [ ... ]
}