playbooks

home / skills / jeremylongshore / claude-code-plugins-plus-skills / supabase-upgrade-migration

supabase-upgrade-migration skill

/plugins/saas-packs/supabase-pack/skills/supabase-upgrade-migration

This skill analyzes and migrates Supabase SDK upgrades, detects breaking changes, runs tests, and documents rollback steps to ensure safe upgrades.

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

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

Files (4)
SKILL.md
1.2 KB
---
name: supabase-upgrade-migration
description: |
  Execute analyze, plan, and execute Supabase SDK upgrades with breaking change detection.
  Use when upgrading Supabase SDK versions, detecting deprecations,
  or migrating to new API versions.
  Trigger with phrases like "upgrade supabase", "supabase migration",
  "supabase breaking changes", "update supabase SDK", "analyze supabase version".
allowed-tools: Read, Write, Edit, Bash(npm:*), Bash(git:*)
version: 1.0.0
license: MIT
author: Jeremy Longshore <[email protected]>
---

# Supabase Upgrade Migration

## Prerequisites
- Current Supabase SDK installed
- Git for version control
- Test suite available
- Staging environment


See `{baseDir}/references/implementation.md` for detailed implementation guide.

## Output
- Updated SDK version
- Fixed breaking changes
- Passing test suite
- Documented rollback procedure

## Error Handling

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

## Examples

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

## Resources
- [Supabase Changelog](https://github.com/supabase/sdk/releases)
- [Supabase Migration Guide](https://supabase.com/docs/migration)

Overview

This skill automates analysis, planning, and execution of Supabase SDK upgrades while detecting breaking changes and deprecations. It guides upgrades from initial assessment through tests and a safe rollout, producing an upgraded SDK, applied fixes, and rollback documentation. Use it to reduce manual effort and risk when moving between Supabase SDK versions.

How this skill works

The skill inspects the current project for Supabase SDK usage, dependency constraints, and call sites. It runs a compatibility analysis against the target SDK changelog to identify breaking changes and deprecated APIs, then generates a concrete migration plan with code modifications and test updates. Finally, it applies changes in a feature branch, runs the test suite in staging, and produces a rollback procedure if failures occur.

When to use it

  • Upgrading the Supabase SDK to a new major or minor version
  • Detecting and resolving deprecated or removed Supabase APIs
  • Preparing a safe migration plan before applying SDK changes
  • Validating that upgrades pass CI and staging tests
  • Automating repetitive code updates across a codebase

Best practices

  • Run the skill in a local clone or CI job with an up-to-date test suite and staging environment
  • Start with an analysis-only run to review suggested changes before applying them
  • Create a feature branch per upgrade and open a PR with automated test results and migration notes
  • Pin target SDK versions in dependency files to control rollout and enable rollbacks
  • Document manual steps and edge cases in the produced rollback procedure

Example use cases

  • Migrating from Supabase SDK v1.x to v2.x while preserving production stability
  • Detecting deprecated client methods and automatically replacing them with new equivalents
  • Running a pre-release audit to list potential breaking changes across a monorepo
  • Generating a patch that updates tests and fixtures to match new API responses
  • Creating a rollback plan and PR after a failed staging deployment

FAQ

What prerequisites are required to run this skill?

You need the current Supabase SDK installed in the project, Git access, a reliable test suite, and a staging environment.

Does it automatically push changes to production?

No. It creates a feature branch, applies changes, and runs tests in staging. Production deployment should follow your standard release process.