Skip to main content
supabase-upgrade-migration 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".
npx skills add jeremylongshore/claude-code-plugins-plus-skills --skill supabase-upgrade-migration ai automation claude-code devops mcp ai-agents
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 projectGit 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.
# 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 Pattern v2 Replacement Notes 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:
// 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.
# 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:
// 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:
// 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 # 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):
# 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 confirmationAll 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 changedTypeScript types regenerated from current schema
Test suite passing, type checking clean
Rollback branch or version pin documented
Error Handling Error Cause Solution Property 'session' does not existv1 sync .session() removed in v2 Replace 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 v2 Use supabase.channel().on('postgres_changes', ...) Type errors after gen types Database schema changed between versions Update 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 bundlers Update 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):
// 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!
)
// 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 }
}
// 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
}
# 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.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
