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또는 관리자의 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이 명령들을 스크립트로 만들어 커밋해 두면 모든 환경이 같은 순서의 변경을 받을 수 있습니다. 명령은 자동으로 멱등하지 않습니다. 이미 존재하는 객체에 대해 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을 업데이트하고(시드 파일 동기화 유지 참고), 다시 빌드한 다음, 배포가 빈 데이터베이스를 가리키게 하여 다시 부트스트랩하세요. - 스키마와 템플릿이 일치하지 않습니다. 배포와 스키마 변경은 서로 독립적이므로 순서를 의도적으로 정하세요. 추가형 스키마 변경(새 컬렉션, 새 선택 필드)을 먼저 하고, 그다음에 그것을 사용하는 코드를 배포합니다. 삭제의 경우에는 먼저 해당 필드를 더 이상 사용하지 않는 코드를 배포한 다음 필드를 삭제하세요.