Version: 1.0.0
Last Updated: 2026-01-11
Status: Active
Overview
This document provides guidelines and procedures for safely reverting database migrations, with a focus on RLS (Row Level Security) policy changes. Following these procedures ensures minimal downtime and prevents data exposure during rollback operations.Table of Contents
- Pre-Migration Checklist
- RLS Policy Rollback Procedures
- Emergency Rollback Steps
- Policy State Capture Scripts
- Testing Rollback
- Rollback Templates
Pre-Migration Checklist
Before applying any migration that modifies RLS policies:1. Document Current State
2. Create Rollback SQL
For everyCREATE POLICY, prepare the inverse DROP POLICY:
3. Test in Staging
- Apply migration to staging environment
- Run RLS test suite
- Verify no recursion risks
- Confirm multi-tenant isolation
- Test all CRUD operations
4. Backup Policy Definitions
Save the output of the state capture script to a file before migration:RLS Policy Rollback Procedures
Principle: Never Modify Policies In-Place
Always use the pattern:DROP POLICY IF EXISTSCREATE POLICYwith new definition
Standard Rollback Pattern
Rolling Back Multiple Policies
Wrap in a transaction for atomicity:Emergency Rollback Steps
Severity Levels
Critical Emergency Procedure
-
Identify the Problem
-
Disable Problematic Policies Immediately
-
Notify Stakeholders
- Alert development team
- Document incident timeline
- Prepare communication for affected users
-
Apply Proper Rollback
- Execute pre-prepared rollback SQL
- Verify with test suite
- Monitor for 30 minutes
-
Post-Incident Review
- Document root cause
- Update rollback procedures if needed
- Add regression tests
Policy State Capture Scripts
Capture All Policies
Capture Policies for Specific Tables
Generate DROP Statements for New Policies
Testing Rollback
Verification Queries
After rollback, run these checks:RLS Test Suite
Run the full RLS test suite after rollback:Rollback Templates
Template A: Single Policy Rollback
Template B: Multi-Table Rollback
Template C: Helper Function Rollback
Best Practices Summary
- Always prepare rollback SQL before migration
- Test in staging first
- Use transactions for atomic rollbacks
- Never modify policies in-place - always DROP + CREATE
- Document every rollback with date and reason
- Run verification queries after every rollback
- Keep rollback SQL files version-controlled
- Set up monitoring alerts for RLS failures