pythia-deploy

Deploying a Release

Announce at start: "Using pythia-deploy — previewing every statement in the release first."

Phase: Ask → Do — the whole ordered set is previewed and approved once, then run step by step

A release script run with sqlplus @release.sql has no snapshot, no preview, no verify and no record of what landed before line 212 failed. pythia deploy runs the same file through the write path, statement by statement, so a failure stops cleanly with an exact list of what landed and how to undo it.

The Iron Law

A RELEASE RUNS IN ORDER, AS PREVIEWED, AND STOPS AT THE FIRST BROKEN STEP

How a script is read

• One statement per ; for SQL; PL/SQL units (`CREATE ... PROCEDURE /

FUNCTION / PACKAGE / TRIGGER / TYPE) end at a line holding only /. A ; or /` inside a literal or a comment is text.

• SQL*Plus directives (SET, PROMPT, SPOOL, SHOW ERRORS, WHENEVER,

DEFINE, …) run nothing on the database: they are skipped and listed.

• @file / @@file includes are refused — list the files instead;

deploy never runs a path nobody looked at.

• Refused, never skipped: anonymous BEGIN ... END; blocks (as in apply),

EXEC / HOST / CONNECT, and ALTER SESSION — it would silently change how every later statement runs, which no preview can show.

• Files run in the order given. A directory runs in natural name order when

every file is numbered (1_, 02_, 10_, Flyway's V3__), otherwise by what each file creates — tables, indexes, comments, types, views, specs, procedures, bodies, triggers, grants, data. The preview says which.

The Workflow

1. Assemble the files in the order they must run; impact

(pythia-impact) for every existing object the release changes.

1. Lint the set: pythia lint <files> — errors are fixed before the

preview, not after.

1. Preview: pythia deploy <files>. Nothing is written. Relay it

verbatim: each statement's group, object, lines changed, impact, ! DESTRUCTIVE and lint lines, the diffs. Policy refusals arrive before anything runs — relay them; the developer decides.

1. Ask once — the preview prints a deploy token (10 hex). The developer

approves it through the first door that works — an AskUserQuestion whose text is pythia approve --card <token> verbatim (Claude Code), the pythia_approve tool (where Codex starts), pythia approve <token> in their terminal — moving to the next unasked when one fails.

1. Run: pythia deploy <files> --confirm <token> — the same file list.

Each statement goes through snapshot → apply → verify with its own journal entry. Read the exit code, unpiped: 0 all landed · 1 refused (nothing after it ran) · 3 written but broken (stopped there).

1. Report every statement's result. On a stop: what landed stays landed

(DDL commits itself); the rest of the approval is withdrawn; the output lists the undo commands newest first, which landed statements have no undo, and the --from N to resume with. Fixing forward or restoring is the developer's call.

Under an autopilot lease (pythia-autopilot) that covers every statement, step 3 lands the release directly; if any statement is not covered the whole release falls back to preview, and the output says which one and why.

Re-running after a stop

The statements before the stop are in the database; CREATE TABLE, ALTER TABLE ADD and inserts cannot run twice. Fix the failing statement, then pythia deploy <files> --from <N> — a fresh preview and a fresh approval for the rest. A backfill that needs a column added earlier in the same release cannot be measured before the DDL exists: deploy the DDL, then the data part with --from.

Red Flags — STOP if you catch yourself thinking

When NOT to use this skill

• One statement in one file → pythia-apply.
• Designing the tables or packages inside the release → pythia-table,

pythia-package; this skill only lands them.