Cloudflare D1 서비스를 이용하여 웹 애플리케이션에 사용될 SQL DB의 신규 생성 및 DB 데이터 입력 방법을 정리.
Cloudflare D1이란?
Cloudflare D1은 Cloudflare 고유의 서버리스 SQL DB를 제공하는 서비스이다. Cloudflare Pages를 통해 서버리스 웹 애플리케이션의 호스팅 서비스를 제공하고 있는데, 이때 D1이 SQL DB를 저장하고 관리하는 역할을 맡고 있다고 보면 된다.
무료 플랜에서의 D1
이 글을 작성하는 2024년 10월 31일을 기준으로 D1 무료 사용자에게 다음과 같은 서비스가 제공된다.
이 정도면 웹 애플리케이션의 개발 단계와 초기 출시 단계에서 사용하기에는 괜찮은 수준이라 생각된다. 이후 웹 애플리케이션 사용자가 증가했을 때의 트래픽 상승에 대한 요금 증가분도 합리적으로 느껴진다.
웹 메뉴를 이용하는 방법
그럼 이제 D1 서비스를 이용하여 신규 SQL DB를 생성하고 데이터를 입력하는 방법을 알아보자. 총 두 가지 방법이 있는데, 우선 웹 메뉴를 이용하는 방법을 설명한다. 만약 SQL에 대해서 잘 모르는 사람이라면 웹 메뉴를 이용하지 않을 예정이더라도 그냥 넘기지 말자. SQL DB 구조에 대한 감을 잡는 데 도움이 되기 때문이다.
D1 신규 DB 생성
우선 Cloudflare 웹 사이트에 로그인을 해야 한다.
로그인을 마치면 위와 같은 대시보드 페이지를 만날 수 있는데, 여기서 [Workers & Pages > D1 SQL Database]를 선택한 뒤 [+ Create] 버튼을 클릭한다.
다음으로 Name 란에 데이터베이스의 이름을 입력해 주고, [Create] 버튼을 클릭하는 것으로 신규 데이터베이스 생성을 마칠 수 있다.
DB 데이터 입력
신규 DB를 생성했으니 이제 거기에 데이터를 입력해 보자.
데이터를 입력하려면 먼저 테이블이 있어야 한다. 테이블은 엑셀 시트를 연상하면 이해하기 편할 것이다. [Create table] 버튼을 눌러 다음 화면으로 넘어가면,
테이블 이름을 지정하고 컬럼을 추가할 수 있다. 자세한 설명은 다음을 참고하자.
- 하나의 컬럼에 대해 설정해 주어야 하는 항목은 네 개다. 컬럼의 이름, 타입, 디폴트 값과 Primary Key 지정 여부이다.
- 예시로 입력된 ticker와 holdings는 각각 주식 종목 티커명, 보유 주식 수에 해당된다. 그러므로 각 컬럼의 Type을 문자열에 해당하는 text와 정수에 해당하는 integer로 설정해 주었다.
- Default Value는 지정하지 않을 경우 비워두면 된다.
- Primary Key로 지정한다는 것은 지정된 컬럼이 테이블 내에서 각 행을 식별할 수 있는 Key Value로 지정한다는 말이다. 따라서 중복되는 값을 가지면 안 되며, 보통 id 같은 행 식별 목적 컬럼에 지정하면 된다.
- [+ Add Column] 버튼을 누르면 컬럼을 추가할 수 있다.
테이블과 컬럼 설정을 마쳤으면, [Create] 버튼을 눌러 다음으로 넘어간다.
그러면 이전 화면으로 돌아가게 되는데, 하단 목록에 테이블이 추가된 것을 볼 수 있다. 이제 각 컬럼 형식에 맞게 데이터를 추가할 차례다. 이는 콘솔(1) 탭에서도 가능하고, 목록에 표시된 테이블(2)에 직접 들어가서 진행하는 것도 가능하다. 먼저 콘솔 탭에서 진행해 보자.
콘솔 탭에서 입력을 하려면 SQL 명령어를 사용해야 한다. 하단의 입력창에 커맨드를 입력하고 [Excute] 버튼을 눌러 커맨드를 수행시키면 된다. 데이터 입력 SQL 커맨드 문법은 다음과 같다.
INSERT INTO 테이블명 (컬럼1명, 컬럼2명, ...) VALUES (컬럼1에대한값, 컬럼2에대한값, ...);SQL을 처음 접하는 사람이라도 프로그래밍 경험이 있다면 해석에 큰 어려움은 없을 것이다. 다음은 목록에 표시된 테이블에 직접 들어가서 데이터를 입력하는 방법이다. Tables 탭 하단의 목록에서 테이블 이름을 클릭해 주면,
위와 같은 화면이 나오는데, [Add data] 버튼을 클릭하여 각 컬럼에 대한 값을 입력해 주면 된다. 매우 직관적인 방법이므로 시도해 보면 어려움 없이 진행할 수 있을 것이다.
데이터 입력을 마치면 되면 위와 같이 표시된다.
지금까지 웹 메뉴를 사용하여 신규 DB를 생성하고 데이터를 추가하는 방법에 대해 알아보았다. 데이터가 한두 줄이라면 이 방법은 크게 불편하지 않다. 하지만 만약 데이터가 수백, 수천 줄이라면? 생각만 해도 답답해지는 상황이다. 이러한 경우를 위해 CLI 툴을 이용하는 방법이 있다.
CLI 툴을 이용하는 방법
D1 신규 DB 생성
CLI 툴을 이용한 방법은 NPM(Node Package Manager)이 설치된 환경을 전제로 한다.
npm install -g wrangler우선 터미널(윈도우 OS의 경우 명령 프롬프트 사용)을 열고 위 커맨드를 입력하여 Wrangler CLI를 설치한다.
npm create cloudflare@latest 프로젝트명다음으로 Cloudflare 프로젝트를 생성할 경로에서 위와 같이 입력하여 신규 프로젝트를 생성해 준다. 만약 기존 프로젝트를 위한 DB를 생성하는 것이라면 이 절차를 건너뛰고 해당 프로젝트 루트 경로로 이동한 뒤 밑에 있는 Cloudflare 로그인 단계부터 이어나가면 된다.
D1 DB의 경우 웹 대시보드 상에서는 Cloudflare 프로젝트에 속하지 않고 별도의 구조로 관리되는 것을 볼 수 있다. 하지만 앞서 기존 프로젝트가 없을 때 굳이 신규 프로젝트를 생성했던 이유는 wrangler.toml 파일 문제 때문이다. 이 파일은 로컬에서 Cloudflare D1 DB에 접근할 때 필요한 환경 정보들이 담기는 파일인데, Cloudflare Workers나 Pages 프로젝트를 생성할 때 자동으로 만들어진다.
물론 프로젝트 생성 없이 wrangler.toml 파일을 수동으로 생성해서 세부 설정을 잡아주고, 사용하는 것이 가능한 것으로 보인다. 하지만 Wrangler의 버전이 올라가면서 deprecated 되는 기존 커맨드들(init, publish 등)의 역할을 생각해 보면 Cloudflare 측은 프로젝트 안에서 DB가 관리되는 구조를 원하는 것 같다. 그러므로 프로젝트 없이 DB만 구축하려는 상황이더라도 Workers의 Hello World 프로젝트 정도를 만들어 주자.
cd 프로젝트명프로젝트가 생성되고 기본 템플릿 설치가 완료되었다면 프로젝트의 루트 경로로 이동한다.
wrangler loginwrangler를 이용하여 Cloudflare 로그인을 진행해 주고,
wrangler d1 create 데이터베이스명새로운 D1 DB까지 생성을 해 준다.
문제없이 생성되면 위와 같은 화면을 만나게 되는데, 빨간색 네모 표시한 부분을 복사한 뒤,
프로젝트 루트 경로에 있는 wrangler.toml 파일을 열고, d1_database 설정 부분을 찾아 위와 같이 고친 뒤 저장한다. 주석 처리되어 있는 45번 라인이 주석 해제되어야 한다는 점을 유의하자.
참고로 binding 값은 코드 레벨에서 해당 DB에 접근하기 위한 식별자라고 한다.
DB 데이터 입력
이제 데이터를 입력해 주면 되는데,
wrangler d1 execute 데이터베이스명 --remote --file SQL파일경로위와 같이 미리 준비된 SQL 파일을 지정하여 execute 커맨드를 입력하는 것으로 테이블 생성, 컬럼 설정, 그리고 데이터 입력까지 진행하게 된다. SQL 문법에 익숙하지 않은 사람들을 위해 다음과 같이 샘플을 준비해 보았다.
CREATE TABLE my_weight (
id INTEGER PRIMARY KEY AUTOINCREMENT,
datetime TEXT,
value REAL,
unit TEXT
);
BEGIN TRANSACTION;
INSERT INTO my_weight (datetime, value, unit) VALUES
('2024-10-01 10:00:00', 50.5, 'kg'),
('2024-10-02 11:00:00', 60.4, 'kg'),
('2024-10-03 12:30:00', 70.1, 'kg');
COMMIT; -- 모든 INSERT가 성공하면 커밋좀 더 상세한 설명이 필요하다면 다음을 참고하자.
- Cloudflare D1은 SQLite 문법을 따른다.
- CREATE TABLE은 테이블 생성을 생성하는 명령어이다. my_weight은 테이블명에 해당하며, 소괄호 내부는 컬럼에 대한 설정이다. AUTOINCREMENT(2번 라인)는 단어의 의미에서 예상할 수 있듯이 해당 컬럼의 값이 자동으로 증가하도록 하는 키워드인데, id 컬럼이 PRIMARY KEY로 지정되었으므로, AUTOINCREMENT를 사용하여 각 행에 대한 고유 식별자가 중복 없이 생성되도록 했다.
- BEGIN TRANSACTION은 트랜잭션을 사용하겠다고 선언하는 것이다. 오류 없이 데이터 추가에 성공했을 경우 COMMIT(13번 라인)을 실행하여 DB에 반영하고, 오류가 발생했을 경우 오류의 종류에 따라 자동으로 ROLLBACK이 되는 열할을 한다. 자동 롤백은 특정 몇 개의 오류에 대해서만 처리되는데, SQLITE_FULL(저장 공간 가득 참), SQLITE_IOERR(디스크 I/O 오류), SQLITE_BUSY(다른 프로세스가 해당 DB 사용 중), SQLITE_NOMEM(메모리 부족)이 그것이다.
- INSERT INTO VALUES는 데이터를 DB에 추가하는 명령어이다. 조금만 살펴보면 명령어 구조를 파악하는 데 어렵지 않을 것이다.
- -- 표시는 SQL의 주석문을 나타낸다.
파일 이름을 적당히 정하고 .sql 확장자를 붙여서 저장한 뒤, 앞서 설명한 execute 커맨드를 입력해 보면 sql 문서에 입력한 데이터들이 웹 대시보드에서도 정상적으로 잘 표시되는 것을 확인할 수 있다.
대량의 데이터를 입력해야 하는 경우라면 타 프로그래밍 언어들을 이용해서 sql 문서 작성 자체를 자동화하면 된다. 참고로 입력하는 데이터의 양은 한 번에 1000개 이내가 안전한 범위라고 하니 그보다 많은 경우 적절히 나누는 것을 고려해 보자.