CMS SEO 백필 스크립트를 안전한 마이그레이션으로 만드는 법

CMS의 사이트 메타정보 중 SEO 필드가 누락되어 있어서, 이를 한 번에 채워주는 백필 스크립트를 작성했다. 언뜻 간단해 보이는 작업이지만, 1회성 데이터 마이그레이션이라는 특성 때문에 설계 단계부터 신경 써야 할 게 많았다.

왜 백필이 필요했나

보통 CMS 시스템이 초기 구축될 때, 모든 필드를 다 채우지 못하는 경우가 있다. SEO 메타데이터 같은 경우, 초반에는 필수 기능으로 보지 않다가 나중에 검색 엔진 노출이 중요해지면서 필요성이 대두된다. 우리도 그런 상황이었다.

이미 CMS에 등록된 수백 개의 사이트들에 대해 SEO 메타 정보가 비어있었고, 새로운 사이트를 등록할 때는 자동으로 기본값이 생성되도록 코드를 수정했다. 하지만 기존 데이터는 그대로 두면 검색 엔진에 노출이 제대로 되지 않을 테니, 과거 데이터를 일괄 채워야 했다.

1회성 스크립트, 어떻게 다루나

1회성 스크립트라는 게 중요한 포인트다. 보통 "이건 한 번만 실행하고 버릴 거니까 대충 해도 되겠지" 하는 생각이 들 수 있지만, 오히려 더 신경 써야 한다. 왜냐하면:

• 프로덕션 데이터를 건드리는 유일한 기회: 실수하면 돌이킬 수 없을 수도 있다
• 재실행 가능성: "다시 한 번만 돌려야 하는데…" 하는 상황이 생길 수 있다
• 감시자 역할: 나중에 같은 상황이 반복되지 않는지 모니터링 근거가 된다

그래서 스크립트를 작성할 때 다음을 고려했다:

스크립트 설계의 핵심

기본 구조는 이런 식으로 잡았다:

# 1. 대상 데이터 조회 (where meta.seo is null/empty)
# 2. 각 데이터에 대해 기본 SEO 값 생성 (title, description, keywords)
# 3. dry-run 플래그로 영향 범위 파악
# 4. 실제 수정 전 스냅샷 저장
# 5. 수정 실행 및 결과 기록
# 6. 수정 건수/소요 시간 리포팅

특히 중요한 부분:
- 조건부 실행: 스크립트 파라미터로 --dry-run, --batch-size, --limit 같은 옵션을 넣어서 상황에 맞게 조절 가능하게 함
- 멱등성 보장: 이미 SEO 값이 있는 건 건너뛰도록
- 에러 처리: 개별 레코드 실패가 전체 작업을 막지 않도록, 실패 건을 별도로 기록

팀과의 커뮤니케이션

이 정도 규모의 작업이면, 혼자 조용히 끝내는 것보다는 팀에 진행 과정을 공유하는 게 맞다고 생각했다.

1. 사전 공지: 언제쯤, 어떤 데이터를 수정할 건지 미리 알림
2. 드라이런 결과 공유: "총 500개 레코드가 영향받을 예정" 같은 수치를 명확히
3. 롤백 계획 제시: 문제 시 DB 스냅샷에서 복구 가능함을 보장
4. 실행 후 결과 보고: 실제 수정 건수, 소요 시간, 발생한 이슈

회고하며 든 생각

비슷한 백필 작업을 여러 번 겪으면서 느낀 건데, 1회성 스크립트는 완성도가 높을수록 비용이 낮다는 거다. 처음엔 "어차피 한 번인데" 하고 대충 만들면, 나중에 재실행할 일이 생겼을 때 다시 손봐야 하거나, 팀원이 신뢰 없이 접근하게 된다.

특히 프로덕션 데이터를 건드리는 작업이면, 다음 체크리스트를 항상 챙기자:
- ✓ 드라이런 모드로 영향 범위 확인
- ✓ 에러 시 부분 롤백 방법 마련
- ✓ 스크립트 실행 결과 로그 남기기
- ✓ 팀과 사전/사후 커뮤니케이션

이런 식으로 "단순한 데이터 백필"을 "신뢰할 수 있는 마이그레이션 프로세스"로 만들 수 있다. 스크립트 파일을 코드베이스에 남겨두는 것도, 나중에 같은 패턴의 작업이 반복될 때 좋은 레퍼런스가 되고, 감사(audit) 목적으로도 도움이 된다.

🛒 이 글과 어울리는 추천 상품

• 기계식키보드 쿠팡에서 보기 →
• 사무의자 쿠팡에서 보기 →
• 외장SSD 쿠팡에서 보기 →

*위 링크는 쿠팡파트너스 활동의 일환이며, 일정액의 수수료를 제공받을 수 있습니다.