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

# Idempotent migrations

> Generate and check replay-safe PostgreSQL migrations that can run more than once without failing on existing objects.

Use this when a migration must survive retries after a partial deploy.

`supaschema` renders guarded DDL where PostgreSQL supports it and catalog-checked blocks where it does not. The goal is simple: a second apply should converge instead of failing on objects that already exist.

## Use this when

* Deploy jobs can be retried after timeouts, locks, or crashes.
* Migration files are reviewed before a database has caught up.
* Existing migrations need static safety checks.
* CI should reject unguarded DDL or unsafe `CASCADE`.

## Do this

Generate migrations from the schema tree:

```bash theme={null}
npx supaschema diff
```

Check generated or hand-written files:

```bash theme={null}
npx supaschema check database/migrations/*.sql
```

Use exact destructive hints only for reviewed object keys. Broad drops are not an idempotency shortcut.

## Verify

When a disposable database is available, prove replay behavior:

```bash theme={null}
npx supaschema verify
```

For pull request annotations or code scanning:

```bash theme={null}
npx supaschema check --reporter github
npx supaschema check --reporter sarif
```

## Related

<CardGroup cols={2}>
  <Card title="Check command" icon="shield-check" href="/docs/commands/check">
    See diagnostics and reporter flags.
  </Card>

  <Card title="Verify command" icon="repeat-2" href="/docs/commands/verify">
    Apply pending migrations twice in a disposable database.
  </Card>

  <Card title="Destructive hints" icon="triangle-alert" href="/docs/configuration/hints">
    Approve risky operations deliberately.
  </Card>

  <Card title="Migration pipeline" icon="route" href="/docs/concepts/migration-pipeline">
    See how diff, check, and verify fit together.
  </Card>
</CardGroup>