EmDash는 컬렉션, 필드, 택소노미를 콘텐츠와 함께 데이터베이스에 저장합니다. 새 코드를 배포해도 이것들은 변경되지 않습니다: 배포는 Worker(또는 서버) 코드를 교체하지만, 데이터베이스의 스키마와 콘텐츠는 그대로 유지됩니다. 이 페이지는 이미 배포된 사이트의 콘텐츠 모델을 변경하는 방법을 Cloudflare D1을 예로 들어 설명합니다. 동일한 워크플로우가 다른 데이터베이스 옵션에도 적용됩니다.
무엇이 무엇을 변경하는가
사이트는 네 가지 별개의 워크플로우를 거칩니다. 각각 다른 레이어에 영향을 줍니다:
| 워크플로우 | 변경되는 것 | 방법 |
|---|---|---|
| 콘텐츠 편집 | 항목, 미디어, 설정 | 관리 패널 또는 콘텐츠 API |
| 코드 배포 | 템플릿, 설정, EmDash 버전 | wrangler deploy — 스키마와 콘텐츠는 그대로 |
| 최초 부트스트랩 | 모든 것 (빈 상태에서) | 마이그레이션 + seed 파일 + 설정 마법사, 첫 부팅 시 자동 |
| 스키마 진화 | 컬렉션, 필드, 택소노미 | 관리 패널 또는 emdash schema를 라이브 사이트에 대해 실행 (이 페이지) |
seed 파일은 세 번째 행에만 참여합니다. 데이터베이스가 비어 있고 설정 마법사가 완료되지 않은 경우 한 번만 적용됩니다. 기존 데이터베이스에 대해 변경된 seed 파일을 배포해도 아무것도 하지 않습니다 — 라이브 사이트의 스키마 진화는 항상 관리 패널이나 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또는 관리자의 Settings → API Tokens에서 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 레퍼런스를 참조하세요.
seed 파일 동기화 유지
빌드에 포함된 seed 파일은 새로운 데이터베이스가 무엇으로 초기화되는지 결정합니다: 새 프리뷰 환경, 재해 복구 재구축, 또는 같은 사이트의 두 번째 배포. 프로덕션이 다른 것으로 진화했는데 seed가 여전히 스타터 블로그를 설명하고 있다면, 모든 새 환경은 잘못된 모델로 부트스트랩됩니다.
빌드는 .emdash/seed.json, package.json#emdash.seed의 경로, 또는 seed/seed.json에서 처음 발견된 seed 파일을 포함합니다. 존재하지 않으면 내장 기본 seed(스타터 블로그 모델)가 포함되고, 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내보낸 seed에는 라이브 사이트의 설정, 컬렉션, 택소노미, 메뉴, 위젯 영역이 포함됩니다. 항목을 포함하려면 --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에서 값을 복원합니다. - 새 환경이 잘못된 모델로 부트스트랩되었습니다. 포함된 seed가 오래되었거나 누락되었습니다.
.emdash/seed.json을 업데이트하고(seed 파일 동기화 유지 참조), 다시 빌드하고 빈 데이터베이스에 배포를 지정하여 다시 부트스트랩합니다. - 스키마와 템플릿이 일치하지 않습니다. 배포와 스키마 변경은 독립적이므로 의도적으로 순서를 정합니다: 추가적인 스키마 변경(새 컬렉션, 새 선택적 필드)을 먼저 한 다음, 그것을 사용하는 코드를 배포합니다. 제거의 경우, 필드 사용을 중단하는 코드를 먼저 배포한 다음 필드를 제거합니다.