From 8560d530702d7ac36d451764c729b298df0581d6 Mon Sep 17 00:00:00 2001 From: skgndi12 Date: Fri, 20 Oct 2023 00:19:53 +0900 Subject: [PATCH] FIXUP: add initial `README` for API project --- api/README.md | 120 ++++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 97 insertions(+), 23 deletions(-) diff --git a/api/README.md b/api/README.md index 744d51d73..2faf1cc10 100644 --- a/api/README.md +++ b/api/README.md @@ -1,11 +1,17 @@ -# 목차 -- [목차](#목차) +목차 - [개요](#개요) - [로컬 인프라 설정](#로컬-인프라-설정) - [DB 설정](#db-설정) - [명령어 설명](#명령어-설명) - - [마이그레이션 파일 생성](#마이그레이션-파일-생성) - - [마이그레이션 진행](#마이그레이션-진행) + - [마이그레이션](#마이그레이션) + - [1. 스키마 편집](#1-스키마-편집) + - [2. 환경 변수 로드](#2-환경-변수-로드) + - [3. 마이그레이션 롤백 파일 생성](#3-마이그레이션-롤백-파일-생성) + - [4. 마이그레이션 파일 생성](#4-마이그레이션-파일-생성) + - [5. 마이그레이션 적용](#5-마이그레이션-적용) + - [6. 마이그레이션 롤백](#6-마이그레이션-롤백) + - [마이그레이션 내용 확인](#마이그레이션-내용-확인) + - [마이그레이션 실패시 대처](#마이그레이션-실패시-대처) - [서버 실행](#서버-실행) - [테스트](#테스트) @@ -13,50 +19,118 @@ `Mr.C`의 API를 담당하는 프로젝트입니다. 이 프로젝트는 `Mr.C` 서비스의 백엔드를 구축하고 관리하는 역할을 합니다. # 로컬 인프라 설정 -1. `api/docker` 폴더로 이동. - ```bash - cd api/docker - ``` +Docker 관련 모든 명령어는 `api` 폴더에서 실행하도록 합니다. -2. Docker image 다운로드 +1. Docker image 다운로드 ```bash docker-compose pull # 이미지 다운로드 ``` -3. Docker container 생성 및 실행 +2. Docker container 생성 및 실행 ```bash - docker-compose up -d # 컨테이너를 백그라운드에 생성 및 실행 + docker-compose --env-file .env -p mrc-api up -d # 컨테이너를 백그라운드에 생성 및 실행 ``` -4. Docker container 정지 및 삭제 (모든 인프라 사용이 종료됐을 경우) +3. Docker container 정지 및 삭제 (모든 인프라 사용이 종료됐을 경우) ```bash - docker-compose down # 컨테이너 정지 및 삭제 + docker-compose -p mrc-api down # 컨테이너 정지 및 삭제 ``` # DB 설정 ## 명령어 설명 ```bash -npm run migrate-dev # 마이그레이션 파일 생성 -npm run migrate-deploy # DB 마이그레이션 진행 +npm run migrage-create:down # 마이그레이션 롤백 파일 생성 +npm run migrate-create:up # 마이그레이션 파일 생성 +npm run migrate-apply:rollback # 마이그레이션 롤백 +npm run migrate-apply:all # 모든 마이그레이션 적용 및 ORM 클라이언트 타입 갱신 +npm run migrate-apply:latest # 아직 적용되지 않은 마이그레이션만 적용 npm run migrate-status # 마이그레이션 상태 확인 -npm run generate-models # ORM 클라이언트에 스키마 변동사항 적용 +npm run generate-models # ORM 클라이언트 타입 갱신 npm run studio # DB GUI 실행 ``` -## 마이그레이션 파일 생성 -`schema.prisma` 파일의 내용이 수정됐을 경우 `npm run migrate-dev` 명령어를 통해 마이그레이션 파일을 생성합니다. -## 마이그레이션 진행 -1. `npm run migrate-deploy` 실행하여 DB 에 마이그레이션 진행. -2. `npm run generate-models`을 통해 ORM 에 스키마 변동 사항 적용. -3. `npm run migrate-status` 또는 `npm run studio` 를 통해 마이그레이션 확인. + +## 마이그레이션 +로컬에서 마이그레이션을 하는 경우 먼저 [로컬 인프라 설정](#로컬-인프라-설정) 의 과정을 완료합니다. + +### 1. 스키마 편집 +`prisma/schema.prisma` 파일의 내용을 편집합니다. + +### 2. 환경 변수 로드 +`scripts` 폴더로 이동해서 `load_dotenv.sh` 스크립트를 다음의 명령어로 실행시켜 쉘에 환경 변수를 로드합니다. + +```bash +. ./load_dotenv.sh +``` + +> [!NOTE] +> 올바르게 환경 변수가 로드 되지 않았을 경우, 마이그레이션의 다음 과정에서 문제가 생길 수 있습니다. 따라서 `printenv` 명령어를 통해 환경 변수의 값이 쉘에 제대로 로드 되었는지 먼저 확인하도록 합니다. + + +### 3. 마이그레이션 롤백 파일 생성 +`npm run migrate-create:down` 명령어를 실행시켜 마이그레이션 롤백 파일을 생성합니다. 명령어를 통해 생성된 `down.sql` 파일은 이후 [4.마이그레이션 파일 생성](#4-마이그레이션-파일-생성) 과정을 마친 후 생성된 폴더로 이동시킵니다. + +> [!NOTE] +> 마이그레이션 롤백 파일을 만들기전에 마이그레이션 파일을 생성하면 히스토리가 갱신되기 때문에 롤백 파일이 제대로 생성되지 않을 수 있습니다. 따라서 반드시 마이그레이션 파일을 생성하기 전에 롤백 파일을 먼저 생성하도록 합니다. + + +### 4. 마이그레이션 파일 생성 +`npm run migrate-create:up` 명령어를 실행시켜 마이그레이션 파일을 생성합니다. + +> [!IMPORTANT] +> `npm run migrate-create:up` 명령어는 `migrations` 폴더의 내용과 타깃 데이터베이스의 상태가 다르면 데이터베이스의 리셋을 다음과 같이 유도할 수 있습니다. 아래와 같이 선택지가 나타날 경우, [공식 문서](https://www.prisma.io/docs/guides/migrate/developing-with-prisma-migrate/troubleshooting-development)를 참고하여 대처하도록 합니다. +``` +❯ npm run migrate-create:up + +> mrc-api@0.0.1 migrate-create:up +> npx prisma migrate dev --create-only + +Environment variables loaded from .env +Prisma schema loaded from prisma/schema.prisma +Datasource "db": PostgreSQL database "mrc", schema "public" at "localhost:5432" + +The following migration(s) are applied to the database but missing from the local migrations directory: 20231017093120_add_profile_user +✔ We need to reset the "public" schema at "localhost:5432" +Do you want to continue? All data will be lost. +``` + + +### 5. 마이그레이션 적용 +마이그레이션 적용은 상황에 따라 다를 수 있습니다. + +**Case 1: 모든 마이그레이션 적용** +모든 마이그레이션들이 DB 에 적용되어야 한다면 `npm run migrate-apply:all` 명령어를 실행시킵니다. 해당 명령어를 실행시킨다면 현재 `prisma/migrations` 폴더에 작성되어 있는 모든 내용들이 데이터베이스에 반영됩니다. + +> [!IMPORTANT] +> `npm run migrate-apply:all` 명령어는 타깃 데이터베이스의 상태가 현재 모든 마이그레이션이 적용된 데이터베이스의 상태와 다를 경우 리셋을 유도할 수 있습니다. 자세한 내용은 아래 문서에서 확인할 수 있습니다. 따라서 실제 서비스 환경의 데이터베이스에 마이그레이션 할때는 사용을 지양하도록 해야합니다. +- [migrate dev](https://www.prisma.io/docs/reference/api-reference/command-reference#migrate-dev) +- [Detecting schema drift](https://www.prisma.io/docs/concepts/components/prisma-migrate/shadow-database#detecting-schema-drift) + + +**Case 2: 아직 적용되지 않은 마이그레이션만 적용** +이미 존재하는 데이터베이스에 아직 적용되지 않은 마이그레이션만 적용하고자 할때는 `npm run migrate-apply:latest` 명령어를 사용합니다. 이미 적용된 마이그레이션은 스킵하고 적용되지 않은 내용만 적용하기 때문에 실제 서비스 환경에서 사용하기 적합합니다. 실제 서비스 환경에서 처음으로 마이그레이션을 적용한다면 [baselining](https://www.prisma.io/docs/guides/migrate/developing-with-prisma-migrate/baselining) 과정을 마친 후 마이그레이션을 진행하도록 합니다. + + +### 6. 마이그레이션 롤백 +마이그레이션을 롤백을 위해서는 [3.마이그레이션 롤백 파일 생성](#3-마이그레이션-롤백-파일-생성) 의 과정을 통해 생성한 마이그레이션 롤백 파일의 위치를 확인해야합니다. 파일의 위치를 확인하고 나서는 다음과 같이 명령어를 실행합니다. + +```bash +npm run migrate-apply:rollback -- --file $rollback_file +``` + +### 마이그레이션 내용 확인 +`npm run migrate-status` 또는 `npm run studio` 를 통해 마이그레이션 적용 여부를 확인합니다. + +### 마이그레이션 실패시 대처 +마이그레이션이 실패했을시에는 다음의 [문서](https://www.prisma.io/docs/guides/migrate/developing-with-prisma-migrate/troubleshooting-development#schema-drift)를 참고하여 대처하도록 합니다. # 서버 실행 로컬 환경에서 서버를 실행시킬 경우 다음 두 가지를 먼저 확인합니다. 1. [로컬 인프라 설정](#로컬-인프라-설정)에서 로컬 인프라가 올바르게 설정됐는지 확인. -2. [마이그레이션 진행](#마이그레이션-진행)을 통해 변경된 스키마가 DB에 올바르게 반영됐는지 확인. +2. [마이그레이션 진행](#마이그레이션)을 통해 변경된 스키마가 DB에 올바르게 반영됐는지 확인. 두 가지 사항 확인이 됐으면 아래의 과정을 통해 서버를 실행시킵니다.