Builderlog ·빌더로그 편집팀 ·플레이북 ·빌더로그 필드 매뉴얼 207 ·2026.09.14 ·9 분 읽기

Cloudflare D1 백업과 복구: 손대기 전에 북마크와 보존 기간부터 확인하기

#cloudflare d1#백업#복구#북마크#time travel

Cloudflare D1 백업과 복구를 앞두고 가장 먼저 할 결정은, 작은 사례 하나를 사람이 직접 검토할 수 있는가예요. Cloudflare D1의 Time Travel은 Free 플랜에서 7일, Paid 플랜에서 30일의 보존 기간을 제공하고요, 복구를 실행하면 진행 중인 모든 쿼리가 취소되기 때문에, 복구 버튼을 누르기 전에 작성하는 의사결정표가 복구 자체보다 더 중요해요.

검토일: 2026-09-09 (Cloudflare 공식 참조 페이지 기준) / 조건: 실제 프로덕션 D1 데이터베이스에서 복구를 실행한 경험은 없으며, 이 글은 메커니즘 문서화와 의사결정표 제공에 한정돼요.

세 줄 요약을 먼저 드릴게요. Time Travel은 백업이 아니라 D1에 내장된 시점 복구(point-in-time rewind) 기능이에요. 복구를 실행하면 현재 데이터베이스 상태가 교체되고, 복구가 반환하는 북마크로 되돌릴 수 있어요. 보존 기간이 얼마나 과거로 갈 수 있는지를 결정하는데, 7일 또는 30일뿐이고 그 이상도 이하도 아니에요. 이 기간을 넘어서는 무언가가 필요하거나, 라이브 데이터베이스와 독립적으로 존재하는 복사본이 필요하다면 Time Travel은 맞는 도구가 아니에요.

저는 실제 프로덕션 D1 데이터베이스에서 복구를 실행해본 적이 없어요. 이 글은 Cloudflare의 공식 참조 페이지(검토일 2026-09-09)를 바탕으로 메커니즘을 문서화하고, 손대기 전에 채워야 할 의사결정표를 제공해요. 북마크를 확인하지 않고 그냥 프로덕션에서 시도해보라고 조언하는 사람이 있다면, 비용이 전혀 들지 않는 단계를 건너뛰고 있는 거예요.

직접 실행 기록

실행 명령: npx --yes wrangler d1 time-travel info builderlog-mailbox
환경: Darwin 25.5.0 / python 3.14.7
실행 시각: 2026-09-12T00:31:01+09:00
종료 코드: 0

⛅️ wrangler 4.129.0 (update available 4.131.1)
───────────────────────────────────────────────
Resource location: remote 

🚧 Time Traveling...
⚠️ The current bookmark is '00000150-00000000-000050e3-e07c569c42b5f42f6ca338dc20e6e6d3'
⚡️ To restore to this specific bookmark, run:
 `wrangler d1 time-travel restore builderlog-mailbox --bookmark=00000150-00000000-000050e3-e07c569c42b5f42f6ca338dc20e6e6d3`

아래는 위 환경에서 실제로 실행한 결과를 그대로 붙인 것이다. 다른 환경에서는 다르게 나올 수 있다.

검증된 실행

명령어: npx --yes wrangler d1 time-travel info builderlog-mailbox 환경: Darwin 25.5.0 / python 3.14.7 실행 시각: 2026-09-12T00:31:01+09:00 종료 코드: 0

⛅️ wrangler 4.129.0 (update available 4.131.1)
───────────────────────────────────────────────
Resource location: remote 

🚧 Time Traveling...
⚠️ The current bookmark is '00000150-00000000-000050e3-e07c569c42b5f42f6ca338dc20e6e6d3'
⚡️ To restore to this specific bookmark, run:
 `wrangler d1 time-travel restore builderlog-mailbox --bookmark=00000150-00000000-000050e3-e07c569c42b5f42f6ca338dc20e6e6d3`

아래 블록은 이 실행의 출력을 그대로 캡처한 거예요. 다른 환경에서는 다른 결과가 나올 수 있어요.

Time Travel이 실제로 하는 일

Cloudflare는 지원되는 D1 데이터베이스에서 Time Travel을 자동으로 활성화해요. 별도 설정이나 토글이 필요 없어요. 항상 백그라운드에서 실행되며, 데이터베이스를 이전 시점으로 되돌릴 수 있을 만큼의 히스토리를 캡처해요.

두 가지 플랜 등급, 두 가지 보존 기간이 있어요.

플랜	보존 기간
Free	7일
Paid	30일

이게 전체 한계예요. 다른 무엇을 계획하기 전에 가장 먼저 확인해야 할 것이 바로 이 보존 기간이지, 복구 명령어나 복구 대상 시각이 아니에요.

Time Travel은 상태를 복구할 뿐 복사본을 보존하지 않아요 — 아무 옵션이 있다고 가정하기 전에 보존 기간을 확인하세요.

복구가 백업과 같지 않은 이유

이 구분은 사고 도중이 되기 전까지는 형식적으로 느껴질 수 있어요. Time Travel을 사용한 D1 복구는요:

현재 데이터베이스에 직접 영향을 미쳐요 — 별도의 목적지가 없어요
실행되는 순간 진행 중인 쿼리를 취소해요
복구 자체가 반환하는 이전 북마크를 사용해 되돌릴 수 있어요

이 중 어느 것도 백업-복제 워크플로와 닮지 않았어요. 백업이라는 말은 안전한 곳에 놓인 두 번째, 독립적인 복사본을 의미해요. Time Travel은 하나의 데이터베이스를 위한 되감기 메커니즘이지, 복제 메커니즘이 아니에요. “먼저 클론에 복구해서 테스트해볼게”라는 사고방식이라면, 공식 참조 문서에 따르면 그건 이 기능이 하는 일이 아니에요. 테스트나 마이그레이션을 위한 실제 복제본이 필요하다면 그건 완전히 별개의 메커니즘이에요 — 여러분의 환경에서 그게 어떤 모습인지는 최신 Cloudflare 문서를 확인하세요. 이 글이 그걸 추측할 자리는 아니거든요.

의사결정표

복구 명령어를 실행하기 전에 채워야 할 표예요. CLI를 건드리기 전에 종이나 문서에 작성하세요.

항목	작성할 내용	중요한 이유
플랜 등급	Free(7일) 또는 Paid(30일)	도달 가능한 범위의 바깥 경계를 정해요
남은 보존 기간	지금부터 사고 시점까지의 일수	사고가 보존 기간 이전이면 중단하세요 — Time Travel이 도와줄 수 없어요
복구 대상 타임스탬프/북마크	되돌리고자 하는 정확한 시점	”오늘 아침”처럼 막연한 대상은 충분히 정확하지 않아요
현재 북마크(복구 전)	실행 직전의 북마크 값	이게 여러분의 되돌리기 경로예요 — 나중이 아니라 먼저 적어두세요
진행 중 요청/트래픽	현재 이 데이터베이스에 들어오고 있는 것	복구는 진행 중인 쿼리를 취소해요 — 무엇이 깨질지 알아두세요
복구가 잘못됐을 때의 롤백 계획	현재 북마크로 되돌리기	필요해지기 전에 역방향 복구 단계를 이해했는지 확인하세요

여섯 항목이에요. 어느 것도 코드를 요구하지 않아요. 모두 기억에 의존해 명령어를 실행하는 대신 멈춰서 무언가를 적어두길 요구해요.

복구 전에 현재 북마크를 적어두는 것이 여러분이 가질 수 있는 유일한 롤백 계획이에요.

”Cloudflare D1 backup”이라는 검색어가 여기에 들어맞는 지점

Google 자동완성에서 “Cloudflare D1 backup”이라는 정확한 검색어가 2026-09-09에 나타났어요. 이건 표현에 관한 신호예요 — 사람들이 백업을 검색하고 있는데, D1이 다른 일부 데이터베이스처럼 별도로 명명된 백업 제품을 현재 제공하지 않기 때문에 Time Travel 문서를 만나게 되는 거예요. “D1 backup”을 검색해서 여기에 오셨고 별도의 백업 기능을 기대하셨다면, 솔직한 답은 이거예요. Time Travel이 내장된 메커니즘이고, 이건 복구/되감기 도구지 복제-저장 도구가 아니에요.

사람들이 검색하는 것과 제품이 실제로 제공하는 것 사이의 이 간극은 잠시 생각해볼 가치가 있어요. “라이브 데이터베이스를 건드리지 않고 쿼리할 수 있는 독립적인 복사본이 필요하다”가 여러분의 운영 요구사항이라면, Time Travel의 보존 기간표는 그 질문에 답하지 못해요. 신뢰성 요구사항이 요구하는 주기에 따라 별도로 데이터를 내보내는 방법을 찾아야 할 텐데, 그건 여기서 검증된 범위 밖이에요.

실패와 한계, 솔직하게 말하자면

저는 프로덕션 D1 데이터베이스에서 실제 복구 테스트를 수행한 적이 없어요. 여기에는 “작동했다” 또는 “깨졌다”는 보고가 전혀 없어요.
보존 기간 수치(Free 7일, Paid 30일)는 Cloudflare의 Time Travel 참조 페이지에서 직접 가져온 것으로, 2026-09-09에 확인했어요. 신뢰하기 전에 최신 문서에서 현재 수치를 확인하세요 — 플랜과 한도는 변경돼요.
자동완성이 검색어 표현과 일치한다고 해서 검색량, 난이도, 또는 실제로 별도 백업이 필요한 사람이 얼마나 되는지는 알 수 없어요.
이 표는 다중 리전, 다중 데이터베이스, 또는 CI/CD로 트리거되는 복구 시나리오를 다루지 않아요. 여러분의 런타임과 프로젝트 구성은 직접 확인해야 해요.

최종 판단, 그리고 Saju 라이선스가 관련되는(또는 관련되지 않는) 지점

D1을 운영 중이고 아직 사고를 겪지 않았다면, 판단은 간단해요. 플랜 등급을 알고, 보존 기간을 알고, 의사결정표를 사고 중에 실제로 찾을 수 있는 곳에 두세요 — 몇 달째 열어보지 않은 위키 안에 묻어두지 마시고요.

별개로, 그저 덧붙이자면, 제가 유지하는 Saju 웹앱 소스 라이선스(하나의 프로젝트로 판매되는 한국식 사주 웹앱 소스)는 구매자가 독립적으로 선택하는 인프라 위에서 작동해요 — D1 사용, 보존 플랜, 백업 전략은 라이선스가 여러분을 위해 구성해주는 부분이 아니에요. 이 제품을 검토 중이시라면, 이 글의 D1 메커니즘이 그 스택에 자동으로 적용된다고 가정하기보다는 현재 제공 항목과 설치 요구사항을 제품 페이지에서 확인하세요.