Agent skill

Supabase Upgrade Migration

by jeremylongshore in jeremylongshore/tons-of-skills-marketplace

Upgrade Supabase SDK and CLI versions with breaking-change detection and automated code migration.

MITAuto-check passedDevelopment

Install Supabase Upgrade Migration

skills CLI
$ npx skills add jeremylongshore/tons-of-skills-marketplace --skill supabase-upgrade-migration -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install jeremylongshore/tons-of-skills-marketplace supabase-upgrade-migration --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/jeremylongshore/tons-of-skills-marketplace.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/.curated/supabase-upgrade-migration .claude/skills/supabase-upgrade-migration && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
supabase-upgrade-migration
GitHub stars
2.8k
Token cost
~2.8k tokens
SKILL.md length
553 words
Files
4 (incl. references)
Skills in repo
3,342
Repo updated
First seen
Licence
MIT

At a glance

Upgrade Supabase SDK and CLI versions with breaking-change detection and automated code migration.

  • Works in 3 steps: Audit Versions, Scan Usage, and Review… → Run the Upgrade and Apply Code Migrations → Verify, Test, and Prepare Rollback
  • Upgrading @supabase/supabase-js (v1→v2
  • SKILL.md covers Overview, Current State, Prerequisites and Instructions, plus 5 more sections
  • Calls npm, pip and npx; needs NEXT_PUBLIC_SUPABASE_ANON_KEY

What it does

Supabase Upgrade Migration is an agent skill from jeremylongshore/tons-of-skills-marketplace. Upgrade Supabase SDK and CLI versions with breaking-change detection and automated code migration. Use when upgrading @supabase/supabase-js (v1→v2 or minor bumps), migrating auth/realtime/storage APIs, or updating the Supabase CLI. Trigger with phrases like "upgrade supabase", "supabase breaking changes", "migrate supabase v2", "update supabase SDK".

Its SKILL.md is about 2.8k tokens, which your agent loads only when the skill is triggered. The skill folder holds 4 other files, including reference files (for example `references/errors.md`, `references/examples.md` and `references/implementation.md`). Compatibility notes: Designed for Claude Code

It sits in Development, covering Code migrations and Anomaly detection. It works with Supabase and Python. The repository describes itself as: Model-agnostic agent-skills platform with a harness-free canonical layer, verified adapters, and the ccpi package manager. Explore at tonsofskills.com. The licence is MIT.

When your agent uses it

  • Upgrading @supabase/supabase-js (v1→v2
  • Migrating auth/realtime/storage APIs
  • Updating the Supabase CLI
  • With phrases like upgrade supabase

Example prompts

  • “upgrade supabase”
  • “supabase breaking changes”
  • “migrate supabase v2”
  • “/supabase-upgrade-migration”

Requirements

  • Python 3
  • Node.js
  • A credential in NEXT_PUBLIC_SUPABASE_ANON_KEY
  • Compatibility (from SKILL.md): Designed for Claude Code
  • Pre-approved tools (allowed-tools): Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(pip:*), Bash(supabase:*), Bash(git:*), Grep, Glob

Workflow steps

3 steps, taken from the step headings in SKILL.md.

  1. Audit Versions, Scan Usage, and Review Breaking Changes
  2. Run the Upgrade and Apply Code Migrations
  3. Verify, Test, and Prepare Rollback

What it can do on your machine

Read from SKILL.md and the folder at commit cfae287. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves these tools, so the agent can use them without asking each time:

    • Read
    • Write
    • Edit
    • Bash(npm:*)
    • Bash(npx:*)
    • Bash(pip:*)
    • Bash(supabase:*)
    • Bash(git:*)
    • Grep
    • Glob

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    Shell commands in SKILL.md call:

    • npm
    • pip
    • npx
    • supabase
    • git
    • python

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    Links to these hosts (documentation or services it may open):

    • github.com
    • supabase.com

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names these keys or tokens, usually read from environment variables:

    • NEXT_PUBLIC_SUPABASE_ANON_KEY

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

  • Compatibility

    Designed for Claude Code

    From compatibility in the SKILL.md frontmatter.

Context cost

Supabase Upgrade Migration loads about 2.8k tokens when it runs, and up to ~3.3k if it reads all its reference files. Until then it costs about 95 tokens; SKILL.md has 553 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~95
When it runs · the whole SKILL.md, loaded when a task matches
~2.8k
With references · SKILL.md plus every file in references/, read only if the agent opens them
~3.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from jeremylongshore/tons-of-skills-marketplace at commit cfae287, republished under its MIT licence (© jeremylongshore). 553 words, ~2,750 tokens.

Download SKILL.mdSave it as .claude/skills/supabase-upgrade-migration/SKILL.md (or your agent's skills folder). This skill also uses 3 other files; get the full folder from GitHub.
name
supabase-upgrade-migration
description
Upgrade Supabase SDK and CLI versions with breaking-change detection and automated code migration. Use when upgrading @supabase/supabase-js (v1→v2 or minor bumps), migrating auth/realtime/storage APIs, or updating the Supabase CLI. Trigger with phrases like "upgrade supabase", "supabase breaking changes", "migrate supabase v2", "update supabase SDK".
allowed-tools
Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(pip:*), Bash(supabase:*), Bash(git:*), Grep, Glob
compatibility
Designed for Claude Code
version
1.54.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
saas, supabase, migration, upgrade, sdk

Supabase Upgrade Migration

Overview

Upgrade @supabase/supabase-js and the Supabase CLI with breaking-change detection, automated code migration, and rollback planning. Covers the v1-to-v2 migration path (auth method renames, data/error destructuring, realtime API overhaul), minor version bumps, @supabase/ssr adoption, and Python SDK upgrades via pip install --upgrade supabase.

Current State

!npm list @supabase/supabase-js 2>/dev/null | grep supabase || echo 'supabase-js not installed' !supabase --version 2>/dev/null || echo 'CLI not installed' !pip show supabase 2>/dev/null | grep Version || echo 'Python SDK not installed'

Prerequisites

  • @supabase/supabase-js or the Python supabase package installed in the project
  • Git with a clean working tree (no uncommitted changes)
  • Test suite available for post-upgrade verification
  • Node.js >= 18 (for supabase-js v2) or Python >= 3.8 (for Python SDK)

Instructions

Step 1: Audit Versions, Scan Usage, and Review Breaking Changes

Check every installed Supabase package and find all import sites in the codebase.

bash
# Check current SDK version
npm list @supabase/supabase-js

# Check CLI version
supabase --version

# Check Python SDK version
pip show supabase | grep Version

# Find all JS/TS Supabase imports
grep -rn "from '@supabase/supabase-js'" --include="*.ts" --include="*.tsx" --include="*.js" src/ lib/ app/ 2>/dev/null
grep -rn "createClient" --include="*.ts" --include="*.tsx" --include="*.js" src/ lib/ app/ 2>/dev/null

# Find all Python Supabase imports
grep -rn "from supabase" --include="*.py" src/ app/ 2>/dev/null

supabase-js v1 → v2 breaking changes:

v1 Patternv2 ReplacementNotes
createClient(url, key)createClient(url, key)Signature unchanged, but return type differs
supabase.auth.session()supabase.auth.getSession()Sync → async, returns { data: { session } }
supabase.auth.user()supabase.auth.getUser()Sync → async, returns { data: { user } }
supabase.auth.signIn({ email, password })supabase.auth.signInWithPassword({ email, password })Method split by auth type
supabase.auth.signIn({ provider: 'google' })supabase.auth.signInWithOAuth({ provider: 'google' })OAuth separated
supabase.auth.signIn({ email })supabase.auth.signInWithOtp({ email })Magic link separated
supabase.auth.api.resetPasswordForEmail(e)supabase.auth.resetPasswordForEmail(e).api namespace removed
{ data: subscription } from onAuthStateChange{ data: { subscription } }Extra destructuring level
error.message string parsingerror.code enum (PGRST116, etc.)Reliable error matching
.single() returns error on 0 rows.maybeSingle() for optional rowsNew method for nullable results
supabase.from('t').on('INSERT', cb).subscribe()supabase.channel('c').on('postgres_changes', ...).subscribe()Realtime v2 channel API
supabase.storage.from('b').download('path')Same, but returns { data: Blob, error }Consistent error/data tuple

Realtime v2 migration detail:

typescript
// v1 realtime
supabase
  .from('messages')
  .on('INSERT', (payload) => console.log(payload.new))
  .subscribe()

// v2 realtime — channel-based API
supabase
  .channel('messages-insert')
  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'messages' },
    (payload) => console.log(payload.new))
  .subscribe()
Step 2: Run the Upgrade and Apply Code Migrations

Create a branch, install new packages, and transform code to match v2 APIs.

bash
# Create upgrade branch
git checkout -b upgrade-supabase-sdk

# Upgrade JS/TS SDK
npm install @supabase/supabase-js@latest

# Upgrade SSR helper (if used with Next.js/SvelteKit/Nuxt)
npm install @supabase/ssr@latest

# Upgrade CLI
npm install -g supabase@latest

# Upgrade Python SDK
pip install --upgrade supabase

# Regenerate TypeScript types from linked project
npx supabase gen types typescript --linked > lib/database.types.ts

# Generate a database migration if schema drifted
npx supabase db diff --use-migra -f upgrade_check

Apply auth code migrations:

typescript
// BEFORE (v1 auth patterns)
const session = supabase.auth.session()
const user = supabase.auth.user()
const { error } = await supabase.auth.signIn({ email, password })
const { data: subscription } = supabase.auth.onAuthStateChange(callback)

// AFTER (v2 auth patterns)
const { data: { session } } = await supabase.auth.getSession()
const { data: { user } } = await supabase.auth.getUser()
const { error } = await supabase.auth.signInWithPassword({ email, password })
const { data: { subscription } } = supabase.auth.onAuthStateChange(callback)

Apply error handling migration:

typescript
// BEFORE (v1 — string matching)
if (error.message.includes('not found')) { ... }

// AFTER (v2 — structured error codes)
if (error.code === 'PGRST116') { ... }  // "not found" → PGRST116
Step 3: Verify, Test, and Prepare Rollback
bash
# Type check (catches 90% of migration issues)
npx tsc --noEmit

# Run test suite
npm test

# Python tests
python -m pytest tests/ -v

# Manual smoke test critical auth flows:
# 1. Sign up → confirm email → sign in with password
# 2. OAuth sign in → callback handling
# 3. Password reset → email → reset form
# 4. Session refresh across page navigations
# 5. Realtime subscription connect/disconnect
# 6. Storage upload/download round-trip

Rollback procedure (if upgrade causes issues):

text
# Option A: Pin to previous version
npm install @supabase/supabase-js@<previous-version>
pip install supabase==<previous-version>

# Option B: Revert the branch
git stash && git checkout main

Output

  • @supabase/supabase-js upgraded to latest version with npm list confirmation
  • All supabase.auth.signIn() calls migrated to signInWithPassword / signInWithOAuth / signInWithOtp
  • Sync auth methods (session(), user()) replaced with async getSession() / getUser()
  • Realtime subscriptions migrated from .on() to channel-based API
  • data/error destructuring updated where return shapes changed
  • TypeScript types regenerated from current schema
  • Test suite passing, type checking clean
  • Rollback branch or version pin documented
Show full SKILL.md (191 more words)Show less

Error Handling

ErrorCauseSolution
Property 'session' does not existv1 sync .session() removed in v2Replace with await supabase.auth.getSession()
Property 'signIn' does not existsignIn split into multiple methods in v2Use signInWithPassword, signInWithOAuth, or signInWithOtp
supabase.auth.api is undefined.api namespace removed in v2Call methods directly on supabase.auth.*
TypeError: supabase.from(...).on is not a functionRealtime API replaced in v2Use supabase.channel().on('postgres_changes', ...)
Type errors after gen typesDatabase schema changed between versionsUpdate application code to match new generated types
PGRST116 error on .single()Zero rows returned (v2 throws)Use .maybeSingle() for optional lookups
ERR_REQUIRE_ESM after upgradev2 is ESM-only in some bundlersUpdate tsconfig.json to "module": "esnext" or use dynamic import()
AuthSessionMissingErrorgetSession() called before auth initializedWrap in onAuthStateChange listener or check session !== null

Examples

Full v1 → v2 auth migration (Next.js):

typescript
// lib/supabase.ts — client initialization (unchanged API)
import { createClient } from '@supabase/supabase-js'
import type { Database } from './database.types'

export const supabase = createClient<Database>(
  process.env.NEXT_PUBLIC_SUPABASE_URL!,
  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
)
typescript
// app/login/page.tsx — v2 auth flow
export async function login(email: string, password: string) {
  const { data, error } = await supabase.auth.signInWithPassword({
    email,
    password,
  })
  if (error) {
    // v2: use error.code instead of parsing error.message
    if (error.code === 'invalid_credentials') {
      return { success: false, message: 'Invalid email or password' }
    }
    throw error
  }
  return { success: true, session: data.session }
}
typescript
// hooks/useAuth.ts — v2 session listener
import { useEffect, useState } from 'react'
import { supabase } from '@/lib/supabase'
import type { Session } from '@supabase/supabase-js'

export function useAuth() {
  const [session, setSession] = useState<Session | null>(null)

  useEffect(() => {
    // v2: getSession is async, returns nested { data: { session } }
    supabase.auth.getSession().then(({ data: { session } }) => {
      setSession(session)
    })

    // v2: subscription nested one level deeper
    const { data: { subscription } } = supabase.auth.onAuthStateChange(
      (_event, session) => setSession(session)
    )

    return () => subscription.unsubscribe()
  }, [])

  return session
}

Python SDK upgrade:

python
# Before (supabase-py < 2.0)
from supabase import create_client
supabase = create_client(url, key)
data = supabase.table("users").select("*").execute()
users = data["data"]

# After (supabase-py >= 2.0)
from supabase import create_client, Client
supabase: Client = create_client(url, key)
response = supabase.table("users").select("*").execute()
users = response.data  # attribute access, not dict

Resources

Next Steps

For CI integration with the upgraded SDK, see supabase-ci-integration. For database migration workflows after schema changes, see supabase-migration-deep-dive.

© jeremylongshore, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 3 other files (references) in skills/.curated/supabase-upgrade-migration of jeremylongshore/tons-of-skills-marketplace.

  • SKILL.md
  • references/errors.md
  • references/examples.md
  • references/implementation.md

Open the folder on GitHubat commit cfae287

Compare with similar skills

Supabase Upgrade Migration next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Supabase Upgrade Migration compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Supabase Upgrade Migration this skilljeremylongshore/tons-of-skills-marketplace2.8k—~2.8kAutomated safety check: PassMIT
Frappe Agent MigratorImpertio-Studio/Frappe_Claude_Skill_Package189—~2.8kAutomated safety check: NotesMIT
jscpd Code Migration Trackerkucherenko/jscpd6.4k—~5kAutomated safety check: PassMIT
RustPython Stdlib UpgradeRustPython/RustPython22k—~876Automated safety check: PassMIT
Code Migrationanthropics/code-migration-kit-with-claude-code748—~983Automated safety check: PassCustom licence
Saleor Port Changessaleor/saleor23k—~969Automated safety check: PassBSD-3-Clause

Similar skills

  • Frappe Agent Migrator

    Impertio-Studio/Frappe_Claude_Skill_Package

    A skill your agent uses when migrating a Frappe app between major versions, detecting breaking API changes, or resolving post-migration errors.

    189 GitHub stars~2.8k tokensUpdated 24 days ago
    Data & AnalyticsAuto-check: notes
  • Measures a code port between languages or frameworks with jscpd's function-level comparison, porting tests before code and tracking what is left unmatched.

    6.4k GitHub stars~5k tokensUpdated yesterday
    DevelopmentAuto-check passed
  • RustPython Stdlib Upgrade

    RustPython/RustPython

    Upgrades a Python standard library module from CPython into RustPython with update_lib, then triages and marks the tests that still fail.

    22k GitHub stars~876 tokensUpdated today
    DevelopmentAuto-check passed
  • Code Migration

    anthropics/code-migration-kit-with-claude-code

    Official

    Run a large-scale language migration with the six-step process: create the map and the rules, stress-test the rules, translate everything, compile, run it, match behavior.

    748 GitHub stars~983 tokensUpdated 3 mo ago
    DevelopmentAuto-check passed
  • Saleor Port Changes

    saleor/saleor

    Forward-ports or backports a single PR or branch onto the currently checked-out Saleor branch, handling GraphQL version markers and migration numbering along the way.

    23k GitHub stars~969 tokensUpdated yesterday
    DevelopmentAuto-check passed
  • Ast Grep

    banteg/crimson

    Use ast-grep for Python structural code exploration, mechanical codemods, and rule maintenance in this repo.

    186 GitHub stars~541 tokensUpdated today
    DevelopmentAuto-check passed

More from jeremylongshore/tons-of-skills-marketplace

All 3,342 skills in this repo
  • Performing Security Code Review

    jeremylongshore/tons-of-skills-marketplace

    Execute this skill enables AI assistant to conduct a security-focused code review using the security-agent plugin.

    2.8k GitHub starsUsed in 2 repos~1.3k tokens
    Auto-check: notes
  • Adapting Transfer Learning Models

    jeremylongshore/tons-of-skills-marketplace

    Build this skill automates the adaptation of pre-trained machine learning models using transfer learning techniques.

    2.8k GitHub stars~1.1k tokensUpdated today
    Auto-check passed
  • Agent Context Loader

    jeremylongshore/tons-of-skills-marketplace

    Execute proactive auto-loading: automatically detects and loads agents.md files.

    2.8k GitHub stars~1.1k tokensUpdated today
    Auto-check passed
  • Aggregating Performance Metrics

    jeremylongshore/tons-of-skills-marketplace

    Aggregate and centralize performance metrics from applications, systems, databases, caches, and services.

    2.8k GitHub stars~1.2k tokensUpdated today
    Auto-check passed
  • Analyzing Capacity Planning

    jeremylongshore/tons-of-skills-marketplace

    Execute this skill enables AI assistant to analyze capacity requirements and plan for future growth.

    2.8k GitHub stars~947 tokensUpdated today
    Auto-check passed
  • Analyzing Database Indexes

    jeremylongshore/tons-of-skills-marketplace

    Process use when you need to work with database indexing. An agent skill from jeremylongshore/tons-of-skills-marketplace.

    2.8k GitHub stars~2k tokensUpdated today
    Auto-check passed

Works with

Categories

Questions about Supabase Upgrade Migration

What does Supabase Upgrade Migration do?

Upgrade Supabase SDK and CLI versions with breaking-change detection and automated code migration. Supabase Upgrade Migration is an agent skill from jeremylongshore/tons-of-skills-marketplace. Upgrade Supabase SDK and CLI versions with breaking-change detection and automated code migration.

When should I use Supabase Upgrade Migration?

Supabase Upgrade Migration fits situations like: upgrading @supabase/supabase-js (v1→v2; migrating auth/realtime/storage APIs; updating the Supabase CLI; with phrases like upgrade supabase.

How do I install Supabase Upgrade Migration in Claude Code?

Run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill supabase-upgrade-migration -a claude-code`. Or copy the skill folder (skills/.curated/supabase-upgrade-migration in jeremylongshore/tons-of-skills-marketplace) into .claude/skills/supabase-upgrade-migration in your project. Claude Code loads it when a task matches its description.

How do I install Supabase Upgrade Migration in Codex?

Run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill supabase-upgrade-migration -a codex`. Or copy the skill folder (skills/.curated/supabase-upgrade-migration in jeremylongshore/tons-of-skills-marketplace) into .agents/skills/supabase-upgrade-migration in your project. Codex loads it when a task matches its description.

Can I use Supabase Upgrade Migration in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add jeremylongshore/tons-of-skills-marketplace --skill supabase-upgrade-migration -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/supabase-upgrade-migration, .gemini/skills/supabase-upgrade-migration, .github/skills/supabase-upgrade-migration and .opencode/skills/supabase-upgrade-migration in your project.

What does Supabase Upgrade Migration need to run?

Going by SKILL.md and its folder, Supabase Upgrade Migration needs the command-line tools its instructions call (npm, pip, npx, supabase, git and python) and credentials named NEXT_PUBLIC_SUPABASE_ANON_KEY. Our summary lists: Python 3; Node.js; A credential in NEXT_PUBLIC_SUPABASE_ANON_KEY. Its frontmatter pre-approves these tools: Read, Write, Edit, Bash(npm:*), Bash(npx:*), Bash(pip:*), Bash(supabase:*), Bash(git:*), Grep, Glob. Compatibility (from SKILL.md): Designed for Claude Code.

Does Supabase Upgrade Migration access the network?

SKILL.md names 2 domains. As links in the text: github.com and supabase.com. This is read from the text; nothing was executed.

Is Supabase Upgrade Migration safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Supabase Upgrade Migration use?

Supabase Upgrade Migration is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Supabase Upgrade Migration use?

About 2.8k tokens (SKILL.md is roughly 11k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full. Its references folder adds about 562 tokens, read only when the agent opens those files.

What are the alternatives to Supabase Upgrade Migration?

Skills that share tags, products or a category with Supabase Upgrade Migration: Frappe Agent Migrator (Impertio-Studio/Frappe_Claude_Skill_Package, 189 stars), jscpd Code Migration Tracker (kucherenko/jscpd, 6.4k stars), RustPython Stdlib Upgrade (RustPython/RustPython, 22k stars) and Code Migration (anthropics/code-migration-kit-with-claude-code, 748 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Supabase Upgrade Migration?

jeremylongshore (a GitHub user) maintains it in jeremylongshore/tons-of-skills-marketplace, which has 2,827 GitHub stars. The repository holds 3,342 skills in this directory. The repository was last updated on October 10, 2026.

Source: jeremylongshore/tons-of-skills-marketplace on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.