데이터베이스와 마이그레이션

설치 및 설정

어떤 단계를 시작하기 전에 시작하기 전에 및 터미널 기본 사항을 읽어보세요. 이 지침에서는 VS Code에서 전체 supastack 단일 저장소를 열었다고 가정합니다. 해당 루트 package.json은 저장소 루트를 표시합니다. pnpm 명령에서 작업 영역 패키지는 앱 또는 공유 코드 폴더입니다. 제품에서 작업공간은 팀의 데이터 컨테이너이자 보안 경계입니다. corepack pnpm --filter ... 명령이 해당 루트에서 실행되는 동안 monorepo에서 하나의 패키지를 선택합니다. 동기화된 모바일 또는 데스크톱 폴더만 열었다면 웹 백엔드, Docker 설정 또는 루트 스크립트가 포함되지 않습니다. 이 모노 저장소 또는 연결 가능한 호스팅 서버에서 백엔드를 실행하고 플랫폼 폴더의 자체 스크립트를 사용하세요. 환경 변수는 로컬 .env 파일이나 호스팅 대시보드에 저장된 명명된 설정입니다. 관련 앱을 변경한 후 다시 시작하고, NEXT_PUBLIC_ 및 EXPO_PUBLIC_ 값에서 서버 비밀을 유지하세요.

1. Docker Desktop를 설치하고 시작합니다.

2. .env.example을 마이그레이션 도구의 루트에 있는 .env로 복사하고 Next.js의 경우 apps/web/.env.local로 복사합니다(PowerShell: Copy-Item .env.example .env; Copy-Item .env.example apps/web/.env.local. macOS/Linux/Git Bash: cp .env.example .env; cp .env.example apps/web/.env.local). 두 파일 모두에서 DATABASE_URL를 동일하게 유지하십시오. 예제는 이미 로컬 Docker 데이터베이스와 일치합니다.

3. 저장소 루트에서 docker compose up -d postgres 및 docker compose ps를 실행합니다. Postgres가 정상이라고 보고할 때까지 기다리십시오.

4. 루트에서 corepack pnpm --filter @supastack/db db:migrate를 실행하여 키트와 함께 이미 제공된 마이그레이션을 적용합니다. packages/db/src/schema.ts를 편집한 후에만 db:generate를 실행하고 생성된 SQL를 검사한 다음 db: migration을 실행합니다. 예상: 로컬 Postgres 컨테이너는 정상이며 웹 앱은 마이그레이션된 데이터베이스를 사용합니다. 이 첫 번째 실행을 프로덕션 단계로 지정하지 마세요.

서버 환경에서 대상 Postgres 데이터베이스용 DATABASE_URL을 구성하세요. 통합 수용에는 별도의 임시 데이터베이스를 사용하세요. 테스트 마이그레이션을 프로덕션 데이터베이스에 향하게 하지 마세요.

데이터베이스 워크스페이스는 스키마 정의와 영속화 헬퍼를보냅니다. 테이블이나 컬럼을 도입하기 전에 packages/db/src/schema.ts와 마이그레이션 디렉터리를 검토하세요.

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

# Only after changing packages/db/src/schema.ts:
corepack pnpm --filter @supastack/db db:generate
corepack pnpm --filter @supastack/db db:migrate

# Optional Compose / Supabase settings in .env:
# POSTGRES_PASSWORD=supastack
# SUPABASE_ACCESS_TOKEN=
# DATABASE_POOLER=transaction

복사 명령

설명을 따라 명령이 실행되는 폴더를 확인하세요. 두 개의 터미널에 레이블이 지정되어 있으면 두 개의 터미널 창을 열고 두 번째 명령을 사용하는 동안 첫 번째 명령을 계속 실행하세요.

# Choose one copy method for your terminal:
# PowerShell:
Copy-Item .env.example .env
Copy-Item .env.example apps/web/.env.local

# macOS/Linux/Git Bash alternative:
# cp .env.example .env
# cp .env.example apps/web/.env.local

docker compose up -d postgres
docker compose ps
corepack pnpm --filter @supastack/db db:migrate

구현 워크플로

스키마를 수정한 후 마이그레이션을 생성하고, 생성된 SQL을 검사하고, 스키마 변경과 함께 커밋하세요. 필수 컬럼을 추가하기 전에 기존 레코드가 값을 어떻게 받는지 계획하세요.

모든 사용자 소유 레코드에 workspaceId를 포함하고 그 경계를 읽기와 쓰기에 걸쳐 유지하세요. 기존 사용량 레코드가 참조하는 가격을 다시 쓰는 대신 AI 회계에는 불변의 모델 가격 이력을 사용하세요.

검증 및 문제 해결

Docker가 엔진에 연결할 수 없다고 말하면 Docker Desktop를 시작하고 로드가 완료될 때까지 기다립니다. postgres가 정상이 아닌 경우 루트에서 docker compose log postgres를 실행하고 마이그레이션하기 전에 해당 오류를 수정하세요. 웹에서 DATABASE_URL가 누락되었다고 표시되면 apps/web/.env.local를 확인하세요. db: migration이 연결할 수 없는 경우 루트 .env를 확인하세요. 데이터베이스를 변경하는 경우 두 파일을 모두 업데이트하세요. 재시도하기 전에 첫 번째 실패한 마이그레이션 설명을 읽어보세요. 생산에 대해 반복하지 마십시오.

격리된 데이터베이스에 마이그레이션을 적용하고 그 위에서 데이터베이스 게이트 테스트를 실행하세요. 누락된 자격 증명은 성공한 영속화 주장이 아니라 명시적으로 건너뛴 게이트를 만들어야 합니다. 마이그레이션이 실패하면 재시도 전에 어떤 문이 실패했는지와 현재 스키마를 검사하세요.