본문으로 바로가기 본문 바로가기
WIKI 기술 지식 베이스

Prisma ORM으로 D1 조회하기

원문 보기 위키 갱신

Prisma ORM ↗︎은 차세대 JavaScript 및 TypeScript ORM으로, 직관적인 데이터 모델, 자동화된 마이그레이션, 타입 안전성(type-safety), 자동 완성(auto-completion) 덕분에 데이터베이스를 다룰 때 한 단계 더 높은 개발자 경험을 열어 줘요.

Prisma ORM에 대해 더 알아보려면 Prisma 문서 ↗︎를 참고하세요.

이 튜토리얼에서는 처음부터 D1 데이터베이스에 접근하는 Cloudflare Worker를 설정하고 배포하는 방법을 보여 드릴게요.

출처: 문서

본문

빠른 시작 (Quick start)

단계를 건너뛰고 빠르게 시작하고 싶다면 아래 Deploy to Cloudflare를 선택하세요.

Deploy to Cloudflare

이 방식은 GitHub 계정에 저장소를 만들고 애플리케이션을 Cloudflare Workers에 배포해 줘요. Cloudflare Workers에 익숙하고 단계별 안내를 건너뛰고 싶다면 이 옵션을 사용하세요.

Cloudflare Workers가 처음이라면 단계를 직접 따라 하는 편이 좋을 거예요.

사전 준비 (Prerequisites)

1. Cloudflare Worker 만들기

터미널을 열고, Cloudflare의 hello-world ↗︎ 템플릿을 사용해 Cloudflare Worker를 만들려면 다음 명령을 실행하세요.

npm create cloudflare@latest prisma-d1-example -- --type hello-world

터미널에서 프로젝트와 관련된 일련의 질문이 나올 거예요.

  1. TypeScript 사용 여부에 yes라고 답하세요.
  2. Worker 배포 여부에 no라고 답하세요.

2. Prisma ORM 초기화하기

참고

D1은 Prisma ORM v5.12.0 ↗︎부터 지원돼요.

Prisma ORM을 설정하려면 프로젝트 디렉터리로 이동해서 Prisma CLI를 설치하세요.

cd prisma-d1-example

npm i -D prisma

yarn add -D prisma

pnpm add -D prisma

bun add -d prisma

다음으로 Prisma Client 패키지와 D1용 드라이버 어댑터를 설치하세요.

npm i @prisma/client @prisma/adapter-d1

yarn add @prisma/client @prisma/adapter-d1

pnpm add @prisma/client @prisma/adapter-d1

bun add @prisma/client @prisma/adapter-d1

마지막으로 다음 명령으로 Prisma ORM에 필요한 파일들을 부트스트랩하세요.

npx prisma init --datasource-provider sqlite

yarn prisma init --datasource-provider sqlite

pnpm prisma init --datasource-provider sqlite

위 명령은:

  1. Prisma 스키마 ↗︎ 파일을 담은 prisma라는 새 디렉터리를 만든다음,
  2. Prisma CLI가 읽을 환경 변수를 설정하는 데 사용하는 .env 파일을 만들어요.

이 튜토리얼에서는 Prisma ORM과 D1의 연결이 바인딩(binding)을 통해 이뤄지므로 .env 파일이 필요하지 않아요. 다음 단계에서 이 바인딩을 설정하는 방법을 안내할 거예요.

현재 Preview 상태인 드라이버 어댑터 ↗︎ 기능을 사용할 것이므로, generator 블록의 previewFeatures 필드를 통해 이 기능을 명시적으로 활성화해야 해요.

schema.prisma 파일을 열고 generator 블록을 다음과 같이 수정하세요.

generator client {
  provider        = "prisma-client-js"
  output          = "../src/generated/prisma"
  previewFeatures = ["driverAdapters"]
}

3. D1 데이터베이스 만들기

이 단계에서는 D1 데이터베이스를 설정할 거예요. Cloudflare 대시보드 ↗︎나 wrangler를 통해 D1 데이터베이스를 만들 수 있어요. 이 튜토리얼에서는 wrangler CLI를 사용할 거예요.

터미널을 열고 다음 명령을 실행하세요.

npx wrangler d1 create prisma-demo-db

터미널에서 다음과 같은 출력이 나와야 해요.

✅ Successfully created DB 'prisma-demo-db' in region WEUR
Created your new D1 database.

{
  "d1_databases": [
    {
      "binding": "DB",
      "database_name": "prisma-demo-db",
      "database_id": "<D1_DATABASE_ID>"
    }
  ]
}

이제 Cloudflare 계정에 Cloudflare Worker에 대한 바인딩을 가진 D1 데이터베이스가 생겼어요.

명령 출력의 마지막 부분을 복사해서 Wrangler 파일에 붙여 넣으세요. 대략 다음과 같이 되어야 해요.

{
	"$schema": "./node_modules/wrangler/config-schema.json",
	"name": "prisma-d1-example",
	"main": "src/index.ts",
	// Set this to today's date
	"compatibility_date": "2026-10-07",
	"compatibility_flags": [
		"nodejs_compat"
	],
	"observability": {
		"enabled": true
	},
	"d1_databases": [
		{
			"binding": "DB", // i.e. available in your Worker on env.DB
			"database_name": "prisma-demo-db",
			"database_id": "<D1_DATABASE_ID>"
		}
	]
}

"$schema" = "./node_modules/wrangler/config-schema.json"
name = "prisma-d1-example"
main = "src/index.ts"
# Set this to today's date
compatibility_date = "2026-10-07"
compatibility_flags = [ "nodejs_compat" ]

[observability]
enabled = true

[[d1_databases]]
binding = "DB"
database_name = "prisma-demo-db"
database_id = "<D1_DATABASE_ID>"

<D1_DATABASE_ID>를 여러분의 D1 인스턴스의 데이터베이스 ID로 바꾸세요. 터미널 출력에서 이 ID를 가져오지 못했다면 Cloudflare 대시보드 ↗︎에서 찾거나 터미널에서 npx wrangler d1 info prisma-demo-db를 실행해서 찾을 수 있어요.

다음으로, 데이터베이스에 테이블을 만들어 Prisma ORM으로 D1에 쿼리를 보낼 수 있게 할 거예요.

4. 데이터베이스에 테이블 만들기

Prisma Migrate ↗︎는 아직 D1을 지원하지 않으므로, prisma migrate dev나 prisma db push를 사용하는 기본 마이그레이션 워크플로는 따라 할 수 없어요.

참고

D1용 Prisma Migrate는 현재 Early Access 단계예요. 사용해 보고 싶다면 Prisma 문서 ↗︎의 안내를 따라 하세요.

D1은 스키마 변경 관리에 마이그레이션(migrations)을 사용하며, Prisma CLI는 그러한 업데이트에 필요한 SQL을 생성하는 데 도움을 줄 수 있어요. 아래 단계에서는 두 도구를 모두 사용해서 데이터베이스에 마이그레이션을 만들고 적용할 거예요.

먼저 wrangler로 새 마이그레이션을 만드세요.

npx wrangler d1 migrations create prisma-demo-db create_user_table

migrations라는 새 폴더를 만들 것인지 묻는 질문에 yes라고 답하세요.

이제 이 명령이 migrations라는 새 디렉터리와 그 안에 0001_create_user_table.sql이라는 빈 파일을 만들었어요.

  • prisma-d1-example
    • migrations
      • 0001_create_user_table.sql

다음으로, User 테이블을 만들 SQL 구문을 그 파일에 추가해야 해요.

schema.prisma 파일을 열고 다음 User 모델을 스키마에 추가하세요.

model User {
  id    Int     @id @default(autoincrement())
  email String  @unique
  name  String?
}

이제 터미널에서 다음 명령을 실행해서 위 User 모델과 동등한 User 테이블을 만드는 SQL 구문을 생성하세요.

npx prisma migrate diff --from-empty --to-schema ./prisma/schema.prisma --script --output migrations/0001_create_user_table.sql

npx prisma migrate diff --from-empty --to-schema-datamodel ./prisma/schema.prisma --script --output migrations/0001_create_user_table.sql

이 명령은 앞서 만든 마이그레이션 파일에 새 User 테이블을 만드는 SQL 구문을 저장해요. 그 내용은 다음과 같아요.

-- CreateTable
CREATE TABLE "User" (
    "id" INTEGER NOT NULL PRIMARY KEY AUTOINCREMENT,
    "email" TEXT NOT NULL,
    "name" TEXT
);

-- CreateIndex
CREATE UNIQUE INDEX "User_email_key" ON "User"("email");

Prisma 스키마의 User 모델이 email 필드에 @unique ↗︎ 속성을 사용하기 때문에 email에 UNIQUE INDEX가 생성됐어요.

이제 wrangler d1 migrations apply 명령을 사용해 이 SQL 구문을 D1에 보내야 해요. 이 명령은 두 가지 옵션을 받아요.

  • --local: 로컬 버전의 D1에 대해 구문을 실행해요. 로컬 버전의 D1은 프로젝트의 .wrangler/state 디렉터리에 위치한 SQLite 데이터베이스 파일이에요. 로컬 머신에서 Worker를 개발하고 테스트하고 싶을 때 이 방식을 사용하세요. 자세한 내용은 로컬 개발을 참고하세요.
  • --remote: 원격 버전의 D1에 대해 구문을 실행해요. 이 버전은 배포된 Cloudflare Workers가 사용해요. 자세한 내용은 원격 개발을 참고하세요.

이 튜토리얼에서는 로컬 개발과 원격 개발을 모두 할 거예요. Worker를 로컬에서 테스트한 다음 Worker를 배포할 거예요.

터미널을 열고 두 명령을 모두 실행하세요.

# For the local database
npx wrangler d1 migrations apply prisma-demo-db --local

# For the remote database
npx wrangler d1 migrations apply prisma-demo-db --remote

마이그레이션을 적용할지 확인하는 안내가 나오면 두 번 모두 Yes를 선택하세요.

다음으로 Worker가 실행되면 조회할 수 있는 데이터를 만들어 두세요. 이번에는 SQL 구문을 파일에 저장하지 않고 실행할 거예요.

# For the local database
npx wrangler d1 execute prisma-demo-db --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('jane@prisma.io', 'Jane Doe (Local)');" --local

# For the remote database
npx wrangler d1 execute prisma-demo-db --command "INSERT INTO  \"User\" (\"email\", \"name\") VALUES
('jane@prisma.io', 'Jane Doe (Remote)');" --remote

참고

Unknown arguments: (\email\, \name\)... 같은 오류가 발생한다면, 백슬래시(\\) 대신 백틱(`)으로 큰따옴표를 이스케이프해야 할 수도 있어요.

그러면 Wrangler 명령이 다음과 같이 보일 거예요.

# Escape with ` instead of \
npx wrangler d1 execute prisma-demo-db --command "INSERT INTO  `"User`" (`"email`", `"name`") VALUES
('jane@prisma.io', 'Jane Doe (Local)');" --<FLAG>

5. Worker에서 데이터베이스 조회하기

Prisma ORM으로 Worker에서 데이터베이스를 조회하려면:

  1. Env 인터페이스에 DB를 추가하세요.
  2. PrismaD1 드라이버 어댑터로 PrismaClient를 인스턴스화하세요.
  3. Prisma Client로 쿼리를 보내고 결과를 반환하세요.

src/index.ts를 열고 전체 내용을 다음으로 바꾸세요.

import { PrismaClient } from "./generated/prisma/";
import { PrismaD1 } from "@prisma/adapter-d1";

export default {
	async fetch(request, env, ctx) {
		const adapter = new PrismaD1(env.DB);
		const prisma = new PrismaClient({ adapter });

		const users = await prisma.user.findMany();
		const result = JSON.stringify(users);
		return new Response(result);
	},
};

import { PrismaClient } from './generated/prisma/';
import { PrismaD1 } from '@prisma/adapter-d1';

export interface Env {
	DB: D1Database;
}

export default {
	async fetch(request, env, ctx): Promise<Response> {
		const adapter = new PrismaD1(env.DB);
		const prisma = new PrismaClient({ adapter });

		const users = await prisma.user.findMany();
		const result = JSON.stringify(users);
		return new Response(result);
	},
} satisfies ExportedHandler<Env>;

Worker를 실행하기 전에 다음 명령으로 Prisma Client를 생성하세요.

npx prisma generate

6. Worker를 로컬에서 실행하기

이제 데이터베이스 쿼리가 준비되고 Prisma Client도 생성됐으니 Worker를 로컬에서 실행하세요.

npm run dev

브라우저에서 http://localhost:8787 ↗︎을 열어 데이터베이스 쿼리 결과를 확인하세요.

[{ "id": 1, "email": "jane@prisma.io", "name": "Jane Doe (Local)" }]

7. Worker 배포하기

Worker를 배포하려면 다음 명령을 실행하세요.

npm run deploy

https://prisma-d1-example.USERNAME.workers.dev에서 여러분의 Worker에 접근하세요. 브라우저에 원격 D1 데이터베이스에서 조회한 다음 데이터가 표시되어야 해요.

[{ "id": 1, "email": "jane@prisma.io", "name": "Jane Doe (Remote)" }]

이 튜토리얼을 마치면서 D1을 데이터베이스로 사용하고 Prisma ORM으로 조회하는 Cloudflare Worker를 배포했어요.

더 알아보기 (Learn more)