sqlplan

Overview ¶

Package sqlplan turns the apply SQL of a nuzur schema push into something a human can decide on: an ordered statement list, each labelled with what it does and what it can cost.

It exists because the CLI receives the migration as one opaque string. sql-push hands over the exact DDL it is about to run — see the confirmation step in extension-sql-push's manager — and nothing between there and here says which of those statements deletes a table.

What this package cannot know ¶

Read this before trusting its output, and before extending it. A preview users over-trust is worse than no preview.

1. No per-statement hazards. pg-schema-diff computes Statement.Hazards, Timeout and LockTimeout for every statement it generates, and every one of those is discarded before the CLI sees it (in the local agent's pg-schema-plan handler, twice in nuzur-go's sql-diff-manager, and finally by the wire types themselves — ComputePgSchemaPlanResponse.apply_sql and GetChangesDiffResponse.apply are plain strings). So this package cannot tell you which statements take an ACCESS EXCLUSIVE lock and therefore take the table offline, which are multi-hour index builds, or which the differ itself considered correctness-affecting. It re-derives only what a keyword can see.
2. No row counts. "DROP TABLE audit_log_2023" cannot be annotated with how many rows that is; nothing in the path counts.
3. No idea whether an ALTER will succeed. Adding a foreign key against orphan rows, SET NOT NULL against nulls, a unique index against duplicates: all of those are flagged "may fail", never resolved. pg-schema-diff could resolve them by validating against a temporary database, but nuzur asks it not to.
4. Atomicity is engine- and content-dependent, and this package reports it rather than guarantees it. sql-push now asks for a transaction, so on Postgres a migration is applied as one unit and a failure rolls the whole thing back — EXCEPT when the batch contains something Postgres cannot run inside a transaction block (CREATE/DROP INDEX CONCURRENTLY, VACUUM, CREATE/DROP DATABASE, ALTER SYSTEM, TABLESPACE operations), which downgrades the whole batch to the old statement-at-a-time path. On MySQL the transaction is opened but DDL commits implicitly, so it is best-effort only and a failure at statement 7 of 12 still leaves 1 through 6 applied. TransactionalWarning says which of those a given plan gets; it cannot change any of them.
5. MySQL diffs contain churn this package cannot identify. nuzur cannot read a MySQL schema directly, so the "existing" side is reconstructed by introspecting the database into a project version and re-rendering it as DDL. Anything the model cannot express comes back normalized, producing statements that change nothing and reappear on every deploy. They take two shapes — column redefinitions (the narrowing class) and index drop/re-add pairs, when the reconstruction loses an index's type — and ChurnNote counts both. A caller with a MySQL target should say so out loud.

The one thing it is careful to get right is the data-loss class, because that is what a caller gates on. Everything unrecognized is KindOther at SeverityNone: never read "not flagged" as "proven safe".