How to Safely Promote Database Changes

The Risk of Direct Changes

A mistyped RLS policy, a dropped column or a changed auth setting can take an application down - or open it up. SupaForge's workflow puts a review and a rehearsal between noticing a difference and changing production.

1. Detect - See What Changed

supaforge diff

Every check runs against both environments. Findings are critical, warning or info, and the drift score summarises how far apart the two are.

2. Review - Read the Fixes

supaforge diff --detail

supaforge diff --apply --dry-run

Things worth a second look:

• Data loss - dropped tables or columns, deleted rows. SupaForge holds these back until you add --allow-destructive.
• Type changes - a narrower column type can fail on existing rows.
• Access - a removed policy or grant, or a provider switched off.

Save the plan for review or your change records:

supaforge diff --apply --dry-run > change-plan.txt

3. Rehearse - Prove It First

--prove replays the fixes on a throwaway, structure-only copy of the target, made on the target's own server, and compares the result with the source. If they wouldn't match, nothing is applied and SupaForge lists what would still differ. If the rehearsal can't run - no pg_dump new enough for both servers, say - nothing is applied either, and SupaForge says what to fix. Changes a copy can't hold, such as cron jobs, are listed as not proved.

4. Apply

supaforge diff --apply --prove

Fixes run in dependency order - functions before the triggers that call them, columns before their indexes, drops last - and in one transaction. If any fix fails, the whole set rolls back and the target is exactly as it was.

You don't have to apply everything at once:

supaforge diff --check=schema --apply

supaforge diff --apply --only='rls-missing-*'

Before and After

• Snapshot first. supaforge snapshot --env=production --apply records the target's structure and configuration before you change it.
• Verify after. Run supaforge diff again; a clean run means the environments match.
• Going back. Restore the snapshot into an empty local database with supaforge restore --env=local --from-snapshot=latest --apply, then diff it as the source against production: the fixes are the changes that return production to its previous shape.

Summary

Detect, review, rehearse, apply. Every step before the last one changes nothing, and the last one either succeeds completely or leaves production as it was.