SKBE v1.0.1.1 업데이트: D1 복원 쿼리 청크 분할 및 멀티 슬롯 디자인 보존 안정화

1. 시작하며: v1.0.1.0 이후 발견된 엣지 케이스와 안정화 과제

지난 v1.0.1.0 업데이트를 통해 슬롯별 독립 프리셋 백업 시스템과 다국어(CJK) 레이아웃 최적화를 완료한 이후, 실제 환경에서 대용량 데이터를 다루고 복합적인 슬롯 디자인을 전환하는 과정에서 몇 가지 중요한 기술적 엣지 케이스들이 발견되었습니다.

특히 Cloudflare Serverless 환경 특유의 인프라 제약 조건과, 여러 개의 디자인 슬롯을 오가는 복원 파이프라인에서 데이터 무결성을 유지하는 것이 핵심 과제로 대두되었습니다.

이번 SKBE v1.0.1.1 업데이트에서는 데이터의 규모와 사용자의 작업 순서에 상관없이 블로그 엔진이 100% 견고하게 동작하도록 데이터베이스 복원 파이프라인과 디자인 동기화 엔진을 전면 안정화했습니다:

1. Cloudflare D1 단일 배치 문장 한계(128개) 극복: 게시글과 댓글이 누적된 상태에서 복원 시 발생할 수 있는 D1 크래시를 원천 방어하는 50개 단위 청크(Chunk) 순차 실행 엔진 구축
2. 디자인 백업 복원 시 멀티 슬롯(design_slots) 보존: 전체 디자인 복원 과정에서 기존에 공들여 작업해 둔 멀티 슬롯 데이터가 유실되지 않도록 엄격한 테이블 보존 로직 적용
3. 디자인 에디터 마운트 시 활성 슬롯 스냅샷 즉각 동기화: 슬롯을 전환하거나 에디터에 새로 진입할 때 메모리 상의 스냅샷 불일치로 인해 발생할 수 있는 슬롯 오염 방지
4. 위젯 고유 ID 및 네비게이션 복원 무결성 확보: 슬롯 복원 과정에서 위젯 고유 식별자(widget_id) 손실을 방지하고, 네비게이션 데이터 누락 시 안전 폴백 구축
5. 활성 슬롯 기준 디자인 공유 내보내기: 디자인 공유 및 내보내기 시 레거시 단일 테이블이 아닌 현재 활성화된 슬롯의 최신 디자인을 정확히 추출하도록 개편

---

2. Cloudflare D1 아키텍처: 단일 배치 128문장 한계와 50개 청크 분할 엔진

1) 잠재적 크래시의 원인: db.batch()의 물리적 제약

Cloudflare D1은 분산 SQLite 기반 데이터베이스로 뛰어난 읽기 성능과 글로벌 엣지 복제를 제공하지만, 단일 db.batch() 트랜잭션 호출 시 포함할 수 있는 SQL 문(Statement)의 개수를 최대 128개로 엄격히 제한하고 있습니다.

기존의 복원 엔진(/api/restore)은 백업 파일에서 추출한 모든 DELETE 문과 수백 개의 INSERT 문을 단일 배열로 결합하여 한 번의 batch()로 전송했습니다:

// [기존 코드의 잠재적 위험]
// 데이터가 많아질 경우 단일 배열이 128개를 초과하여 크래시 발생
await BLOG_DB.batch([...blogDeleteStatements, ...blogInsertStatements]);

블로그 포스트가 80개, 댓글 및 엔트리가 50개를 넘어가는 순간 총 문장 수가 130개를 초과하게 되며, 이 경우 D1은 즉각 D1_ERROR: Batch size too large 에러를 반환하고 복원 작업을 중단시키는 심각한 결함이 발생할 수 있었습니다.

2) 해결책: 50개 청크 분할 및 단계별 순차 실행 (executeInChunks)

이를 완벽히 해결하기 위해, D1 배치 호출부를 50개 단위 청크(Chunk)로 안전하게 분할하여 순차 실행하는 유틸리티 엔진을 설계하고 적용했습니다:

// --- Safe chunk execution utility ---
const executeInChunks = async (db: any, statements: any[], chunkSize = 50) => {
    for (let i = 0; i < statements.length; i += chunkSize) {
        const chunk = statements.slice(i, i + chunkSize);
        if (chunk.length > 0) {
            await db.batch(chunk);
        }
    }
};

// 1. BLOG_DB: Deletes가 완전히 완료된 후 Inserts 순차 실행
if (blogDeleteStatements.length > 0) {
    await executeInChunks(BLOG_DB, blogDeleteStatements);
}
if (blogInsertStatements.length > 0) {
    await executeInChunks(BLOG_DB, blogInsertStatements);
}

// 2. USER_DB: 동일한 방식으로 Deletes 후 Inserts 실행
if (userDeleteStatements.length > 0) {
    await executeInChunks(USER_DB, userDeleteStatements);
}
if (userInsertStatements.length > 0) {
    await executeInChunks(USER_DB, userInsertStatements);
}

청크 분할 엔진의 핵심 강점

• 데이터 무제한 확장성: 백업 파일에 게시글이 수천 개 이상 누적되어도 50개 단위로 자동 분할 실행되므로 D1의 128개 제한에 절대 걸리지 않습니다.
• 외래 키(FK) 제약 조건의 완벽한 안전성: 기존 데이터를 정리하는 DELETE 묶음이 데이터베이스에 100% 완결 반영된 이후에 비로소 새 데이터를 주입하는 INSERT 묶음이 실행되므로, 외래 키 충돌이나 데이터 꼬임이 원천 방지됩니다.
• 무중단 사용자 경험: 분할 처리는 서버리스 백엔드 내부에서만 비동기로 완결되므로, 프론트엔드 관리자 화면의 안내 문구나 다국어 알림 UI는 기존과 동일하게 매끄럽게 동작합니다.

---

3. 디자인 백업 및 복원 안정화: 멀티 슬롯(design_slots) 보존

SKBE는 최대 3개 이상의 독자적인 테마와 레이아웃을 저장하고 실시간으로 교체할 수 있는 멀티 디자인 슬롯 시스템을 갖추고 있습니다.

과거 레거시 전체 디자인 복원을 수행할 때, 복원 대상 테이블 목록에 design_slots가 부주의하게 포함될 경우 사용자가 정성껏 구성해 둔 다른 슬롯의 디자인 데이터까지 통째로 비워지는 부작용이 발생할 위험이 있었습니다.

이번 v1.0.1.1에서는 복원 로직을 정밀하게 점검하여, 디자인 백업 복원 시 기존 멀티 슬롯 테이블(design_slots)의 독립적인 슬롯 스냅샷들을 철저히 보호하고 보존하도록 필터링을 강화했습니다. 이를 통해 사용자는 안심하고 디자인 백업 파일을 불러올 수 있습니다.

---

4. 디자인 에디터 동기화: 슬롯 스냅샷 및 위젯 안전장치

1) 에디터 마운트 시 활성 슬롯 스냅샷 동기화

디자인 에디터(design-editor/+page.svelte)를 로드할 때, 브라우저 메모리에 캐시된 상태와 데이터베이스에서 불러온 활성 슬롯의 스냅샷 간에 미세한 시차가 발생할 수 있었습니다.

이로 인해 1번 슬롯을 편집하려 진입했음에도 이전에 열려 있던 2번 슬롯의 메모리 잔재가 섞여 디자인이 오염되는 현상을 차단하기 위해, 컴포넌트 마운트(onMount) 즉시 활성 슬롯의 원본 스냅샷을 강제 동기화하도록 파이프라인을 보강했습니다.

2) 위젯 고유 ID 유실 방지 및 네비게이션 폴백

슬롯 복원 및 교체 과정에서 복잡한 위젯 트리 내부의 고유 식별자(widget_id)가 누락되어 일부 위젯 스타일이 기본값으로 풀리는 현상을 방지하도록 정규화 로직을 보강했습니다. 또한 헤더/푸터 네비게이션 메뉴 데이터가 비어 있는 경우에도 사이트가 깨지지 않도록 안전한 기본 폴백을 적용했습니다.

3) 활성 슬롯 기준 디자인 공유 내보내기

다른 블로그나 사용자에게 내 디자인을 공유하는 '디자인 공유 내보내기(/api/share-design)' 기능 역시, 과거의 레거시 단일 테이블(blog_settings)을 읽던 방식을 탈피하여 현재 활성화되어 있는 슬롯의 최신 디자인 데이터를 정확하게 추출해 내보내도록 개편되었습니다.

---

5. 마치며: 프로덕션 레벨의 블로그 엔진을 향해

이번 SKBE v1.0.1.1 업데이트는 화려한 외형적 기능 추가보다는, **"어떠한 데이터 환경과 작업 시퀀스에서도 데이터가 유실되지 않고 안전하게 보존되는가?"**에 집중한 인프라 안정화 릴리즈입니다.

Cloudflare Serverless의 엄격한 제약을 우아하게 극복하고, 멀티 슬롯 디자인 시스템의 무결성을 완성함으로써 SKBE는 더욱 신뢰할 수 있는 독립형 블로그 엔진으로 발전했습니다.

SKBE 프로젝트는 앞으로도 실제 운영에서 검증된 기술적 경험과 안전한 아키텍처를 투명하게 공유해 나가겠습니다.