Molayo

© 2026 Molayo

Dev.to헤드라인2026. 05. 26. 12:02

Prisma-7 완전 초보자 가이드 (무료 클라우드 데이터베이스 포함!)

요약

Prisma 7의 핵심 개념과 새로운 기능을 소개하는 초보자용 가이드입니다. ORM의 역할부터 Prisma 7에서 도입된 드라이버 어댑터, ESM 우선 지원, 그리고 명령어 한 줄로 무료 클라우드 데이터베이스를 생성하는 방법까지 단계별로 안내합니다.

핵심 포인트

  • Prisma는 TypeScript 타입 안전성을 보장하는 ORM입니다.
  • Prisma 7은 드라이버 어댑터 적용을 통해 성능과 엣지 런타임을 지원합니다.
  • npx create-db 명령어로 무료 클라우드 DB를 즉시 생성할 수 있습니다.
  • 새로운 prisma.config.ts 파일과 ESM 우선 정책이 도입되었습니다.

데이터베이스 경험이 전혀 없어도 괜찮습니다. 이 가이드는 Prisma가 무엇인지, 어떻게 작동하는지, 어떻게 몇 초 만에 무료 클라우드 데이터베이스를 확보하는지, 그리고 어떻게 첫 번째 쿼리 (Query)를 작성하는지까지 모든 과정을 안내합니다.

Prisma란 무엇인가?

Node.js 앱에서 데이터베이스와 통신하려고 시도해 본 적이 있다면, 그 과정이 얼마나 지저분해질 수 있는지 알고 있을 것입니다. 생 SQL (Raw SQL) 문자열을 작성하고, 오타가 없기를 기도하며, TypeScript의 도움을 전혀 받지 못하죠. 그것은 과거의 방식입니다.

Prisma는 ORM (Object-Relational Mapper)입니다. ORM은 기본적으로 여러분의 JavaScript/TypeScript 코드와 데이터베이스 사이의 가교 역할을 합니다. 다음과 같이 SQL을 작성하는 대신:
SELECT * FROM users WHERE id = 1;

다음과 같이 깔끔한 TypeScript를 작성할 수 있습니다:
const user = await prisma.user.findUnique({ where: { id: 1 } });

그러면 Prisma가 여러분을 대신해 SQL을 처리합니다. 또한 Prisma는 완벽한 TypeScript 자동 완성 (Autocomplete) 기능을 제공합니다. 따라서 에디터가 user에 어떤 필드가 있는지, 그 타입은 무엇인지 알고 있으며, 실수를 하면 경고를 보내줍니다.

Prisma는 세 가지 주요 부분으로 구성됩니다:

  • Prisma ORM — 핵심 라이브러리입니다. 스키마 (Schema)를 읽고 TypeScript로 데이터베이스를 쿼리할 수 있게 해줍니다.
  • Prisma Client — 쿼리를 실행하기 위해 앱에서 실제로 임포트 (Import)하는, 자동 생성된 타입 안전 (Type-safe) 코드입니다.
  • Prisma Studio — 코드를 작성하지 않고도 데이터베이스 데이터를 확인하고 편집할 수 있는 시각적인 브라우저 기반 UI입니다.

Prisma 7에서 무엇이 바뀌었나요?

Prisma 7 (2025년 11월 출시)은 몇 가지 중요한 변화를 도입했습니다:

  • 드라이버 어댑터 (Driver adapters) 필수 적용. 이전 버전에서는 Prisma가 데이터베이스에 직접 연결했습니다. 이제는 PrismaClient에 "드라이버 어댑터" (PostgreSQL의 경우 @prisma/adapter-pg와 같은 형태)를 전달해야 합니다. 이를 통해 더 나은 성능과 엣지 런타임 (edge runtime) 지원을 제공합니다.
  • 새로운 prisma.config.ts 파일 — 이전에는 모든 설정이 schema.prisma 내부에 있었습니다. 이제는 별도의 TypeScript 설정 파일이 존재합니다.
  • ESM 우선 (ESM first) — Prisma 7은 ES 모듈 (ES Modules, 현대적인 JavaScript 모듈 시스템)을 우선적으로 사용합니다.
  • 명령어 한 줄로 무료 클라우드 데이터베이스 생성 — 이제 npx create-db (또는 pnpm dlx create-db)를 실행하면 계정 생성 없이도 몇 초 만에 실제 호스팅된 PostgreSQL 데이터베이스를 얻을 수 있습니다.

걱정하지 마세요 — 이 가이드에서 이 모든 과정을 단계별로 다룹니다.

사전 요구 사항 (Prerequisites)

다음이 필요합니다:

  • Node.js 18+ 설치 — nodejs.org에서 다운로드하세요.
  • npm 또는 pnpm — npm은 Node.js와 함께 제공됩니다. pnpm을 설치하려면: npm install -g pnpm을 실행하세요.
  • 코드 에디터 (VS Code 권장)

이것으로 끝입니다. PostgreSQL을 로컬에 설치할 필요는 없습니다. Prisma가 무료 클라우드 데이터베이스를 제공할 것입니다.

파트 1: 옵션 A — 무료 클라우드 데이터베이스 가져오기 (초보자 권장)

이것이 가장 쉬운 방법입니다. Prisma는 단 한 번의 명령어로 생성할 수 있는 무료 호스팅 PostgreSQL 데이터베이스를 제공합니다 — 가입도, 신용카드 등록도 필요 없습니다.

작동 방식

npx create-db (또는 pnpm dlx create-db)를 실행하면 Prisma가 다음을 수행합니다:

  1. 클라우드에 실제 PostgreSQL 데이터베이스를 프로비저닝 (Provisions) 합니다.
  2. 프로젝트에 붙여넣을 수 있는 연결 문자열 (connection string)을 제공합니다.
  3. 데이터베이스를 무료로 사용할 수 있는 24시간의 유예 기간을 제공합니다.
  4. **클레임 URL (claim URL)**을 보여줍니다 — 이 URL을 클릭하면 데이터베이스를 영구적으로 무료로 유지할 수 있습니다 (무료 Prisma 계정 필요).

시승 (test drive)과 같다고 생각하세요. 24시간 동안 무료로 사용해 볼 수 있습니다. 계속 사용하고 싶다면 클레임(claim)을 하세요. 그러면 Prisma의 관대한 무료 티어 (free tier)를 통해 계속 무료로 유지됩니다.

1단계: 새 프로젝트 생성하기

터미널을 열고 다음을 실행하세요:

mkdir hello-prisma
cd hello-prisma

이제 Node.js TypeScript 프로젝트를 초기화합니다:

npm:


이제 Node.js TypeScript 프로젝트를 초기화합니다:

**npm:**

```bash
`npm init -y   npm install typescript tsx @types/node --save-dev   npx tsc --init``

**pnpm:**

```bash
pnpm init   pnpm add typescript tsx @types/node --save-dev   pnpm dlx tsc --init``

### 2단계: Prisma 및 종속성 설치 (Install Prisma and Its Dependencies)

**npm:**

```bash
`npm install prisma @types/pg --save-dev   npm install @prisma/client @prisma/adapter-pg pg dotenv``

**pnpm:**

```bash
pnpm add prisma @types/pg --save-dev   pnpm add @prisma/client @prisma/adapter-pg pg dotenv``

| 패키지 | 역할 | 
| :--- | :--- | 
| `prisma` | Prisma CLI — `prisma init`, `prisma migrate`, `prisma studio`와 같은 명령 실행 |
| ... | 
### 3단계: ESM 지원 구성 (Configure ESM Support)

Prisma 7은 최신 ES Modules를 사용합니다. 프로젝트에 이 사실을 알려줘야 합니다.

`tsconfig.json` 파일을 열고 내용을 다음으로 대체합니다:

```json
`{   "compilerOptions": {   "module": "ESNext",   "moduleResolution": "bundler",   "target": "ES2023",   "strict": true,   "esModuleInterop": true,   "ignoreDeprecations": "6.0"   }   }`

그런 다음 package.json을 열고 그 안에 `

prisma.config.ts란 무엇인가요? 이는 Prisma 7에서 새로 도입된 기능입니다. 이 파일은 Prisma에게 스키마(schema)의 위치, 마이그레이션(migration) 기록을 저장할 위치, 그리고 데이터베이스에 연결하는 방법을 알려줍니다. Prisma를 위한 "설정 파일 (settings file)"이라고 생각하면 됩니다.

5단계: 무료 클라우드 데이터베이스 가져오기

이제 다음 명령어를 실행하여 무료로 호스팅되는 PostgreSQL 데이터베이스를 생성하세요:

npm:

bash

npx create-db

pnpm:

bash

pnpm dlx create-db

터미널에 다음과 같은 출력이 나타납니다:

┌ 🚀 Prisma Postgres 데이터베이스 생성 중 │ │ us-east-1 지역에 임시 데이터베이스를 프로비저닝(Provisioning)하는 중... │ 24시간 후에 자동으로 삭제되지만, 소유권을 주장(claim)할 수 있습니다. │ ◇ 데이터베이스가 성공적으로 생성되었습니다! │ ● 데이터베이스 연결 (Database Connection) │ 연결 문자열 (Connection String): │ postgresql://<username>:<password>@db.prisma.io:5432/postgres │ ◆ 데이터베이스 소유권 주장하기 (Claim your database) → │ │ 데이터베이스를 계속 유지하고 싶으신가요? 무료로 소유권을 주장하세요: │ https://create-db.prisma.io?projectID=proj_... │ │ 소유권을 주장하지 않으면 데이터베이스가 [날짜]에 삭제됩니다. └

해당 연결 문자열 (connection string)을 복사하여 .env 파일에 붙여넣으세요:

DATABASE_URL="postgresql://<username>:<password>@db.prisma.io:5432/postgres"

무료 데이터베이스 소유권을 주장하는 방법 (영구 보관)

  1. 터미널 출력에서 **소유권 주장 URL (claim URL)**을 복사합니다 (예: https://create-db.prisma.io?projectID=proj_... 형태).
  2. 브라우저에서 해당 URL을 엽니다.
  3. Google 또는 GitHub로 로그인합니다 (무료 Prisma Data Platform 계정이 생성됩니다).
  4. 워크스페이스(workspace)를 선택하고 Claim을 클릭합니다.

이제 끝났습니다. 여러분의 데이터베이스는 Prisma의 무료 티어(free tier)에서 영구적으로 소유하게 됩니다. 신용카드는 필요하지 않습니다.

파트 1: 옵션 B — 본인의 PostgreSQL 데이터베이스 사용하기

이미 실행 중인 PostgreSQL 데이터베이스(로컬 또는 Supabase, Railway, Neon 등의 서비스)가 있다면, 대신 이 경로를 사용하세요.

1~4단계: 옵션 A와 동일

위의 1~4단계를 따르되, Prisma를 초기화할 때 --datasource-provider postgresql을 추가하세요:

npm:

bash

npx prisma init --datasource-provider postgresql --output ../generated/prisma

pnpm:

bash

pnpm dlx prisma init --datasource-provider postgresql --output ../generated/prisma

Step 5: 데이터베이스 URL 추가하기

npx create-db는 건너뛰세요. 대신, .env 파일을 열고 본인의 연결 문자열 (connection string)을 붙여넣으세요:

DATABASE_URL="postgresql://username:password@localhost:5432/mydb?schema=public"

다음 부분들을 실제 정보로 교체하세요:

Placeholder교체할 내용
username본인의 PostgreSQL 사용자 이름 (보통 postgres)
...

Supabase를 사용하시나요? Supabase 프로젝트 → Settings → Database → Connection String (URI mode)으로 이동하세요. 해당 문자열을 복사하여 붙여넣으세요.

Neon을 사용하시나요? Neon 대시보드 → Connection Details로 이동하여 연결 문자열을 붙여넣으세요.

Part 2: 데이터 모델 정의하기

이제 Prisma에게 데이터베이스가 어떤 모습이어야 하는지 알려줄 차례입니다. prisma/schema.prisma 파일을 여세요.

이미 기본적인 보일러플레이트 (boilerplate) 코드가 작성되어 있을 것입니다. 파일 하단에 모델 (models)을 추가하세요:

prisma

generator client { provider = "prisma-client" output = "../generated/prisma" }

datasource db { provider = "postgresql" }

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

model Post { id Int @id @default(autoincrement()) title String content String? published Boolean @default(false) author User @relation(fields: [authorId], references: [id]) authorId Int }

이것은 무엇을 의미하나요?

각 model을 하나의 **데이터베이스 테이블 (database table)**이라고 생각하세요. User 모델을 분석해 보겠습니다:

  • id Int @id @default(autoincrement()) — 자동으로 증가하는 숫자 (1, 2, 3...). 이는 각 사용자를 고유하게 식별하는 기본 키 (primary key)입니다.
  • email String @unique — 모든 사용자 사이에서 고유해야 하는 텍스트 필드 (중복 불가).
  • name String? — ?는 이 필드가 **선택 사항 (optional)**임을 의미합니다 (null 허용).
  • posts Post[] — 이 사용자는 여러 개의 게시글을 가질 수 있습니다. 이것은 **관계 (relation)**로, User와 Post를 연결합니다.

Post 모델에서는:

  • author User @relation(...) — 각 게시글은 하나의 User에 속합니다.
  • authorId Int — 관련 사용자의 id를 저장합니다 (외래 키 (foreign key)).

Part 3: 마이그레이션 (Migration)이란 무엇인가?

마이그레이션 명령어를 실행하기 전에, 마이그레이션이 실제로 무엇인지 이해해 봅시다.

마이그레이션의 쉬운 설명

데이터베이스를 하나의 건물이라고 상상해 보세요. 처음 데이터베이스를 만들 때는 빈 땅에서 시작합니다. **마이그레이션 (migration)**은 건축 설계도와 같습니다. 건물에 어떤 변화를 줄 것인지를 설명해 줍니다.

  • 첫 번째 마이그레이션 — "기초를 다지고, 벽을 세우고, 방을 만드세요" (테이블 생성)
  • 두 번째 마이그레이션 — "2층에 새로운 방을 추가하세요" (새로운 컬럼 또는 테이블 추가)
  • 세 번째 마이그레이션 — "거실의 이름을 라운지로 바꾸세요" (필드 이름 변경)

모든 마이그레이션은 파일로 저장됩니다. 이는 다음을 의미합니다:

  • 데이터베이스에 가해진 모든 변경 사항의 전체 이력을 볼 수 있습니다.
  • 이 파일들을 팀원들과 공유할 수 있어, 모두의 데이터베이스가 동일한 상태를 유지하게 할 수 있습니다.
  • 운영 환경 (production)에서 마이그레이션을 다시 실행하여 실제 데이터베이스를 안전하게 업데이트할 수 있습니다.

Prisma는 마이그레이션 파일을 prisma/migrations/ 폴더에 저장합니다. 각 마이그레이션은 타임스탬프가 찍힌 폴더이며, 그 안에 .sql 파일이 들어 있습니다.

첫 번째 마이그레이션 실행하기

npm:

bash

npx prisma migrate dev --name init

pnpm:

bash

pnpm dlx prisma migrate dev --name init

--name init은 이 마이그레이션에 사람이 읽을 수 있는 이름을 붙여주는 것뿐입니다. 변경 사항을 설명하는 이름이라면 무엇이든 사용할 수 있습니다 (예: --name add-user-table 또는 --name add-email-field).

이 명령어는 다음 과정을 수행합니다:

  1. schema.prisma 파일을 확인합니다.
  2. 이를 현재 데이터베이스의 상태와 비교합니다.
  3. 데이터베이스를 스키마 (schema)와 일치시키기 위한 SQL을 생성합니다.
  4. 해당 SQL을 데이터베이스에 적용합니다.
  5. 기록을 위해 마이그레이션 파일을 저장합니다.

migrate dev vs migrate deploy — migrate dev는 개발용 (마이그레이션을 생성하고 적용함)입니다. migrate deploy는 운영 환경용 (이미 존재하는 마이그레이션만 적용함)입니다. 운영 환경에서 절대 migrate dev를 실행하지 마세요.

Prisma Client 생성하기

마이그레이션(Migration)을 마친 후에는 TypeScript 코드가 스키마(Schema)와 동기화될 수 있도록 Prisma Client를 생성해야 합니다.

npm:

npx prisma generate

pnpm:

pnpm dlx prisma generate

이 명령을 실행하면 generated/prisma 폴더에 자동으로 생성된 TypeScript 코드가 만들어집니다. 이 폴더는 직접 수정하지 마세요. prisma generate를 실행할 때마다 Prisma가 해당 폴더를 다시 생성합니다.

파트 4: 코드 내 Prisma Client 설정하기

Prisma 7에서는 클라이언트를 생성할 때 **드라이버 어댑터 (Driver Adapter)**를 설정해야 합니다. lib/prisma.ts 경로에 새 파일을 생성하세요:

import "dotenv/config";
import { PrismaPg } from "@prisma/adapter-pg";
import { PrismaClient } from "../generated/prisma/client";

const connectionString = `${process.env.DATABASE_URL}`;

const adapter = new PrismaPg({ connectionString });
const prisma = new PrismaClient({ adapter });

export { prisma };

드라이버 어댑터 (Driver Adapter)란 무엇인가요?

드라이버 어댑터를 **번역기 (Translator)**라고 생각하면 쉽습니다. Prisma는 내부적으로 자체적인 쿼리 언어를 사용합니다. 어댑터는 이 언어를 PostgreSQL이 이해할 수 있는 언어로 번역해 줍니다. Prisma 7에서는 이 과정이 백그라운드에서 숨겨져 있지 않고 명시적으로 드러나게 되었습니다.

AI 자동 생성 콘텐츠

본 콘텐츠는 Dev.to AI tag의 원문을 AI가 자동으로 요약·번역·분석한 것입니다. 원 저작권은 원저작자에게 있으며, 정확한 내용은 반드시 원문을 확인해 주세요.

원문 바로가기
0

댓글

0