Next.js Supabase 데이터베이스 스키마 불일치 오류 완벽 해결 가이드 2025

Next.js 애플리케이션을 개발하면서 Supabase와 연동할 때 가장 자주 마주치는 문제 중 하나가 데이터베이스 스키마 불일치 오류입니다. 특히 "column does not exist" 에러는 개발자들을 좌절시키는 대표적인 문제입니다.

이 글에서는 실제 프로덕션 환경에서 발생한 사례를 바탕으로 체계적인 트러블슈팅 방법론을 제시하겠습니다.

🚨 실제 발생한 오류 사례

다음과 같은 오류가 Next.js 애플리케이션에서 발생했습니다:

Error fetching Notion connection: {
  code: '42703',
  details: null,
  hint: null,
  message: 'column notion_connections.user_id does not exist'
}

Connection error: {
  code: 'PGRST204',
  details: null,
  hint: null,
  message: "Could not find the 'user_id' column of 'notion_connections' in the schema cache"
}

🔍 체계적 트러블슈팅 방법론

1단계: 문제 분석과 우선순위 설정

효과적인 트러블슈팅을 위해 먼저 작업을 체계적으로 계획하세요:

1. 현재 테이블 구조 확인 (높은 우선순위)
2. 관련 테이블 스키마 분석 (높은 우선순위)
3. 데이터베이스 쿼리 수정 (높은 우선순위)
4. 수정사항 테스트 (중간 우선순위)

💡 트러블슈팅 팁: 복잡한 문제일수록 작업을 단계별로 나누고 우선순위를 정하세요. 이렇게 하면 놓치는 부분 없이 체계적으로 해결할 수 있습니다.

2단계: 실제 데이터베이스 스키마 확인

에러 메시지만 보고 추측하지 말고, 실제 데이터베이스 상태를 직접 확인하는 것이 중요합니다.

Supabase SQL Editor에서 확인:

-- 테이블 구조 확인
SELECT column_name, data_type, is_nullable
FROM information_schema.columns
WHERE table_name = 'notion_connections';

발견한 실제 상황:

• ❌ notion_connections 테이블에 user_id 컬럼이 없음
• ✅ 대신 provider_user_id 컬럼이 존재 (varchar 타입)
• ✅ users 테이블에는 id (integer)와 provider_user_id (varchar) 두 컬럼 모두 존재

💡 중요한 교훈: 에러 메시지를 맹신하지 마세요. 실제 데이터베이스 상태를 직접 확인하는 것이 가장 정확합니다.

3단계: 문제 코드 위치 추적

에러 로그에서 문제가 되는 API 엔드포인트를 확인:

• GET /api/notion/connection 500
• POST /api/notion/connect-page 500

관련 파일들을 체계적으로 검색하여 문제 코드를 찾아냅니다.

🛠️ Next.js API 라우트 수정 방법

문제 1: /api/notion/connection/route.ts

❌ 문제가 된 코드:

const { data: connection, error: connectionError } = await supabase
  .from('notion_connections')
  .select(`
    user_id,  // 존재하지 않는 컬럼
    workspace_id,
    // ...
  `)
  .eq('user_id', user.id)  // 존재하지 않는 컬럼으로 필터링
  .single()

✅ 수정된 코드:

const { data: connection, error: connectionError } = await supabase
  .from('notion_connections')
  .select(`
    id,
    provider_user_id,  // 실제 존재하는 컬럼
    workspace_id,
    // ...
  `)
  .eq('provider_user_id', userId)  // Clerk userId 직접 사용
  .single()

문제 2: /api/notion/connect-page/route.ts

❌ 문제가 된 코드:

const connectionData = {
  user_id: user.id,  // 존재하지 않는 컬럼
  // ...
}

await supabase
  .from('notion_connections')
  .upsert(connectionData, {
    onConflict: 'user_id',  // 존재하지 않는 컬럼
  })

✅ 수정된 코드:

const connectionData = {
  provider_user_id: userId,  // 실제 존재하는 컬럼
  // ...
}

await supabase
  .from('notion_connections')
  .upsert(connectionData, {
    onConflict: 'provider_user_id',  // 올바른 유니크 제약조건
  })

⚡ 성능 최적화 팁

문제 해결과 동시에 코드를 더 효율적으로 개선할 수 있습니다:

Before (비효율적):

// 불필요한 users 테이블 조회
const { data: user, error: userError } = await supabase
  .from('users')
  .select('id')
  .eq('provider_user_id', userId)
  .single()

// 그 후 notion_connections 조회
.eq('user_id', user.id)

After (효율적):

// Clerk userId를 직접 사용
.eq('provider_user_id', userId)

🔧 Supabase PostgreSQL 스키마 관리 모범 사례

1. 스키마 문서화

• 모든 테이블과 컬럼을 명확히 문서화
• 관계도(ERD) 작성 및 유지보수
• 컬럼명 명명 규칙 통일

2. 마이그레이션 관리

• 스키마 변경 시 마이그레이션 스크립트 작성
• 롤백 계획 수립
• 개발/스테이징/프로덕션 환경 동기화

3. 타입 안전성 확보

• Supabase TypeScript 타입 생성 활용
• 컴파일 타임 에러 방지
• IDE 자동완성 지원

📈 효과적인 트러블슈팅을 위한 핵심 원칙

1. 가정하지 말고 확인하라

• 에러 메시지만으로 추측하지 말고 실제 데이터베이스 스키마를 확인
• 코드에서 사용하는 컬럼명과 실제 테이블 구조를 대조

2. 체계적으로 접근하라

• 문제를 단계별로 나누어 해결
• 체크리스트를 활용해 놓치는 부분 방지

3. 도구를 적극 활용하라

• Supabase SQL Editor: 실제 스키마 확인
• 브라우저 개발자 도구: 네트워크 요청 분석
• Next.js 개발 서버 로그: 상세한 에러 정보 확인

4. 전체적인 일관성 확인

• 한 곳을 수정하면 연관된 모든 부분 함께 확인
• SELECT, INSERT, UPDATE, DELETE 쿼리 모두 일관성 유지
• 유니크 제약조건과 인덱스 설정 확인

🚀 예방을 위한 개발 환경 설정

TypeScript 타입 생성

# Supabase 타입 생성
npx supabase gen types typescript --project-id YOUR_PROJECT_ID --schema public > types/supabase.ts

환경별 스키마 동기화

# 로컬 개발 환경 초기화
npx supabase init
npx supabase start
npx supabase db reset

📋 체크리스트: 스키마 오류 방지

• ☑️ 실제 데이터베이스 스키마와 코드 일치 확인
• ☑️ TypeScript 타입 정의 최신 상태 유지
• ☑️ API 라우트에서 사용하는 모든 컬럼명 검증
• ☑️ 유니크 제약조건과 upsert 설정 일치 확인
• ☑️ 개발/프로덕션 환경 스키마 동기화
• ☑️ 마이그레이션 스크립트 작성 및 테스트

🎯 결론

Next.js와 Supabase를 사용한 웹 애플리케이션 개발에서 데이터베이스 스키마 불일치 오류는 충분히 예방하고 해결할 수 있는 문제입니다.

핵심은 실제 상황을 정확히 파악하는 것입니다. 에러 메시지에 현혹되지 않고 실제 데이터베이스 스키마를 확인함으로써 근본적인 원인을 찾을 수 있습니다.

복잡한 문제일수록 체계적인 접근이 중요합니다. 문제를 단계별로 나누고, 적절한 도구를 활용하며, 전체적인 일관성을 유지하면서 해결해 나가는 것이 효과적인 트러블슈팅의 핵심입니다.

기억하세요: 좋은 개발자와 뛰어난 개발자의 차이는 문제를 해결하는 능력이 아니라, 문제를 체계적으로 분석하고 근본 원인을 찾아내는 능력에 있습니다.

🏷️ 태그: #NextJS #Supabase #PostgreSQL #데이터베이스오류 #스키마불일치 #트러블슈팅 #웹개발 #API라우트