EmDash는 컬렉션, 필드, 택소노미를 콘텐츠와 함께 데이터베이스에 저장합니다. 새 코드를 배포해도 해당 콘텐츠 모델은 변경되지 않지만, 새로운 EmDash 버전은 첫 번째 요청에서 EmDash가 관리하는 데이터베이스 테이블을 마이그레이션할 수 있습니다. 이 페이지에서는 이미 배포된 사이트의 콘텐츠 모델을 변경하는 방법을 설명하며, Cloudflare D1을 예시로 사용합니다. 동일한 워크플로우가 다른 데이터베이스 옵션에도 적용됩니다.
무엇이 무엇을 변경하는가
사이트는 네 가지 서로 다른 워크플로우를 거칩니다. 각각은 다른 레이어에 영향을 줍니다:
| 워크플로우 | 변경되는 것 | 방법 |
|---|---|---|
| 콘텐츠 편집 | 항목, 미디어, 설정 | 관리 패널 또는 콘텐츠 API |
| 코드 배포 | 템플릿, 설정, EmDash 버전 | wrangler deploy — EmDash 관리 테이블을 마이그레이션할 수 있음 |
| 최초 부트스트랩 | 모든 것 (빈 상태에서) | 마이그레이션 + 시드 파일 + 설정 마법사, 첫 부팅 시 자동 |
| 스키마 진화 | 컬렉션, 필드, 택소노미 | 관리 패널 또는 emdash schema를 운영 사이트에 대해 실행 (이 페이지) |
시드 파일은 세 번째 행에만 관여합니다. 데이터베이스가 비어 있고 설정 마법사가 완료되지 않은 경우 한 번만 적용됩니다. 기존 데이터베이스에 대해 변경된 시드 파일을 배포해도 아무것도 일어나지 않습니다 — 운영 사이트의 스키마 진화는 항상 관리 패널이나 API를 통해 이루어집니다.
관리 패널에서 스키마 변경
관리 패널은 배포된 사이트를 발전시키는 주요 방법입니다. 관리 화면에서 Content Types를 열고 컬렉션과 필드를 추가, 편집 또는 제거합니다. 변경 사항은 즉시 적용됩니다 — 콘텐츠 API, 로더, 편집 UI 모두 런타임에 데이터베이스에서 스키마를 읽습니다.
사용 가능한 필드 타입, 유효성 검사 규칙, 위젯 옵션에 대해서는 컬렉션과 필드를 참조하세요.
스키마를 변경한 후, 템플릿이 사용하는 TypeScript 타입을 재생성합니다. emdash types 명령은 실행 중인 인스턴스에서 스키마를 읽으므로, 배포된 사이트를 직접 가리킬 수 있습니다:
npx emdash types --url https://example.comCLI에서 스키마 변경
emdash schema 명령은 REST API를 통해 실행 중인 인스턴스와 통신하므로, 로컬 개발과 동일한 방식으로 배포된 사이트에 대해 작동합니다. 디바이스 플로우로 한 번 인증합니다:
npx emdash login --url https://example.com또는 관리 화면의 설정 → API 토큰에서 API 토큰을 생성하고 --token이나 EMDASH_TOKEN 환경 변수로 전달합니다 — CI에서 유용합니다.
그런 다음 로컬에서 사용하는 것과 동일한 명령으로 스키마를 발전시킵니다:
npx emdash schema add-field posts subtitle --type string --label "Subtitle" --url https://example.com
npx emdash schema remove-field posts legacy_field --url https://example.com
npx emdash schema create projects --label Projects --url https://example.com이 명령들은 단순한 CLI 호출이므로 스크립트화할 수 있습니다: 콘텐츠 모델에 대한 반복 가능한 “마이그레이션”은 emdash schema 호출의 셸 스크립트로, 리포지토리에 체크인하고 각 환경에 대해 순서대로 실행합니다.
전체 명령 목록은 CLI 레퍼런스를 참조하세요.
시드 파일 동기화 유지
빌드에 내장된 시드 파일은 새 데이터베이스가 무엇으로 초기화되는지를 결정합니다: 새로운 프리뷰 환경, 재해 복구 재구축 또는 동일한 사이트의 두 번째 배포. 시드가 여전히 스타터 블로그를 설명하는 반면 프로덕션이 다른 것으로 발전했다면, 모든 새 환경이 잘못된 모델로 부트스트랩됩니다.
빌드는 .emdash/seed.json, package.json#emdash.seed의 경로 또는 seed/seed.json에서 처음 발견된 시드 파일을 내장합니다. 없으면 내장 기본 시드(스타터 블로그 모델)가 내장되고, astro dev가 경고를 출력합니다.
배포된 사이트의 스키마를 발전시킨 후, 운영 모델을 리포지토리로 다시 내보냅니다. emdash export-seed는 로컬 SQLite 파일을 읽고, wrangler d1 export는 배포된 D1 데이터베이스에서 생성합니다:
npx wrangler d1 export emdash-db --remote --output=./prod.sql
sqlite3 prod.db < prod.sql
npx emdash export-seed --database prod.db > .emdash/seed.json내보낸 시드에는 운영 사이트의 설정, 컬렉션, 택소노미, 메뉴, 위젯 영역이 포함됩니다. --with-content를 추가하면 항목도 포함됩니다. 업데이트된 .emdash/seed.json을 새 스키마에 의존하는 코드와 함께 커밋하여, 새 환경이 항상 코드가 이해하는 모델로 부트스트랩되도록 합니다.
프리뷰 환경에서 변경 사항 리허설
파괴적인 스키마 변경(필드 제거, 컬렉션 재구성)은 프로덕션의 일회용 복사본에 대해 리허설하는 것이 가장 안전합니다.
-
wrangler.jsonc에 자체 D1 데이터베이스를 가진 프리뷰 환경을 추가합니다:{ "env": { "preview": { "d1_databases": [{ "binding": "DB", "database_name": "emdash-db-preview" }], }, }, } -
프로덕션을 복사합니다:
npx wrangler d1 export emdash-db --remote --output=./prod.sql npx wrangler d1 execute emdash-db-preview --remote --file=./prod.sql -
배포하고 프리뷰 URL에 대해 스키마 변경을 실행합니다:
npx wrangler deploy --env preview npx emdash schema remove-field posts legacy_field --url https://preview.example.com -
사이트가 렌더링되고 관리 화면이 예상대로 동작하는지 확인한 다음, 동일한 명령을 프로덕션에 대해 실행합니다.
실수에서 복구
- 필드를 실수로 삭제했습니다. 열과 그 데이터가 운영 데이터베이스에서 사라졌습니다. D1 Time Travel 시점 백업에서 복원하거나, 필드를 다시 추가하고 이전
wrangler d1 export에서 값을 복원합니다. - 새 환경이 잘못된 모델로 부트스트랩되었습니다. 내장된 시드가 오래되었거나 없었습니다.
.emdash/seed.json을 업데이트하고(시드 파일 동기화 유지 참조), 다시 빌드하고 빈 데이터베이스에 배포를 가리켜 다시 부트스트랩합니다. - 스키마와 템플릿이 일치하지 않습니다. 배포와 스키마 변경은 독립적이므로 의도적으로 순서를 정합니다: 추가적인 스키마 변경(새 컬렉션, 새 선택적 필드)을 먼저, 그 다음 이를 사용하는 코드. 제거의 경우, 필드 사용을 중단하는 코드를 먼저 배포한 다음 필드를 제거합니다.