배포된 사이트의 스키마 진화시키기

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.com

CLI에서 스키마 변경

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 파일을 읽습니다. 오프사이트 D1 덤프 만들기에 설명된 대로 SQL 파일을 만들고, 테이블과 행을 로컬 데이터베이스에 불러온 다음 시드를 내보내세요.

sqlite3 prod.db < backup-schema.sql
sqlite3 prod.db < backup-folders.sql
sqlite3 prod.db < backup-data.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-config
```
env.preview.d1_databases에 새 데이터베이스 이름과 UUID가 들어 있는지 확인하세요. 바인딩은 최상위 Wrangler 설정에서 상속되지 않습니다.

오프사이트 D1 덤프 만들기에 설명된 대로 프로덕션에서 SQL 파일을 만든 다음, 프리뷰 환경의 DB 바인딩을 통해 순서대로 가져옵니다.

npx wrangler d1 execute DB --env preview --remote --file=./backup-schema.sql
npx wrangler d1 execute DB --env preview --remote --file=./backup-folders.sql
npx wrangler d1 execute DB --env preview --remote --file=./backup-data.sql
npx wrangler d1 execute DB --env preview --remote --file=./backup-indexes.sql

프리뷰 사이트는 해당 섹션에 설명된 대로 검색 API가 처음 호출될 때 검색 인덱스를 다시 구축합니다.

프로젝트를 빌드하고 프리뷰 환경에 배포한 다음, 프리뷰 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 시점 백업에서 복원하거나, 필드를 다시 추가하고 이전의 오프사이트 D1 덤프에서 값을 복원하세요.
새 환경이 잘못된 모델로 부트스트랩되었습니다. 포함된 시드가 오래되었거나 없었습니다. .emdash/seed.json을 업데이트하고(시드 파일 동기화 유지 참고), 다시 빌드한 다음, 비어 있는 데이터베이스를 가리키도록 배포하여 다시 부트스트랩하세요.
스키마와 템플릿이 일치하지 않습니다. 배포와 스키마 변경은 서로 독립적이므로 의도적으로 순서를 정하세요. 추가적인 스키마 변경(새 컬렉션, 새 선택 필드)을 먼저 하고, 그것을 사용하는 코드를 그다음에 배포합니다. 제거의 경우, 해당 필드를 더 이상 사용하지 않는 코드를 먼저 배포한 다음 필드를 제거하세요.