DbGate로 Cloudflare D1 데이터베이스 관리하기

Published: 2026-10-19 | Jan Procházka

Cloudflare D1은 Cloudflare Workers 가까이에서 실행되는 서버리스 SQL 데이터베이스입니다. SQLite를 사용하고 서버를 설정할 필요가 없으며, 애플리케이션 규모가 커지기 전까지 무료로 이용할 수 있습니다. 다만 데이터를 편하게 살펴볼 수 있는 환경은 부족합니다. Cloudflare 대시보드에는 기본 콘솔이 있고 Wrangler로 명령줄에서 SQL을 실행할 수 있지만, 둘 다 본격적인 데이터베이스 관리 도구는 아닙니다.

이 가이드에서는 D1에 적합한 용도와 제한 사항을 설명하고, DbGate에 연결해 다른 데이터베이스처럼 탐색, 조회, 편집, 백업하는 방법을 소개합니다.

Cloudflare D1은 버전 7.3.0부터 DbGate Premium에서 지원됩니다. D1 데이터베이스 백업과 복원은 버전 7.3.2에 추가되었습니다.

Cloudflare D1이란?

D1은 SQLite를 기반으로 한 Cloudflare의 관리형 데이터베이스입니다. 각 D1 데이터베이스는 Cloudflare가 저장하고 복제하는 완전한 SQLite 데이터베이스입니다. 클릭 한 번이나 wrangler d1 create 명령으로 만들고, Worker에 바인딩한 뒤 일반 SQL로 조회할 수 있습니다.

D1이 제공하는 기능은 다음과 같습니다.

SQLite 기능 – JSON 함수와 FTS5 전체 텍스트 검색을 포함하여 SQLite에서 익숙한 SQL 문법, 데이터 형식, 함수
인프라 관리 불필요 – 서버, 연결 풀, 패치, 용량 계획을 관리할 필요가 없습니다
사용량 기반 요금 – 읽은 행, 쓴 행, 저장 공간에 따라 비용을 지불하며 넉넉한 무료 사용량이 제공됩니다
여러 개의 작은 데이터베이스 – 계정 하나에 수천 개의 데이터베이스를 둘 수 있어 테넌트나 사용자마다 별도 데이터베이스를 사용하는 설계가 가능합니다
Time Travel – 백업 설정 없이 보존 기간 내 원하는 시점의 분 단위로 복원할 수 있습니다(유료 요금제는 30일)
읽기 복제 – 다른 지역에 선택적으로 읽기 복제본을 두어 전 세계 사용자에게 제공되는 읽기 지연 시간을 줄입니다
Workers와 긴밀한 통합 – Worker가 바인딩으로 데이터베이스에 접근하므로 코드에 자격 증명을 넣거나 네트워크를 설정할 필요가 없습니다

D1 데이터베이스에 접근하는 방법은 세 가지입니다.

Worker 바인딩 – 프로덕션에서 애플리케이션이 D1에 접근하는 방법
Wrangler CLI – 개발 중 마이그레이션과 일회성 명령에 사용
Cloudflare REST API – Cloudflare 외부에서 관리할 때 사용하며, DbGate도 이 방식으로 연결합니다

알아두어야 할 제한 사항

D1은 SQLite를 사용하지만 로컬 SQLite 파일은 아닙니다. 선택하기 전에 제한 사항이 애플리케이션에 맞는지 확인하세요. 아래 수치는 작성 당시 기준입니다. 최신 값은 D1 공식 제한 사항 페이지를 참조하세요.

데이터베이스 크기 – 단일 데이터베이스는 유료 요금제에서 최대 10 GB, 무료 요금제에서 최대 500 MB입니다. D1은 하나의 거대한 데이터베이스보다 여러 작은 데이터베이스로 확장하도록 설계되었습니다.
한 번에 한 명의 작성자 – 데이터베이스마다 쿼리를 순서대로 처리합니다. 따라서 처리량은 쿼리 속도에 달려 있고, 오래 실행되는 쿼리는 뒤따르는 작업을 막습니다.
대화형 트랜잭션 미지원 – BEGIN으로 트랜잭션을 시작하고 작업한 뒤 나중에 COMMIT할 수 없습니다. 대신 D1은 여러 문으로 이루어진 배치를 원자적으로 실행합니다. 모두 성공하거나 아무것도 적용되지 않습니다.
문과 값의 크기 – SQL 문 하나는 최대 100 KB, 행·문자열·BLOB 하나는 최대 2 MB입니다. 큰 파일은 D1이 아니라 R2에 저장해야 합니다.
쿼리 실행 시간 – 쿼리 하나는 최대 30초 동안 실행할 수 있습니다.
읽은 행 기준 과금 – 쿼리가 반환한 행뿐 아니라 실제로 읽은 모든 행에 비용이 부과됩니다. 큰 테이블을 전체 스캔하면 비용이 커지므로 적절한 인덱스가 특히 중요합니다.
파일 수준 SQLite 기능 미지원 – ATTACH DATABASE, 확장 프로그램 로드, sqlite_master 쓰기는 허용되지 않습니다. 외래 키는 항상 적용됩니다. 배치 안에서는 PRAGMA foreign_keys = OFF 대신 PRAGMA defer_foreign_keys = on을 사용할 수 있습니다.
예약된 이름 – _cf_로 시작하는 테이블은 Cloudflare 내부용이므로 읽거나 수정할 수 없습니다.
REST API 요청 제한 – REST API에는 Cloudflare의 전역 API 요청 제한이 적용됩니다. 관리와 도구용이지 프로덕션 트래픽 처리용이 아닙니다. 애플리케이션은 Worker 바인딩을 사용해야 합니다.

일반적인 활용 사례

애플리케이션이 이미 Cloudflare에서 실행되거나 데이터를 작고 독립적인 데이터베이스로 자연스럽게 나눌 수 있다면 D1이 특히 적합합니다.

Workers와 Pages의 백엔드 – 엣지에서 실행되는 웹 애플리케이션의 사용자 계정, 설정, 콘텐츠, 주문
테넌트별 데이터베이스 – SaaS 고객마다 분리된 데이터베이스를 제공해 데이터 분리, 삭제, 내보내기를 쉽게 합니다
콘텐츠 및 구성 저장소 – 블로그, CMS 콘텐츠, 기능 플래그, 리디렉션 등 읽기가 많은 데이터로, 읽기 복제본과 함께 사용하는 것이 좋습니다
프로토타입과 개인 프로젝트 – 무료 사용량과 간단한 설정 덕분에 빠르게 시작하고 나중에 확장할 수 있습니다
가벼운 분석과 로그 – 데이터베이스별 크기 제한을 지키면서 카운터, 이벤트, 감사 로그를 저장합니다
다른 데이터의 엣지 캐시 – 기본 데이터베이스의 일부 데이터를 사용자 가까이에 SQLite 복사본으로 둡니다

D1은 쓰기가 많은 단일 대형 OLTP 데이터베이스, 긴 대화형 트랜잭션이 필요한 작업, 큰 바이너리 파일 저장에는 적합하지 않습니다. 이런 경우 PostgreSQL, MySQL 또는 다른 전통적인 데이터베이스가 더 적합하며, Cloudflare Hyperdrive로 연결할 수도 있습니다.

DbGate를 Cloudflare D1에 연결하기

DbGate는 Cloudflare REST API를 통해 D1에 연결합니다. 연결 하나는 Cloudflare 계정 하나에 연결되며 API 토큰이 접근할 수 있는 모든 D1 데이터베이스를 표시합니다.

1단계 – 계정 ID 찾기

Cloudflare 대시보드에 로그인합니다.
Storage & Databases | D1 SQL Database 또는 계정 홈 화면을 엽니다.
Account ID를 복사합니다. 계정 세부 정보와 대시보드 URL(dash.cloudflare.com/<account-id>/...)에서 확인할 수 있습니다.

2단계 – API 토큰 만들기

My Profile | API Tokens로 이동해 Create Token을 클릭합니다.
Create Custom Token을 선택합니다.
Permissions에서 Account | D1 | Edit를 추가합니다. 데이터 읽기만 필요하면 Read로 충분합니다.
Account Resources에서 데이터베이스가 있는 계정을 선택합니다.
필요하다면 토큰을 자신의 IP 주소로 제한하고 만료일을 설정합니다.
토큰을 만들고 복사합니다. Cloudflare는 토큰을 한 번만 표시합니다.

DbGate 전용 토큰을 사용하면 배포 파이프라인에서 사용하는 토큰과 별개로 폐기할 수 있습니다.

3단계 – DbGate에서 연결 만들기

DbGate에서 New connection을 클릭합니다.
연결 유형으로 Cloudflare D1을 선택합니다.
Cloudflare Account ID와 Cloudflare API Token을 입력합니다.
사용자 지정 API 엔드포인트가 필요한 경우가 아니라면 Cloudflare API URL을 비워 둡니다. 기본값은 https://api.cloudflare.com/client/v4입니다.
네트워크에서 필요하다면 연결 설정에 HTTP 프록시를 구성합니다.
실수로 데이터를 변경하지 않도록 Is read only를 선택할 수 있습니다.
Test를 클릭한 다음 Save(또는 Connect)를 클릭합니다.

연결 후 DbGate는 토큰이 접근할 수 있는 계정의 모든 D1 데이터베이스를 나열합니다. 데이터베이스를 펼치면 테이블, 뷰, 열, 인덱스, 외래 키를 볼 수 있습니다.

연결에 실패하면 DbGate가 원인을 알려 주려고 합니다. 토큰이 유효하지 않거나 만료되었을 수 있고, D1 권한이 없거나 계정 ID가 틀렸거나 데이터베이스가 더 이상 존재하지 않을 수 있습니다.

DbGate에서 D1 관리하기

DbGate는 내부적으로 D1을 전송 방식이 다른 SQLite로 취급합니다. 데이터 탐색기, SQL 생성, 스키마 분석은 로컬 SQLite 파일에서 사용하는 기능과 같으므로 익숙한 작업 방식 대부분을 그대로 적용할 수 있습니다.

데이터 탐색 및 편집

데이터 탐색기에서 테이블을 열어 행을 필터링, 정렬, 검색하고 외래 키를 따라 관련 레코드로 이동하거나 그리드에서 값을 직접 편집할 수 있습니다. 저장할 때 변경 사항이 D1에 기록됩니다.

D1은 읽은 행 수에 따라 과금되므로 큰 테이블을 탐색할 때는 모든 행을 스크롤하기보다 필터와 인덱스가 있는 열을 사용하세요.

스키마 살펴보기

DbGate는 테이블, 열, 기본 키, 외래 키, 인덱스, 뷰를 포함한 전체 데이터베이스 구조를 읽습니다. D1 쿼리마다 HTTPS 요청이 필요하므로 DbGate는 스키마 분석을 미리 계획하고 수백 개의 개별 쿼리 대신 몇 개의 배치 요청을 보냅니다. 보통 크기의 데이터베이스는 전체 분석에 요청 두 번이면 충분합니다.

Cloudflare 내부의 _cf_* 테이블은 스키마에서 숨겨져 사용자 자신의 객체만 표시됩니다.

SQL 쿼리 실행

D1 데이터베이스에서 쿼리 편집기를 열고 로드된 스키마를 바탕으로 한 자동 완성을 이용해 평소처럼 SQLite SQL을 작성합니다. 여러 문이 포함된 스크립트를 실행하면 DbGate는 모두 하나의 배치로 D1에 보냅니다. D1은 배치를 원자적으로 실행하므로 스크립트가 모두 완료되거나 아무것도 적용되지 않습니다.

다음 사항을 기억하세요.

명시적인 BEGIN, COMMIT, ROLLBACK, SAVEPOINT 문은 D1 API가 대화형 트랜잭션을 지원하지 않으므로 명확한 메시지와 함께 거부됩니다. D1 연결에서는 트랜잭션 버튼도 숨겨집니다.
Is read only로 표시된 연결에서는 DbGate가 SELECT, EXPLAIN, 스키마 읽기용 PRAGMA 문만 허용합니다. 다른 문은 Cloudflare에 보내기 전에 거부됩니다. 보호를 강화하려면 D1 | Read 권한의 API 토큰도 사용하세요.
EXPLAIN QUERY PLAN은 쿼리가 인덱스를 사용하는지 전체 테이블을 스캔하는지 보여 줍니다. 이는 D1 요금에 직접 영향을 줍니다.

데이터 내보내기 및 가져오기

쿼리 결과와 테이블을 CSV, Excel, JSON 등 DbGate가 지원하는 형식으로 내보내고 파일의 데이터를 D1 테이블로 가져올 수 있습니다. 일회성 데이터 수정, 보고서 작성, D1과 DbGate에 연결된 다른 데이터베이스 간의 데이터 이동에 유용합니다.

D1 데이터베이스 백업

Time Travel은 보존 기간 내의 실수로부터 데이터를 보호하지만, 보관하거나 다른 곳에서 열 수 있는 파일을 제공하지는 않습니다. DbGate는 D1 데이터베이스를 일반 SQL 파일로 백업할 수 있습니다.

연결 트리에서 데이터베이스를 마우스 오른쪽 버튼으로 클릭합니다.
Create database backup을 선택합니다.
스키마, 데이터, 데이터베이스 설정, rowid 가운데 포함할 항목을 선택합니다. 로컬 SQLite 백업과 같은 옵션입니다.
백업을 시작합니다.

결과는 일반 SQLite SQL 스크립트입니다. 다른 D1 데이터베이스에 복원하거나 명령줄 도구 sqlite3로 열거나 개발과 디버깅을 위해 로컬 SQLite 파일로 불러올 수 있습니다.

D1로 복원

DbGate는 DbGate에서 만든 백업이나 다른 출처의 SQLite 덤프를 D1 데이터베이스로 복원할 수도 있습니다. 대상 데이터베이스를 마우스 오른쪽 버튼으로 클릭하고 Restore database backup을 선택한 뒤 SQL 파일을 지정합니다.

D1은 덤프를 그대로 받아들이지 않으므로 DbGate가 복원 중 다음과 같이 조정합니다.

덤프를 최대 250개 문(그리고 최대 1 MB)씩 배치로 보냅니다. 각 배치는 하나의 D1 트랜잭션으로 실행되므로 실패한 배치가 부분적인 쓰기 결과를 남기지 않습니다.
각 배치가 자체 트랜잭션이므로 덤프에 포함된 트랜잭션 문을 건너뜁니다.
Cloudflare가 가져오기 작업에 권장하는 PRAGMA defer_foreign_keys = on을 사용해 외래 키 검사를 각 배치의 끝으로 미룹니다.
예약된 _cf_ 이름을 가진 객체를 건너뜁니다.
AUTOINCREMENT 카운터, 통계, user_version처럼 D1이 쓰기를 거부할 수 있는 문은 데이터 처리 후 실행하며, 문제는 경고로만 알립니다.
Stop on first error를 켜면 첫 번째 실패 배치에서 복원을 중단합니다. 그렇지 않으면 계속 진행한 뒤 모든 오류를 마지막에 보고합니다.

D1의 SQL API로 복원할 수 없는 항목은 두 가지입니다. INSERT 문이 D1의 100 KB 제한을 초과하는 행(대개 큰 텍스트나 BLOB 값 때문)과 덤프가 PRAGMA writable_schema로 다시 만드는 가상 테이블입니다. DbGate는 조용히 실패하지 않고 이러한 항목을 명확하게 보고합니다.

백업과 복원을 조합하면 로컬 SQLite 데이터베이스를 D1로 옮기는 것도 간단합니다. DbGate에서 로컬 파일을 백업한 후 SQL 파일을 비어 있는 D1 데이터베이스에 복원하면 됩니다. 반대로 프로덕션 D1 데이터를 테스트용 로컬 SQLite 파일에 복사할 수도 있습니다.

읽기 전용 연결에서는 복원할 수 없습니다.

보안 참고 사항

API 토큰은 다른 DbGate 자격 증명과 마찬가지로 연결과 함께 저장됩니다. 토큰을 공유하지 말고 D1 권한, 단일 계정, 가능하다면 자신의 IP 주소로 제한하세요.
DbGate는 토큰이 로그나 오류 메시지에 나타나지 않도록 합니다.
DbGate Team Premium에서는 서버에 D1 연결을 한 번만 설정하고 어떤 사용자와 역할이 사용할 수 있는지 제어할 수 있습니다. 팀원마다 API 토큰을 배포할 필요가 없습니다.

마무리

Cloudflare D1을 사용하면 Worker, 프로젝트, 테넌트마다 자체 SQL 데이터베이스를 쉽게 제공할 수 있습니다. DbGate에서는 계정 ID와 API 토큰만으로 스키마 탐색, 그리드에서 데이터 편집, SQL 편집기, 데이터 가져오기와 내보내기, 백업과 복원을 이용할 수 있습니다. PostgreSQL, MySQL, SQL Server, SQLite 등 여러 데이터베이스를 관리하던 바로 그 도구에서 모두 처리할 수 있습니다.

DbGate 다운로드 후 D1 데이터베이스에 연결해 보세요.