---
title: "Approve a schema change"
description: "Rehearse a held schema change, decide it in the console, and let the caller's next tide apply pick up the decision."
---

> Documentation Index
> Fetch the complete documentation index at: https://docs.tryatlantis.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Approve a schema change

Rehearse a held schema change, decide it in the console, and let the
caller's next `tide apply` pick up the decision.

> **Prerequisites**
>
> - A change waiting on a decision — `tide apply` exited 2 and printed the
> plan id and the role that decides.
> - The role the change needs: the class rule names `admin` or `developer`,
> and a protected entity's `admin_only` floor demands an admin whatever the
> rule says.

## 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_only` tier 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](/concepts/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`](/reference/cli-tide/#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](/concepts/change-approval/) — tiers, verdicts,
  overrides, expiry.
- [Manage members and callers](/guides/manage-members-and-callers/) — tiers and
  the rehearsal grant.
- [Set up CI](/guides/set-up-ci/) — pipelines that wait for decisions.

Source: https://docs.tryatlantis.dev/guides/approve-a-schema-change/index.mdx