[플젝기록] Next.js + Prisma + PlanetScale 세팅하기 (Vercel 배포)

이 글은 단순히 세팅만을 위한 글이지 내부적인 로직이나 스키마 등에 대한 설명이 전혀 포함되어 있지 않으며, 어떠한 프로그래밍적인 기능 구현 역시 다루지 않는다.

PlanetScale의 https://planetscale.com/blog/how-to-setup-next-js-with-prisma-and-planetscale 글에 기초한 내용이며 해당 글의 동영상 버전(링크) 도 참조했다. 

How to set up Next.js with Prisma and PlanetScale

 

1. PlanetScale 가입 / 로그인 후 Create New Database를 통해서 새로운 DB 생성 

Organization 별로 1개의 DB가 무료로 제공된다. 만약 이미 1개를 사용하고 있다면 새로운 organization을 생성한 후에 DB를 생성하면 된다. 

내가 설정하고자 하는 DB의 이름은 blog이고 튜토리얼을 들을 때 Region의 경우 latency 때문에 가까운 곳으로 설정하라고 해서 Tokyo로 설정하였다. 
생성 완료되면 대시보드가 뜬다. 

PlanetScale CLI가 설치되어있다면(OS별 설치 방법은 여기서 확인) 명령어를 통해서도 DB생성이 가능하다. 기본 브랜치로 main 브랜치가 생성된다. 

 

2. Next.js 프로젝트 생성

 

3. TailwindCSS 설치

먼저 2번에서 생성한 프로젝트 디렉토리로 이동한 다음 혹은 위의 디렉토리를 자신이 사용하는 코드 에디터에서 열어준 후 아래의 명령어를 하나씩 입력하여 TailwindCSS를 설치한다. 

 

4. Prisma 설치

프로젝트 디렉토리에서 아래의 명령어를 통해 Prisma를 설치한다. 

 

5. Prisma 설정

.env파일에서 DATABASE_URL을 아래와 같이 자신이 생성한 PlanetScale DB 이름을 넣어 수정한다. 

 

6. Prisma Client 설정

prisma > schema.prisma 파일에서 client와 datasource를 업데이트 해준다.
generator client와 datasource db는 아래와 같이 작성해주면 된다.

PlanetScale은 외래키 제약조건을 지원하지 않고 Prisma는 기본적으로 관계 표현 시 외래키를 사용하기 때문에 PlanetScale과 Prisma를 함께 사용할 때 `referentialIntegrity` 속성에 대해 설정을 해주어야 한다고 한다. 

Because PlanetScale doesn’t support foreign key constraints and Prisma defaults to using foreign keys to express relations, we need to set this referentialIntegrity property when using Prisma with PlanetScale.

“Referential integrity is a property of a data set that states that all its references are valid. Referential integrity requires that if one record references another, then the referenced record must exist. For example, if a Post model defines an author, then the author must also exist.“ (Source: Prisma docs)

model 부분은 샘플로 자신이 필요한 항목과 데이터 타입으로 생성해주면 된다. 

 

7. 로컬에서 돌려보기

프로젝트 디렉토리에서 아래의 명령어를 실행시켜 기본 브랜치인 main 브랜치를 로컬의 3309 포트와 연결한다. 꼭 3309 포트일 필요는 없다. 
(만일 1번에서 새로운 organization을 생성하고 DB를 생성하였다면, 아마 pscale이 이전 organization에 연결되어 있을 것이다. 이 경우에는 먼저 `pscale org switch YOUR-ORGANIZATION-NAME-HERE`을 입력하여 현재 연결할 DB가 있는 organization으로 변경해준다. )

PlanetScale의 스키마를 schema.prisma의 파일에 맞추기 위해 아래의 명령어를 실행한다. 

schema.prisma에 작성한 내용이 PlanetScale 스키마에 잘 반영이 되었는가는 아래의 명령어로 확인이 가능하다. 

위에서 작성한 model이 잘 생성된 것을 아래와 같이 확인할 수 있다. (command: describe YOUR-MODEL-NAME; -- query는 세미콜론으로 끝내기!)

 

8. main 브랜치를 production으로 promote하기 

PlanetScale의 브랜치와 관련된 내용에 대해 알고 싶다면 문서를 참조하는 것이 좋다. 

Branching - Documentation - PlanetScale

브랜치의 두 종류에 대해 설명한 내용을 가져와서 번역해보자면 (더보기에서 확인)

PlanetScale provides two types of database branches:

• Development branches — Development branches provide isolated copies of your production database schema where you can make changes, experiment, or run CI. Note, only the schema is copied, not the data.
• Production branches — Production branches are highly available databases intended for production traffic. They are protected from direct schema changes by default and include automated daily backups. To make a change to a production branch, you must create a deploy request.

PlanetScale은 두 가지 종류의 데이터베이스 브랜치를 제공한다:

• 개발(Development) 브랜치 — 개발 브랜치는 변경, 실험 혹은 CI를 실행할 수 있는 운영(production) 데이터베이스 스키마의 독립적인 복사본을 제공한다. 스키마만 복사되는 것이지 데이터가 복사되는 것은 아님을 유의하라. 
• 운영(Production) 브랜치 — 운영 브랜치는 운영 트래픽을 위한 고가용성 데이터베이스이다. 운영 브랜치는 직접적인 스키마 변경으로부터 기본적으로 보호받으며 자동화된 일일 백업이 포함되어있다. 운영 브랜치에 수정사항이 생기면 배포 요청(deploy request)을 생성해야한다. 

아래의 명령어로 main 브랜치를 promote할 수 있다. promote 후에 main 브랜치는 production을 위한 브랜치가 되고 main 브랜치에 대해 직접적인 스키마 변경이 불가능하다. 이 글을 작성하기 전에 테스트 삼아 만들어 본 DB에서 이 브랜치에 대한 개념을 잘 모르고 promote한 상태에서 스키마를 변경하려고 해서 에러로 당황했던 적이 있다. 

이 글에서는 우선 기본 설정을 마치고 배포하는 것에 의의를 두기 때문에 특별히 구현해놓은 내용이 없어 main 브랜치를 promote하지 않고 배포했다. 하지만 promote 하려면 아래의 명령어를 입력하면 된다. 

만일 브랜치를 promote 했는데 스키마를 변경해야한다면? 해결방법은 아래의 글을 통해 확인할 수 있다👇

[플젝기록] PlanetScale branch 변경 및 deploy request (Prisma String의 default 값)

 

9. Production으로 배포하기

처음 데이터베이스를 생성했던 PlanetScale로 접속하여 자신이 만든 DB 프로젝트 대시보드를 보면 Connect 버튼이 보인다. 클릭하면 아래와 같은 화면이 보인다. 

Connect with에서 Prisma를 선택하고 그럼 Database authentication credentials에 Username과 Password가 보여지고 .env에 DATABASE_URL이 보여진다. 배포 시에 환경변수로 사용되기 때문에 잘 메모해둔다. 

여기까지 완료 후에 GitHub 코드저장소에 commit 후 push 해주었다. 

배포는 자신이 편한 곳으로 선택할 수 있다. 이 글에서는 Vercel을 사용하여 배포한다. 

Vercel 사이트에서 가입 / 로그인 진행 후 New Project를 통해 GitHub에 있는 코드저장소를 import 해주는데 여기서 이미 코드저장소 전체가 보이도록 권한 설정을 해둔 분들은 문제 없겠지만 에러가 뜨거나 배포하고자하는 코드저장소가 보이지 않는 경우에는 GitHub에서 권한을 설정해주면 된다. 여기서 그 부분까지는 다루지 않는다. 프로젝트(코드저장소)를 선택하고 Import를 눌러주면 아래와 같은 화면이 뜬다. 

여기서 추가해주어야할 부분은 Environment Variables이다. 바로 전 단계에서 메모해둔 혹은 복사해둔 DATABASE_URL의 값을 환경 변수로 저장해준다. 추가 후 Add를 누르는데 값에는 따옴표를 제거 후 넣어준다. 그리고 Deploy 버튼을 누르면 완료!