Drizzle와 D1 시작하기

This guide assumes familiarity with:

dotenv - 환경 변수를 관리하기 위한 패키지 - 여기서 읽기
tsx - TypeScript 파일을 실행하기 위한 패키지 - 여기서 읽기
Cloudflare D1 - Workers 및 Pages 프로젝트에서 쿼리할 수 있는 서버리스 SQL 데이터베이스 - 여기서 읽기
wrangler - Cloudflare 개발자 플랫폼 커맨드라인 인터페이스 - 여기서 읽기

기본 파일 구조

이 프로젝트의 기본 파일 구조입니다. src/db 디렉토리 안에는 schema.ts 파일에 테이블 정의가 있습니다. drizzle 폴더에는 SQL 마이그레이션 파일과 스냅샷이 있습니다.

📦 <project root>
 ├ 📂 drizzle
 ├ 📂 src
 │   ├ 📂 db
 │   │  └ 📜 schema.ts
 │   └ 📜 index.ts
 ├ 📜 .env
 ├ 📜 drizzle.config.ts
 ├ 📜 package.json
 └ 📜 tsconfig.json

1단계 - 필요한 패키지 설치하기

npm

yarn

pnpm

bun

npm i drizzle-orm  dotenv
npm i -D drizzle-kit tsx

yarn add drizzle-orm  dotenv
yarn add -D drizzle-kit tsx

pnpm add drizzle-orm  dotenv
pnpm add -D drizzle-kit tsx

bun add drizzle-orm  dotenv
bun add -D drizzle-kit tsx

2단계 - wrangler.toml 설정하기

D1 데이터베이스를 사용하려면 wrangler.toml 파일이 필요합니다. 이 파일은 다음과 같이 구성됩니다:

name = "여러분의 프로젝트 이름"
main = "src/index.ts"
compatibility_date = "2022-11-07"
node_compat = true

[[ d1_databases ]]
binding = "DB"
database_name = "여러분의 DB 이름"
database_id = "여러분의 DB ID"
migrations_dir = "drizzle"

3단계 - Drizzle ORM을 데이터베이스에 연결하기

import { drizzle } from 'drizzle-orm/d1';

export interface Env {
  DB: D1Database;
}

export default {
  async fetch(request: Request, env: Env) {
    const db = drizzle(env.DB);
  },
};

위 코드는 Drizzle ORM을 사용하여 데이터베이스에 연결하는 기본적인 설정을 보여줍니다. Env 인터페이스는 D1Database 타입의 DB 속성을 정의하며, 이는 데이터베이스 연결을 위한 환경 변수를 나타냅니다. fetch 함수 내에서 drizzle 함수를 사용하여 데이터베이스 연결을 초기화합니다. 이렇게 하면 여러분의 애플리케이션에서 데이터베이스와 상호작용할 준비가 됩니다.

4단계 - 테이블 생성

src/db 디렉토리에 schema.ts 파일을 생성하고 테이블을 선언해 보겠습니다. 아래 코드는 users_table이라는 테이블을 정의하며, 각 컬럼의 타입과 제약 조건을 설정합니다.

import { int, sqliteTable, text } from "drizzle-orm/sqlite-core";

export const usersTable = sqliteTable("users_table", {
  id: int().primaryKey({ autoIncrement: true }), // 자동 증가하는 기본 키
  name: text().notNull(),                        // 이름 (필수 값)
  age: int().notNull(),                          // 나이 (필수 값)
  email: text().notNull().unique(),              // 이메일 (필수 값, 고유 값)
});

이 코드는 drizzle-orm 라이브러리를 사용하여 SQLite 데이터베이스의 테이블 스키마를 정의합니다. 각 컬럼은 타입과 제약 조건을 가지며, id는 자동 증가하는 기본 키로 설정됩니다.

5단계 - Drizzle 설정 파일 설정하기

Drizzle 설정 파일은 Drizzle Kit에서 사용하는 설정 파일로, 데이터베이스 연결 정보, 마이그레이션 폴더, 스키마 파일 등에 대한 모든 정보를 포함합니다.

프로젝트 루트에 drizzle.config.ts 파일을 생성하고 다음 내용을 추가하세요:

import 'dotenv/config';
import { defineConfig } from 'drizzle-kit';

export default defineConfig({
  out: './drizzle',
  schema: './src/db/schema.ts',
  dialect: 'sqlite',
  driver: '',
  dbCredentials: {
    accountId: process.env.CLOUDFLARE_ACCOUNT_ID!,
    databaseId: process.env.CLOUDFLARE_DATABASE_ID!,
    token: process.env.CLOUDFLARE_D1_TOKEN!,
  },
});

팁

CloudFlare에서 환경 변수를 가져오는 방법은 우리 튜토리얼을 참고하세요.

6단계 - 데이터베이스에 변경 사항 적용하기

drizzle-kit push 커맨드를 사용하면 데이터베이스에 직접 변경 사항을 적용할 수 있습니다. 이 방법은 로컬 개발 환경에서 새로운 스키마 디자인이나 수정 사항을 빠르게 테스트할 때 유용합니다. 마이그레이션 파일을 관리할 필요 없이 빠르게 반복 작업을 진행할 수 있습니다:

npx drizzle-kit push

push 커맨드에 대해 더 알아보려면 문서를 참고하세요.

팁

또는 drizzle-kit generate 커맨드로 마이그레이션을 생성한 후, drizzle-kit migrate 커맨드로 적용할 수도 있습니다:

마이그레이션 생성:

npx drizzle-kit generate

마이그레이션 적용:

npx drizzle-kit migrate

마이그레이션 프로세스에 대해 더 알아보려면 문서를 참고하세요.

// 데이터베이스 변경 사항을 적용하는 컴포넌트
function ApplyChanges() {
  const handleApplyChanges = async () => {
    try {
      // 데이터베이스 업데이트 요청
      const response = await fetch('/api/apply-changes', {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({ changes: 'your_changes_here' }),
      });

      if (!response.ok) {
        throw new Error('변경 사항 적용 실패');
      }

      console.log('변경 사항이 성공적으로 적용되었습니다.');
    } catch (error) {
      console.error('오류 발생:', error);
    }
  };

  return (
    <button onClick={handleApplyChanges}>
      변경 사항 적용
    </button>
  );
}

7단계 - 데이터베이스 시드 및 쿼리

import { drizzle } from 'drizzle-orm/d1';

export interface Env {
  DB: D1Database;
}

export default {
  async fetch(request: Request, env: Env) {
    const db = drizzle(env.DB);
    const result = await db.select().from(users).all();
    return Response.json(result);
  },
};

8단계 - index.ts 파일 실행하기

TypeScript 파일을 실행하는 방법은 여러 가지가 있지만, 여기서는 tsx를 사용하는 방법을 살펴보겠습니다.

이미 tsx를 설치했으므로, 이제 쿼리를 실행할 수 있습니다.

index.ts 스크립트 실행하기

<Npx>
  tsx src/index.ts
</Npx>

팁

TypeScript 파일을 실행할 때 bun을 사용하는 것을 추천합니다. bun을 사용하면 프로젝트가 CommonJS(CJS), ECMAScript Modules(ESM) 또는 다른 모듈 형식으로 구성되어 있더라도 추가 설정 없이 스크립트를 실행할 수 있습니다. bun으로 스크립트를 실행하려면 다음 명령어를 사용하세요:

bun src/index.ts

만약 bun이 설치되어 있지 않다면, Bun 설치 문서를 참고하세요.