Skip to main content
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

  1. Pre-Migration Checklist
  2. RLS Policy Rollback Procedures
  3. Emergency Rollback Steps
  4. Policy State Capture Scripts
  5. Testing Rollback
  6. Rollback Templates

Pre-Migration Checklist

Before applying any migration that modifies RLS policies:

1. Document Current State

2. Create Rollback SQL

For every CREATE 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:
  1. DROP POLICY IF EXISTS
  2. CREATE POLICY with new definition
This ensures atomic changes and clean rollback.

Standard Rollback Pattern

Rolling Back Multiple Policies

Wrap in a transaction for atomicity:

Emergency Rollback Steps

Severity Levels

Critical Emergency Procedure

  1. Identify the Problem
  2. Disable Problematic Policies Immediately
  3. Notify Stakeholders
    • Alert development team
    • Document incident timeline
    • Prepare communication for affected users
  4. Apply Proper Rollback
    • Execute pre-prepared rollback SQL
    • Verify with test suite
    • Monitor for 30 minutes
  5. 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

  1. Always prepare rollback SQL before migration
  2. Test in staging first
  3. Use transactions for atomic rollbacks
  4. Never modify policies in-place - always DROP + CREATE
  5. Document every rollback with date and reason
  6. Run verification queries after every rollback
  7. Keep rollback SQL files version-controlled
  8. Set up monitoring alerts for RLS failures


Changelog