get-convex/convex-migration-helper

convex-migration-helper은(는) 무엇을 하나요?

Convex 스키마 및 데이터 마이그레이션을 widen-migrate-narrow 패턴과 @convex-dev/migrations 라이브러리를 사용하여 계획합니다. 주요 스키마 변경, 백필(backfill), 테이블 재구성, 제로 다운타임 롤아웃에 사용됩니다.

개요

이 스킬은 Convex 데이터베이스의 스키마 및 데이터 마이그레이션을 안전하게 계획하고 실행하는 방법을 제공합니다. widen-migrate-narrow 패턴을 사용하여 다운타임 없이 스키마를 변경하고, @convex-dev/migrations 라이브러리를 사용하여 백필 및 데이터 변환을 수행합니다.

지원 플랫폼

• Claude Code
• Cursor
• Codex

사용법

1. 현재 스키마(schema.ts)와 마이그레이션할 스키마 변경 사항을 분석합니다.
2. widen-migrate-narrow 패턴을 적용하여 마이그레이션 단계를 계획합니다.
3. @convex-dev/migrations 라이브러리를 사용하여 데이터 마이그레이션 스크립트를 작성합니다.
4. 마이그레이션을 안전하게 실행하고 롤백 계획을 수립합니다.

주요 기능

• 제로 다운타임 마이그레이션: widen-migrate-narrow 패턴을 사용하여 서비스 중단 없이 스키마 변경
• 데이터 백필: 기존 데이터를 새로운 스키마에 맞게 변환
• 테이블 재구성: 테이블 분할, 병합, 필드 추가/제거
• 롤백 계획: 마이그레이션 실패 시 안전하게 롤백할 수 있는 방법 제공

예시

import { Migrations } from "@convex-dev/migrations";
import { mutation } from "./_generated/server";

const migrations = new Migrations();

// widen 단계: 새 필드 추가 (선택 사항)
export const addNewField = mutation({
  handler: async (ctx) => {
    await migrations.migrate(ctx, {
      table: "users",
      batchSize: 100,
      migrate: async (doc) => {
        // 새 필드 추가
        return { ...doc, newField: "default" };
      },
    });
  },
});

// narrow 단계: 이전 필드 제거
export const removeOldField = mutation({
  handler: async (ctx) => {
    await migrations.migrate(ctx, {
      table: "users",
      batchSize: 100,
      migrate: async (doc) => {
        const { oldField, ...rest } = doc;
        return rest;
      },
    });
  },
});

참고 자료

• Convex 마이그레이션 문서
• @convex-dev/migrations
• widen-migrate-narrow 패턴