D1에서 가상 테이블을 포함한 데이터베이스를 내보낼 수 있게 됐지만, 새 SQLite CLI 전용 덤프를 다시 D1에 가져오는 것은 지원하지 않습니다. Cloudflare가 2026년 11월 12일 발표한 변경에서 가장 먼저 구분할 조건이에요. 파일을 얻은 사실과 원하는 대상에 복원할 수 있다는 확인은 같은 결과가 아닙니다.
이 글은 FTS5 검색 테이블이나 R*Tree 같은 가상 테이블이 있는 D1을 운영하며 로컬 점검·데이터 반출을 준비하는 분을 위한 안내예요. 11월 16일 공식 발표와 현재 export API, 일반 안내를 확인했습니다. 실제 데이터베이스를 내보내거나 복원하고 장애 복구 시간을 측정한 사례는 아닙니다.
가상 테이블 지원 소식은 목적지부터 읽어 주세요
11월 12일 공지는 이전에는 가상 테이블이 포함된 데이터베이스의 내보내기가 실패했다고 설명합니다. 새로 추가된 경로에서는 API의 dump_options.compatibility를 sqlite3_cli_only로 정해 가상 테이블을 덤프에 포함할 수 있어요. Wrangler의 d1 export에도 같은 목적의 --compatibility 옵션이 제공된다고 안내합니다.
공지의 예로는 SQLite FTS5를 이용한 전문 검색 테이블과 R*Tree를 이용한 공간 인덱스 테이블이 나옵니다. 어떤 앱에 검색 기능이 있다는 사실만으로 그 앱의 모든 테이블 구성이 같다고 단정하지는 마세요. 실제 데이터베이스의 구조와 사용 모듈을 먼저 확인할 문제입니다.
중요한 조건은 새 덤프의 사용처입니다. 공지는 이 형식이 SQLite CLI만을 대상으로 하며 D1에 다시 가져오는 것은 지원하지 않는다고 명시합니다. 가상 테이블이 없는 데이터베이스에는 표준 내보내기를 사용하라는 설명도 함께 있어요. 지원이 추가됐다는 한 문장을 D1의 모든 가져오기·복원 경로가 확장됐다는 뜻으로 읽지 않아야 합니다.
가령 검색 기능이 있는 데이터의 구조를 로컬에서 조사하려는 상황과 운영 D1을 다른 D1으로 되돌리려는 상황을 생각해 보세요. 두 상황 모두 파일을 받을 수는 있지만 필요한 목적지와 검증 기준이 다릅니다. 먼저 결과물을 어디에 사용할지 적어 두면 내보내기 옵션을 고르는 이유도 설명하기 편해집니다.
기본 형식과 CLI 전용 형식은 다른 계약이에요
현재 API 참조는 compatibility에 두 값을 설명합니다. 기본값인 d1은 D1이 가져올 수 있는 덤프이며, sqlite3_cli_only는 SQLite의 .dump 출력과 맞는 형식으로 가상 테이블도 포함하지만 D1으로의 재가져오기는 지원하지 않습니다. 확장자가 둘 다 SQL처럼 보여도 목적지 호환성은 따로 읽어야 해요.
| 덤프 형식 | 공식 문서의 사용 범위 |
| d1 | D1이 가져올 수 있는 기본 덤프 형식 |
| sqlite3_cli_only | 가상 테이블을 포함하는 SQLite CLI용 형식. D1 재가져오기 미지원 |
일반 가져오기·내보내기 안내에는 2026년 4월 21일 갱신 표시와 가상 테이블 내보내기의 기존 제약 문구가 남아 있었습니다. 이번 글에서는 새 모드의 지원 범위는 11월 12일 공지와 현재 API의 명시적인 필드 설명으로 확인했어요. 서로 다른 시점의 문장을 합쳐 어느 형식이든 같은 동작을 한다고 설명하지 않겠습니다.
오래된 일반 안내를 보고 운영 데이터베이스에서 가상 테이블을 먼저 삭제하는 방식으로 곧바로 진행하지 마세요. 새 옵션이 필요한 상황인지, 원본을 유지할 방법과 실제 복원 목적이 무엇인지부터 다시 검토할 부분입니다. 이 글은 테이블 삭제·재생성이나 운영 데이터 변경을 지시하지 않습니다.
Wrangler로 진행하려는 경우에는 설치된 버전에서 해당 옵션이 지원되는지 현재 도움말과 공식 문서를 대조해 주세요. 이 글은 검증하지 않은 최소 버전 숫자를 만들지 않습니다. 실행 도구의 이름, 실제 버전, 대상 계정·데이터베이스와 선택한 모드를 기록해 나중에 무엇을 반출했는지 추적할 수 있게 하는 것이 목적입니다.
API 요청 성공과 내보내기 완료를 구분해요
export API는 SQL 내용을 내보내고 다운로드할 주소를 반환하는 작업으로 설명됩니다. 요청에서는 output_format을 polling으로 정하고 완료될 때까지 상태를 조회하는 방식을 사용해요. 진행 중인 내보내기를 확인할 때는 첫 응답에서 돌려준 북마크를 current_bookmark에 사용하도록 문서가 안내합니다.
따라서 API 호출이 성공했다는 가장 바깥 응답과 실제 내보내기 작업이 끝났다는 상태를 나누어 읽을 필요가 있습니다. 현재 참조는 작업의 status와 error, 메시지, 완료 때 제공되는 결과 파일 이름과 서명된 URL을 구분합니다. 성공 한 칸만 보고 파일 검토까지 끝났다고 기록할 근거는 아니에요.
문서는 큰 데이터베이스에서 시간이 걸릴 수 있고 그동안 D1이 쿼리를 제공할 수 없다고 설명합니다. 불필요하게 막힌 상태를 유지하지 않도록 진행 중 작업을 계속 조회하지 않으면 자동 취소된다는 조건도 있어요. 내보내기를 가벼운 단일 조회와 똑같은 운영 영향으로 보지 않을 이유입니다.
가상의 운영 메모에는 작업을 요청한 시각과 이후 관찰한 상태, 북마크, 오류·메시지, 완료 여부와 파일을 실제 보존한 시각을 구분해 적을 수 있습니다. 민감한 인증값은 빼고 담당자가 작업의 흐름을 확인할 수 있는 정보만 남겨 보세요. 이 메모는 이 글의 제안이며 실제 API 실행 로그는 아닙니다.
진행 응답이 불명확하다면 현재 작업의 상태와 식별 정보를 먼저 대조하는 편이 좋습니다. 같은 작업을 다시 제출한 사실과 기존 작업을 조회한 사실을 혼동하지 않아야 해요. 중복 요청을 해결하는 구체적인 절차는 실제 응답과 현재 도구의 지원 범위에 따라 판단할 문제입니다.
전체 덤프인지, 스키마인지, 데이터인지 확인하세요
파일을 받았더라도 어떤 내용을 요청했는지 확인이 남습니다. 현재 API의 no_data는 테이블 정의만 내보내고 내용은 제외하는 옵션이며, no_schema는 테이블 내용만 내보내고 정의는 제외하는 옵션입니다. 둘은 같은 생략 조건이 아니에요. 필요한 결과가 무엇인지부터 정한 뒤 현재 요청을 읽어야 합니다.
또한 tables로 한 개 이상의 테이블을 고를 수 있습니다. 문서는 빈 배열이 아무 테이블도 선택하지 않았다는 뜻이 아니라 값을 생략한 것과 같아 전체 테이블을 내보낸다고 설명합니다. 설정 파일을 읽을 때 빈 목록을 안전한 빈 결과로 단정하지 않을 중요한 이유예요.
받은 파일의 이름만으로 범위를 판단하기보다 선택 모드와 테이블 목록, 스키마·데이터 옵션을 함께 남기는 방식을 제안합니다. 로컬 점검용으로 구조만 필요한지, 승인된 데이터까지 필요한지에 따라 자료 반출 범위가 달라집니다. 실제 값이 들어 있는 덤프라면 보관 위치와 접근 권한도 데이터 취급 정책에 맞춰야 합니다.
파일 내용 점검에서도 질문을 나눠 보세요. 요청한 구조가 있는지, 필요한 테이블이 포함됐는지, 데이터가 필요한 목적이라면 해당 범위가 들어 있는지 확인하는 것입니다. 파일이 존재하거나 용량이 커 보인다는 사실만으로 이 질문에 모두 답할 수는 없습니다. 가상 테이블이 포함된 경우에는 그 구조를 읽을 로컬 도구의 지원 조건도 별도로 확인해야 합니다.
정밀한 값의 동일성이나 애플리케이션의 검색 동작까지 필요한 경우에는 그 검토 목표를 따로 적어야 합니다. 이 글은 원본과 덤프의 모든 값을 대조하거나 로컬 검색 결과를 시험하지 않았어요. 어떤 증거를 확보했고 어떤 검증이 더 필요한지 구분하는 것이 파일 검사 단계의 목적입니다.
다운로드 주소와 운영 데이터는 보존 방식도 달라요
현재 API 문서는 완료 결과의 서명된 다운로드 URL을 한 시간 동안 사용할 수 있다고 설명합니다. 응답 주소를 메모한 사실과 덤프 파일을 실제로 내려받아 승인된 위치에 보존한 사실은 다른 기록이에요. 나중에 주소만 남았는데도 백업 파일이 있다고 착각하지 않는 편이 좋습니다.
서명된 주소나 인증 토큰을 공개 글·공용 로그에 그대로 남기지 마세요. 자료를 받을 수 있는 경로와 데이터 자체는 정해진 접근 범위 안에서 관리할 대상입니다. 파일의 보존 시각과 식별 가능한 해시, 선택한 모드 같은 정보로 작업을 추적하고 실제 비밀값의 노출은 피하는 방식이 가능합니다.
실행 전에는 운영 요청이 막힐 수 있다는 조건을 담당자와 함께 검토해 주세요. 사용자가 접속하는 서비스라면 언제 작업할지, 상태 조회를 누가 맡을지, 실패나 중단 때 무엇을 확인할지도 정해 두는 것이 좋습니다. 이 글은 특정 시간 안에 내보내기가 끝난다거나 서비스 영향이 없다고 보장하지 않습니다.
원본 데이터와 기존에 검증한 복구 경로도 보존해야 합니다. 새 반출 모드를 사용했다는 이유로 기존 백업을 지우거나 복구 계획을 교체할 필요는 없어요. 파일을 만드는 기능의 추가와 장애 때 애플리케이션을 되살릴 수 있다는 확인 사이에 어떤 절차가 남는지 살펴볼 기회입니다.
복구 준비 메모에는 목적지와 미확인을 함께 남겨요
가상 테이블이 있는 D1의 구조를 로컬에서 살펴보려는 경우라면, 이번 모드가 그 반출 목적에 맞는지 확인할 수 있습니다. 반면 원하는 결과가 D1으로의 재가져오기라면 CLI 전용 덤프의 제한부터 분명히 적어야 해요. 지원하지 않는 경로를 파일 편집만으로 확실히 해결할 수 있다고 이 글에서 안내하지 않겠습니다.
복원 시험이 필요한 상황에서는 운영 데이터베이스에 곧바로 가져오기 작업을 하기보다 조직이 승인한 격리된 대상과 검토 범위를 먼저 정해 주세요. 무엇을 복원할지, 애플리케이션이 기대하는 구조·값·검색 동작을 어디까지 확인할지 담당자가 판단할 문제입니다. 실제 시험을 하지 않았다면 복원 성공이나 복구 시간은 미확인으로 남겨야 합니다.
자주 묻는 질문도 정리해 볼게요. 가상 테이블 export가 되면 D1 import도 되나요? 새 CLI 전용 형식은 지원하지 않습니다. 성공 응답이면 파일까지 보존됐나요? 완료 상태와 실제 다운로드를 확인해야 해요. 테이블 목록이 비어 있으면 아무 데이터도 안 나가나요? API는 전체 테이블을 뜻한다고 설명합니다.
이번 변경의 이익은 이전에 막혔던 구조를 내보내 확인할 선택지가 생겼다는 데 있습니다. 그 이익을 활용하면서 덤프의 형식, 작업 완료, 파일 보존, 목적지 검증을 각각 적어 보세요. 같은 파일을 받았다는 사실을 다른 서비스와 다른 복구 목적의 성공으로 넓히지 않는 기록이 운영 판단을 명확하게 해 줍니다.
자료 확인일은 2026년 11월 16일입니다. 공식 발표와 현재 문서로 확인한 범위를 정리했으며 실제 계정 설정 변경·명령 실행·성능 시험은 하지 않았어요. 적용 시점의 계정·버전·환경 조건은 담당자가 다시 확인해 주세요.
함께 읽어 볼 글: D1 원자료를 AI Search에 연결할 때의 읽기·동기화 조건. 이번 글과 적용 질문이 어떻게 다른지 함께 살펴보세요.

'소프트웨어개발' 카테고리의 다른 글
| GitHub AI Scan 관리 API 추가: 설정 켜기와 검사 완료는 달라요 (0) | 2026.11.17 |
|---|---|
| EmbeddingGemma 2가 Workers AI에 왔어요: 검색 전 차원과 입력을 맞추세요 (0) | 2026.11.17 |
| Copilot 모델 12월 14일 종료 예고: 대체 모델과 연간 구독 예외 확인하세요 (0) | 2026.11.16 |