Data and Script Operations

Some tickets need to change something in your live database, not your code. Alchemist calls this a data operation, and it always goes through an explicit approval step before anything touches your database. This guide covers what a data operation is, what happens when you approve one, and how to read the result.

What a data operation is

A data operation is a change to your running, live database, not a code deploy. It’s how an agent fixes bad rows a bug left behind, backfills a column, or runs a one-off script against your project’s real data. It never goes through the normal commit and deploy pipeline: there’s no pull request, no build, no release. It’s the same kind of thing an operator would do by hand from a terminal, except an agent proposes it and you approve it.

There are two shapes:

• A data repair, plain SQL statements (insert, update, delete) proposed against your database.
• A script run, a self-contained script (Deno, bash, or Node) for work that plain SQL can’t do: a backfill that calls your own services, an outbound API replay, or a transform that needs real logic.

The propose, approve, apply lifecycle

1. Propose. The agent authors the exact SQL statements or script and submits them. Nothing runs yet. For SQL, the system dry-runs the statements (executes them and rolls back) so it can show you the real affected-row counts before you decide anything.
2. Approval card. The proposal pauses the ticket and posts an approval card, on the ticket detail page, in the Approvals panel, and in your connected channels if the ticket came from one. The card shows the exact SQL or the full script text, the agent’s rationale, and (for a script) the execution mode, see below.
3. You decide. Approve or decline. Nothing is ever applied without this explicit step, there’s no auto-apply path for a script, and only small, purely additive SQL changes on a project that’s opted in can skip straight through.
4. Apply. On approval, the exact statements or script you saw run server-side against your project’s real database. The ticket resumes with the result.
5. Verify. For most data operations, the agent then runs a read-only check to confirm the database actually reached the expected end state, rather than just trusting that the apply “should have” worked.

What clicking Approve actually does: dry-run vs execute mode

For a script run, the approval card tells you which of two modes you’re approving:

• Execute (the default). Approving this makes the script perform its real writes against your live database. If the script follows the dry-run-first convention (checking for an explicit --execute flag before writing), the platform passes that flag so the write actually happens; a script that doesn’t check for it just runs as written either way.
• Dry run only. Approving this does not pass the execute flag. A script written to check for it performs no writes, it only reports what it would have done. This is for when you want to see a script’s real output before deciding to commit to it.

Either way, the exact script text shown on the card is what runs, verbatim, nothing is re-authored between proposal and apply.

Reading run output and failures

Once a script or SQL statement runs, the result, exit code, captured output, and duration, is written back to the ticket and to the underlying operation record. This happens whether the run succeeds or fails: a failed apply is never left blank. If a script run exits with a non-zero status, you’ll see its captured output (truncated if it’s long) so you can tell what went wrong, and the ticket does not get marked as successfully completed on the strength of a failed run. A ticket whose only script or data operation failed cannot be reported as fully verified; the system checks the operation’s real recorded status, not the agent’s own summary of what happened.

Retry and decline semantics

• Decline and nothing runs. The database is untouched, and the ticket records that you declined, honestly, rather than reporting it as some kind of quiet success.
• Approve a failed run’s follow-up. If a run fails, the agent can diagnose the output and propose a corrected version, you’ll see a fresh approval card for the new attempt; the old failed attempt is never silently retried without your review.
• Every apply is scoped to your project’s own database connection. The lane never has platform-wide credentials and never reaches another tenant’s data.

Next steps

See Answering Agent Questions for where approval cards surface and how replies dispatch follow-up tickets, or Alchemist Tickets for the full ticket lifecycle these approvals pause and resume.