Rehearse a held schema change, decide it in the console, and let the
caller’s next tide apply pick up the decision.
Why the change is waiting
Four policies compose, and the most restrictive answer wins:
- The change policy: per class — additive, backfill-required, cross-caller breaking, destructive — apply unattended or wait.
- The caller’s apply-policy tier. The refusal says when the tier is
what queued it. The
sandbox_onlytier refuses every apply outright; no approval unblocks it. - Protected entities — a change touching one always waits.
- Freeze windows — during a freeze, approved changes are refused too.
Change approval covers the model; this guide is the workflow.
1. Open the queue
Console → Approvals. Each waiting plan shows its class, the caller, who requested it (or unattributed, for an unattended pipeline), the deciding role, its expiry, and its rehearsal verdict once one has run.
2. Read the change
Review opens the plan: the proposed .atl source first, then the SQL
that will run. The approval you give binds to exactly this content: if the
caller submits anything different, the decision does not carry over.
3. Rehearse it
Rehearse executes the plan’s SQL against a disposable clone of the
real database and lands the verdict on the row: pass,
pass_with_warnings, fail_data with the violating constraint and
counts, fail_structural, or unverified. Rehearsing needs the
developer or admin role, and takes as long as cloning the database.
From the terminal, tide rehearse
runs the same rehearsal against your working tree, exiting 0 on a pass, 2
on a failure and 4 when the clone could not verify, so a caller can pre-clear a
change before it reaches the queue.
A fail_data verdict means the apply would fail the same way; reject with
the verdict’s remediation as the reason rather than approving a change that
cannot land.
4. Decide
- Approve re-authenticates you at Cloud, then records the decision. The approval covers this exact content and lasts until the plan’s expiry, seven days from when the change was requested.
- Reject requires a reason and needs no re-authentication. The caller sees only that reason.
- Override (admins) approves past a freeze window, a protected-entity floor, or the self-approval refusal, with a mandatory recorded reason.
You cannot approve a plan you requested; another holder of the deciding role decides it, or an admin overrides.
5. The caller applies
The caller re-runs tide apply, or is already waiting with
--wait-for-approval, which polls every 15 seconds and picks the decision
up on its next poll. During a freeze window the server refuses even an
approved apply and names the window: a plain tide apply exits and is
re-run after the window lifts, while a still-running --wait-for-approval
keeps retrying and applies when it does.
Verify
The plan shows applied in the queue’s history, and the console’s History
page carries the new version with the approver recorded beside the caller.
Change the rules
Settings → Change policy edits the per-class rules, protected entities, and freeze windows; the Callers page sets each caller’s tier and rehearsal grant. Every edit re-authenticates you and is recorded.
Related
- Change approval — tiers, verdicts, overrides, expiry.
- Manage members and callers — tiers and the rehearsal grant.
- Set up CI — pipelines that wait for decisions.