Supabase Schema Sync Action

Synchronize database schemas between local and remote Supabase environments with diff comparison and conflict resolution.

When to Use This Command

Run this command when you need to:

• Compare your local database schema against a remote Supabase project and identify differences
• Pull remote schema changes into your local migration files after dashboard edits
• Push local schema changes to a remote environment with conflict detection and resolution

Consider alternatives when:

• You need to create new migrations from scratch (use supabase-migration-assistant-launcher)
• You want to back up the full database including data (use quick-supabase-backup-manager)

Quick Start

Configuration

Copy
name: supabase-schema-sync-action
type: command
category: database

Example Invocation

Copy
claude command:run supabase-schema-sync-action --action diff --target staging

Example Output

[Connect] Local: supabase/migrations/ (14 files)
[Connect] Remote: myapp-staging (us-east-1)
[Compare] Analyzing schema differences...

[Diff Report]
  + Remote has table: analytics_events (not in local migrations)
  ~ Column type mismatch: users.metadata (local: JSON, remote: JSONB)
  - Local has index: idx_orders_status (not on remote)

[Recommendation]
  1. Pull analytics_events table definition into new migration
  2. Create migration to alter users.metadata from JSON to JSONB
  3. Push idx_orders_status index to remote

[Action] Run with --action pull to sync remote changes locally

Core Concepts

Schema Sync Overview

Aspect	Details
Comparison	Structural diff of tables, columns, indexes, constraints, functions
Directions	Pull (remote to local), push (local to remote), bidirectional diff
Conflict Handling	Interactive resolution for conflicting changes with dry-run preview
Safety	Backup creation before any push operation; dry-run mode by default

Sync Workflow

[Connect Local + Remote]
          |
[Extract Both Schemas]
          |
[Compute Structural Diff]
    /          \
[Additions] [Conflicts]
    |            |
[Generate Migration] [Interactive Resolution]
          |
[Apply Direction: Pull or Push]
          |
[Validate + Report]

Configuration

Parameter	Type	Default	Description
action	string	diff	Operation: diff, pull, push, or validate
target	string	required	Remote environment: staging, production, or project ref
dry-run	boolean	true	Preview changes without applying them
include-rls	boolean	true	Include RLS policies in schema comparison
backup	boolean	true	Create backup before push operations

Best Practices

1. Always Diff Before Sync - Run --action diff first to review all differences. Blindly pulling or pushing without understanding the delta can overwrite intentional divergences between environments.

2. Pull Dashboard Changes Promptly - When team members make schema changes via the Supabase dashboard, pull those changes into migration files immediately. Untracked remote changes create invisible drift.

3. Use Dry-Run for Push Operations - Keep --dry-run true for push operations until you have reviewed the generated SQL. One accidental column drop in production is one too many.

4. Include RLS in Comparisons - Schema diffs that ignore RLS policies miss critical security configuration. Always include --include-rls to catch policy discrepancies between environments.

5. Commit Sync Results to Version Control - After pulling remote changes, commit the generated migration files immediately. This ensures the team has a single source of truth for the schema.

Common Issues

1. Diff Shows Phantom Differences - Column order or default value formatting may differ between environments without functional impact. Use --ignore-cosmetic to filter non-functional differences.

2. Push Blocked by Foreign Key Dependencies - Tables with foreign key references must be synced in dependency order. The command resolves this automatically, but circular dependencies require manual intervention.

3. Conflicting Migrations After Pull - If local migrations already exist for changes that were also made on remote, the pull creates duplicate migrations. Review and deduplicate before applying.