How to Safely Promote Database Changes

The Risk of Direct Changes

Applying changes directly to production without review is the leading cause of Supabase incidents. A mistyped RLS policy, a dropped column, or a changed auth setting can take down an application instantly.

SupaForge's promote workflow gives you a safety net: scan for differences, preview the exact changes, and apply them only after review.

The Three-Step Workflow

1. Scan — Detect What Changed

Run a full scan to see every difference across all checks:

supaforge scan

Review the drift score and per-check findings. Each issue includes severity (critical, warning, info) to help you prioritize.

2. Dry Run — Preview the Fix

The promote command is a dry-run by default — it shows every SQL statement and API call that would be executed, without making any changes to the target:

supaforge promote

This is the review step. Read through each statement. Look for:

• Destructive operations — DROP TABLE, DROP COLUMN, DELETE FROM.
• Data loss risk — column type changes that truncate data.
• Auth changes — disabling a provider that active users depend on.
• RLS changes — removing a policy that protects sensitive data.

3. Promote — Apply Changes

Once you've reviewed the dry-run output and are satisfied, add the--apply flag to execute the changes:

supaforge promote --apply

Promote Specific Checks

You don't have to promote everything at once. Promote individual checks for more granular control:

supaforge promote --check schema --apply

supaforge promote --check rls

Save Output for Audit

Pipe the promote preview to a file for team review or compliance records:

supaforge promote > promote-plan.txt

Rollback Strategy

SupaForge generates both UP (apply) and DOWN (rollback) SQL for schema changes. If a promote goes wrong:

1. Swap source and target in your config to generate the reverse migration.
2. Run a dry run with the swapped config to preview the rollback.
3. Promote to apply the rollback.

For non-SQL changes (auth settings, storage config), the Supabase Dashboard provides immediate manual override.

Summary

The scan → dry-run → promote workflow gives you full visibility and control over every change applied to production. Never promote blind — always review the dry-run output first.