타임 트래블과 백업 (Time Travel and backups)

원문 보기 위키 갱신 2026.10.07

D1의 백업과 특정 시점 복구(point-in-time recovery) 기능인 타임 트래블(Time Travel)에 대해 다루는 문서예요. 지난 30일 내의 어느 분 단위 시점으로 데이터베이스를 복원할 수 있어요.

출처: 문서

본문

Time Travel and backups

타임 트래블은 D1의 백업과 특정 시점 복구 방식이에요. 데이터베이스를 지난 30일 내의 어느 분 단위 시점으로 복원할 수 있게 해줘요.

타임 트래블을 활성화할 필요가 없어요. 항상 켜져 있어요.
데이터베이스 기록과 데이터베이스 복원은 추가 비용이 들지 않아요.
타임 트래블은 사용자를 대신해 북마크를 자동으로 생성해요. 수동으로 백업을 시작하거나 기억할 필요가 없어요.

정기 백업이나 수동 백업에 의존할 필요가 없으므로, 실패한 마이그레이션이나 스키마 변경, 특정 WHERE 절이 없는 DELETE·UPDATE 문 이전 시점으로 돌아가 데이터베이스를 복원할 수 있고, 향후에는 프로덕션 데이터베이스를 직접 포크/복사할 수도 있어요.

북마크 (Bookmarks)

타임 트래블은 D1의 북마크(bookmark) 개념을 활용해 특정 시점으로 복원해요. 북마크는 특정 시점의 데이터베이스 상태를 나타내요.

30일보다 오래된 북마크는 유효하지 않으며 복원 지점으로 사용할 수 없어요.
특정 북마크로 데이터베이스를 복원해도 더 오래된 북마크가 제거되거나 삭제되지는 않아요. 예를 들어 10분 전 데이터베이스 상태를 나타내는 북마크로 복원한 뒤, 더 이른 시점으로 복원해야 한다고 판단해도 여전히 그렇게 할 수 있어요.
북마크는 사전식(lexicographically)으로 정렬 가능해요. 정렬하면 북마크 목록을 오래된 것부터 최신 것 순서로 배열할 수 있어요.
북마크는 Unix 타임스탬프 ↗︎(1970년 1월 1일 이후 초)에서 파생될 수 있으며, 특정 타임스탬프와 북마크 사이의 변환은 결정적(안정적)이에요.

북마크는 세션 API에서도 활용되어 세션 내 순차적 일관성(sequential consistency)을 보장해요.

타임스탬프 (Timestamps)

타임 트래블은 두 가지 타임스탬프 형식을 지원해요.

Unix 타임스탬프 ↗︎: 1970년 1월 1일 자정 이후의 초에 해당하며, 항상 UTC로 표시돼요.
JavaScript 날짜-시간 문자열 형식 ↗︎: ISO-8601 타임스탬프 형식의 단순화 버전이에요. Americas/New_York (EST)에서 2023년 7월 27일 오전 11:18을 나타내는 유효한 날짜-시간 문자열은 2023-07-27T11:18:53.000-04:00처럼 보여요.

요구 사항 (Requirements)

타임 트래블 명령을 사용하려면 Wrangler v3.4.0 이상이 설치되어 있어야 해요.
D1 프로덕션 백엔드에 있는 데이터베이스가 있어야 해요. 데이터베이스가 이 백엔드를 사용하는지 wrangler d1 info DB_NAME로 확인할 수 있어요. 출력에 version: production가 표시되면 돼요.

북마크 가져오기 (Retrieve a bookmark)

d1 info 명령을 호출해 현재 타임스탬프의 북마크를 가져올 수 있어요. 이 명령은 기본적으로 현재 북마크를 반환해요.

wrangler d1 time-travel info YOUR_DATABASE

🚧 Time Traveling...
⚠️ The current bookmark is '00000085-0000024c-00004c6d-8e61117bf38d7adb71b934ebbf891683'
⚡️ To restore to this specific bookmark, run:
 `wrangler d1 time-travel restore YOUR_DATABASE --bookmark=00000085-0000024c-00004c6d-8e61117bf38d7adb71b934ebbf891683`

과거의 타임스탬프에 대한 북마크를 가져오려면 --timestamp 플래그에 유효한 Unix 또는 RFC3339 타임스탬프를 전달하세요.

RFC3339 타임스탬프(시간대 포함)를 사용하는 경우:

wrangler d1 time-travel info YOUR_DATABASE --timestamp="2023-07-09T17:31:11+00:00"

데이터베이스 복원 (Restore a database)

데이터베이스를 특정 특정 시점으로 복원하려면:

wrangler d1 time-travel restore YOUR_DATABASE --timestamp=UNIX_TIMESTAMP

🚧 Restoring database YOUR_DATABASE from bookmark 00000080-ffffffff-00004c60-390376cb1c4dd679b74a19d19f5ca5be

⚠️ This will overwrite all data in database YOUR_DATABASE.
In-flight queries and transactions will be cancelled.

✔ OK to proceed (y/N) … yes
⚡️ Time travel in progress...
✅ Database YOUR_DATABASE restored back to bookmark 00000080-ffffffff-00004c60-390376cb1c4dd679b74a19d19f5ca5be

↩️ To undo this operation, you can restore to the previous bookmark: 00000085-ffffffff-00004c6d-2510c8b03a2eb2c48b2422bb3b33fad5

다음 사항을 유의하세요.

타임스탬프는 결정적이고 안정적인 북마크로 변환돼요. 같은 타임스탬프는 항상 같은 북마크를 나타내요.
실행 중이던(in flight) 쿼리는 취소되고 클라이언트에 오류가 반환돼요.
복원 작업은 복원 실행 취소를 하고 데이터베이스를 되돌릴 수 있는 북마크를 반환해요.

복원 실행 취소 (Undo a restore)

다음 방법으로 복원을 실행 취소할 수 있어요.

wrangler d1 time-travel restore 작업의 일부로 반환된 이전 북마크를 기록해 두기
마지막 복원 이전의 과거 북마크로 직접 복원하기

더 이른 상태의 북마크를 가져오려면:

wrangler d1 time-travel info YOUR_DATABASE

🚧 Time Traveling...
⚠️ The current bookmark is '00000085-0000024c-00004c6d-8e61117bf38d7adb71b934ebbf891683'
⚡️ To restore to this specific bookmark, run:
 `wrangler d1 time-travel restore YOUR_DATABASE --bookmark=00000085-0000024c-00004c6d-8e61117bf38d7adb71b934ebbf891683`

Workflows를 사용해 D1을 R2로 내보내기

REST API와 Cloudflare Workflows를 사용해 D1 데이터베이스를 R2 스토리지로 자동 내보낼 수 있어요. D1 데이터베이스의 상태를 30일보다 오래 저장하고 싶다면 유용할 수 있어요.

Export and save D1 database 가이드를 참조하세요.

참고 사항 (Notes)

macOS와 Windows 명령줄에서 date +%s로 Unix 타임스탬프를 빠르게 구할 수 있어요.
타임 트래블은 아직 기존 데이터베이스를 새 복사본으로 클론 또는 포크하는 것을 지원하지 않아요. 향후에는 타임 트래블로 기존 데이터베이스를 새 데이터베이스로 포크(복제)하거나 기존 데이터베이스를 덮어쓸 수 있게 될 거예요.
데이터베이스를 지난 30일(Workers 유료 플랜) 또는 7일(Workers 무료 플랜)까지 특정 시점으로 복원할 수 있어요. 타임 트래블의 제한 사항에 대한 자세한 내용은 제한 사항 (Limits)을 참조하세요.