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이 명령들을 스크립트에 체크인하여 각 환경이 동일한 순서의 변경을 받을 수 있습니다. 명령은 자동으로 멱등하지 않습니다: 이미 존재하는 객체에 대해 create나 add-field를 다시 실행하면 실패할 수 있습니다. emdash schema list나 get으로 대상을 검사하고, 어떤 환경이 각 단계를 완료했는지 기록하고, 첫 번째 에러에서 멈추세요.
전체 명령 목록은 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을 새 스키마에 의존하는 코드와 함께 커밋하여, 새 환경이 항상 코드가 이해하는 모델로 부트스트랩되도록 합니다.
프리뷰 환경에서 변경 사항 리허설
파괴적인 스키마 변경(필드 제거, 컬렉션 재구조화)은 프로덕션의 일회용 복사본에 대해 리허설하는 것이 가장 안전합니다.
-
별도의 프리뷰 D1 데이터베이스를 생성하고 Wrangler가
preview환경에 추가하도록 합니다:npx wrangler d1 create emdash-db-preview \ --binding DB --env preview --update-configenv.preview.d1_databases에 새 데이터베이스 이름과 UUID가 포함되어 있는지 확인하세요. 바인딩은 최상위 Wrangler 구성에서 상속되지 않습니다. -
프로덕션을 내보낸 다음 프리뷰 환경의
DB바인딩을 통해 SQL을 가져옵니다:npx wrangler d1 export emdash-db --remote --output=./prod.sql npx wrangler d1 execute DB --env preview --remote --file=./prod.sql -
프로젝트를 빌드하고 프리뷰 환경에 배포한 다음 프리뷰 URL에 대해 스키마 변경을 실행합니다:
npm run build 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을 업데이트하고(시드 파일 동기화 유지 참조), 다시 빌드하고, 빈 데이터베이스에 대해 배포하여 다시 부트스트랩합니다. - 스키마와 템플릿이 일치하지 않음. 배포와 스키마 변경은 독립적이므로 의도적으로 순서를 정하세요: 추가적인 스키마 변경(새 컬렉션, 새 선택적 필드)을 먼저, 그다음 이를 사용하는 코드를. 제거의 경우, 먼저 필드 사용을 중단하는 코드를 배포하고, 그다음 필드를 제거하세요.