playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / supabase-migration-deep-dive

supabase-migration-deep-dive skill

/plugins/saas-packs/supabase-pack/skills/supabase-migration-deep-dive

This skill guides you through a Strangler Fig based Supabase migration, from assessment to traffic shift, ensuring safe major re-architecture.

npx playbooks add skill jeremylongshore/claude-code-plugins-plus-skills --skill supabase-migration-deep-dive

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
1.5 KB
---
name: supabase-migration-deep-dive
description: |
  Execute Supabase major re-architecture and migration strategies with strangler fig pattern.
  Use when migrating to or from Supabase, performing major version upgrades,
  or re-platforming existing integrations to Supabase.
  Trigger with phrases like "migrate supabase", "supabase migration",
  "switch to supabase", "supabase replatform", "supabase upgrade major".
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(node:*), Bash(kubectl:*)
version: 1.0.0
license: MIT
author: Jeremy Longshore <[email protected]>
---

# Supabase Migration Deep Dive

## Prerequisites
- Current system documentation
- Supabase SDK installed
- Feature flag infrastructure
- Rollback strategy tested

## Instructions

### Step 1: Assess Current State
Document existing implementation and data inventory.

### Step 2: Build Adapter Layer
Create abstraction layer for gradual migration.

### Step 3: Migrate Data
Run batch data migration with error handling.

### Step 4: Shift Traffic
Gradually route traffic to new Supabase integration.

## Output
- Migration assessment complete
- Adapter layer implemented
- Data migrated successfully
- Traffic fully shifted to Supabase

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

## Examples

See `{baseDir}/references/examples.md` for detailed examples.

## Resources
- [Strangler Fig Pattern](https://martinfowler.com/bliki/StranglerFigApplication.html)
- [Supabase Migration Guide](https://supabase.com/docs/migration)

Overview

This skill executes a major Supabase re-architecture and migration strategy using the strangler fig pattern for safe, incremental replacement. It guides teams through discovery, adapter implementation, data migration, and traffic shifting so you can replatform or upgrade with minimal disruption. The goal is clear checkpoints: assessment, adapter layer, data migration, and full traffic cutover.

How this skill works

The skill inspects your current system documentation and inventory to produce a migration assessment. It helps you design and implement an adapter layer that lets old and new systems coexist. It automates batch data migration with error handling and recommends phased traffic routing using feature flags and progressive rollout. Rollback strategies and testing are integrated into each stage to reduce risk.

When to use it

  • Replatforming an existing product to Supabase
  • Performing a major Supabase version upgrade that changes APIs or schemas
  • Gradually replacing legacy data stores with Supabase using the strangler fig pattern
  • When you need zero-downtime migration with rollback and feature-flagged rollout
  • Switching third-party integrations to Supabase-backed services

Best practices

  • Start with a full assessment and data inventory to scope migration work
  • Implement an adapter/abstraction layer to decouple callers from Supabase internals
  • Use feature flags to progressively route traffic and enable quick rollback
  • Run idempotent, logged batch migrations with retry and dead-letter handling
  • Test rollback and recovery paths before shifting significant traffic

Example use cases

  • Migrating user and session storage from a legacy PostgreSQL instance to Supabase while keeping the old API for remaining services
  • Upgrading Supabase major version with schema changes: migrate data in batches, validate, then flip traffic by feature flag
  • Replatforming file storage to Supabase Storage and gradually updating client SDKs through an adapter layer
  • Consolidating multiple microservices data into a single Supabase project while keeping legacy services operational

FAQ

How long does a migration typically take?

Duration varies by data size and complexity; small apps can finish in days, larger systems may take weeks. Plan by data volume, integration count, and testing cycles.

What if a batch migration fails?

Use idempotent operations, log failures to a dead-letter queue, retry after fixes, and rely on the tested rollback strategy to restore service quickly.