pythia-deploy

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

开始时声明： "正在使用 pythia-deploy —— 首先预览发布版本中的每条语句。"

阶段： Ask → Do —— 先对整个有序语句集完成一次预览和批准，再逐步运行

使用

sqlplus @release.sql

运行发布脚本时，没有 snapshot、preview、verify，也不会记录第 212 行失败之前哪些内容已成功落地。

pythia deploy

会让同一个文件通过写入路径逐条运行，因此一旦失败便可安全停止，并精确列出成功落地了哪些内容，以及如何撤销。

The Iron Law

铁律

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

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.

对于 SQL，每个
```
;
```
对应一条语句；PL/SQL 单元（
```
CREATE ... PROCEDURE / FUNCTION / PACKAGE / TRIGGER / TYPE
```
）以一行中只有
```
/
```
的形式结束。字面量或注释内的
```
;
```
或
```
/
```
视为文本。
SQL*Plus 指令（
```
SET
```
、
```
PROMPT
```
、
```
SPOOL
```
、
```
SHOW ERRORS
```
、
```
WHENEVER
```
、
```
DEFINE
```
、…）不会在数据库上执行任何操作：它们会被跳过并列入清单。
```
@file
```
/
```
@@file
```
include 会被拒绝——应改为列出文件；deploy 绝不会运行任何未经查看的路径。
拒绝而非跳过：匿名
```
BEGIN ... END;
```
块（与
```
apply
```
中一样）、
```
EXEC
```
/
```
HOST
```
/
```
CONNECT
```
和
```
ALTER SESSION
```
——它们会静默改变后续每条语句的执行方式，而任何 preview 都无法呈现这种变化。
文件按给定顺序运行。当目录中的每个文件都有编号（
```
1_
```
、
```
02_
```
、
```
10_
```
、Flyway 的
```
V3__
```
）时，目录按名称的自然顺序运行；否则按每个文件创建的对象排序——表、索引、注释、类型、视图、spec、procedure、body、trigger、grant、数据。preview 会说明采用了哪种顺序。

The Workflow

工作流

Assemble the files in the order they must run; impact (
```
pythia-impact
```
) for every existing object the release changes.
Lint the set:
```
pythia lint <files>
```
— errors are fixed before the preview, not after.
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.
Ask once — the preview prints a deploy token (10 hex). The developer approves it through one door: the
```
pythia_approve
```
tool, an
```
AskUserQuestion
```
whose text is
```
pythia approve --card <token>
```
verbatim, or
```
pythia approve <token>
```
in their terminal.
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).
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.

组装：按必须运行的顺序整理文件；对发布版本所修改的每个现有对象执行 impact （
```
pythia-impact
```
）。
Lint 这一组文件：
```
pythia lint <files>
```
——在 preview 之前修复错误，而不是之后。
Preview：
```
pythia deploy <files>
```
。不会写入任何内容。请逐字转述 preview：每条语句所属的 group、object、变更行数、impact、
```
! DESTRUCTIVE
```
和 lint 行、diff。策略性拒绝会在任何内容运行之前返回——请转述这些拒绝；由开发者决定。
只询问一次——preview 会打印一个 deploy token（10 个十六进制字符）。开发者通过一个统一入口完成批准：
```
pythia_approve
```
工具、一个文本逐字为
```
pythia approve --card <token>
```
的
```
AskUserQuestion
```
，或者在终端中运行
```
pythia approve <token>
```
。
运行：
```
pythia deploy <files> --confirm <token>
```
——使用同一个文件列表。每条语句都会依次经过 snapshot → apply → verify，并各自生成一条 journal entry。读取退出码时不要使用管道：
```
0
```
全部执行成功 ·
```
1
```
已拒绝（其后没有任何内容运行） ·
```
3
```
已写入但损坏（已在此处停止）。
报告每条语句的结果。发生停止时：已成功落地的内容会保留（DDL 会自动提交）；本次批准中其余语句的授权会被撤回；输出会按从新到旧的顺序列出 undo 命令、哪些已落地语句没有 undo，以及恢复执行时使用的
```
--from N
```
。是向前修复还是恢复，由开发者决定。

在覆盖每一条语句的 autopilot lease（

pythia-autopilot

）下，步骤 3 会直接执行该发布版本；如果有任何语句未被覆盖，整个发布版本都会回退到 preview，输出会说明是哪一条语句以及原因。

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

停止之前执行的语句已经进入数据库；

CREATE TABLE

、

ALTER TABLE ADD

和 insert 操作无法运行两次。修复失败的语句，然后运行

pythia deploy <files> --from <N>

——剩余语句需要一次全新的 preview 和新的批准。某个 backfill 如果依赖同一发布版本中更早添加的列，那么在 DDL 存在之前无法对其执行度量：先部署 DDL，再使用

--from

部署数据部分。

Red Flags — STOP if you catch yourself thinking

危险信号——如果你发现自己在想以下内容，请立即停止

Thought	Reality
"Faster to run it in sqlplus"	And no snapshot, no verify, no record of where it stopped. The hook denies it anyway.
"Statement 7 failed, skip it and continue"	The rest was ordered on top of it. Stop, report, let the developer decide.
"The includes are fine, I wrote them"	Deploy runs what was listed and previewed. List them.
"One approval covered the release, so I can edit a file and re-run"	The token binds the previewed content. Edited → preview again.
"Exit 3 on the last statement, everything else is fine"	Written but broken. Report it as broken, with the undo list.

想法	实际情况
"用 sqlplus 运行会更快"	而且没有 snapshot、没有 verify，也没有停止位置的记录。hook 无论如何都会拒绝它。
"第 7 条语句失败了，跳过它继续执行"	后续语句依赖它。停止并报告，由开发者决定。
"include 没问题，是我写的"	Deploy 只运行已列出并预览过的内容。请将它们列出来。
"一次批准覆盖了整个发布版本，所以我可以修改文件后重新运行"	token 与已预览的内容绑定。修改后必须重新 preview。
"最后一条语句的退出码是 3，其他都没问题"	已写入但损坏。按损坏状态报告，并附上 undo 列表。

When NOT to use this skill

不应使用此 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.

一个文件中只有一条语句 →
```
pythia-apply
```
。
设计发布版本中要包含的表或 package →
```
pythia-table
```
、
```
pythia-package
```
；此 skill 只负责将它们落地。