Claude-code-plugins-plus supabase-upgrade-migration

install

source · Clone the upstream repo

git clone https://github.com/jeremylongshore/claude-code-plugins-plus-skills

Claude Code · Install into ~/.claude/skills/

T=$(mktemp -d) && git clone --depth=1 https://github.com/jeremylongshore/claude-code-plugins-plus-skills "$T" && mkdir -p ~/.claude/skills && cp -r "$T/plugins/saas-packs/supabase-pack/skills/supabase-upgrade-migration" ~/.claude/skills/jeremylongshore-claude-code-plugins-plus-supabase-upgrade-migration && rm -rf "$T"

manifest: plugins/saas-packs/supabase-pack/skills/supabase-upgrade-migration/SKILL.md

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.

# 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 parsing	`error.code` enum ( `PGRST116` , etc.)	Reliable error matching
`.single()` returns error on 0 rows	`.maybeSingle()` for optional rows	New 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
```
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

Error Handling

Error	Cause	Solution
`Property 'session' does not exist`	v1 sync `.session()` removed in v2	Replace with `await supabase.auth.getSession()`
`Property 'signIn' does not exist`	`signIn` split into multiple methods in v2	Use `signInWithPassword` , `signInWithOAuth` , or `signInWithOtp`
`supabase.auth.api` is undefined	`.api` namespace removed in v2	Call methods directly on `supabase.auth.*`
`TypeError: supabase.from(...).on is not a function`	Realtime 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 upgrade	v2 is ESM-only in some bundlers	Update `tsconfig.json` to `"module": "esnext"` or use dynamic `import()`
`AuthSessionMissingError`	`getSession()` called before auth initialized	Wrap 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
}

Python SDK upgrade:

# 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

supabase-js v2 Migration Guide — official step-by-step
supabase-js Releases — changelog for every version
Supabase CLI Releases — CLI changelog
Auth Helpers Migration —
```
@supabase/auth-helpers
```
→
```
@supabase/ssr
```
Realtime v2 Guide — channel-based API reference
supabase-py Releases — Python SDK changelog

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