01. Next.js + Prisma + PostgreSQL로 건물 관리 웹 앱 개발 시작하기: 프로젝트 설정 및 DB 구축 🚀

안녕하세요!  회사에 자체적인 서비스를 진행해 건물관리 입찰에서 도움이되면 좋겠어서

'QR 코드로 간편하게 건물 관리하기' 웹 서비스를 Next.js와 Prisma, PostgreSQL을 사용하여 개발하는 여정의 첫 단계를 기록해보려고 합니다. 풀스택에 대한 도전이기도해요..

 

비슷한 스택으로 프로젝트를 시작하시려는 분들께 도움이 되기를 바랍니다.

 

프로젝트 목표:

• 관리자, 중간관리자, 노동자 역할 분담
• 시설 및 점검표 등록/관리
• 시설 QR 코드 생성 및 스캔을 통한 점검 접근
• 노동자 역할 확인 및 PIN 인증 후 점검 수행
• 점검 결과(사진 포함) 기록 및 조회
• (추가) 웹소켓 기반 채팅 기능

기술 스택:

• 프레임워크: Next.js (App Router)
• 데이터베이스: PostgreSQL
• ORM: Prisma
• 배포 (예정): Vercel

개발을 하기전에 밑그림을 먼저 그리고 시작하는 편이예요.
그래서 저는erd와 api명세서 와이어프레임을 작성하고 개발을 시작하구요,개발을 들어갔을때 전체적으로 먼저 폴더구조를 만들고 화면보다는 기능이 먼저 작동되는지 확인한다음 화면을 만드는 순서를 저는 가지고있어요!!
(물론 개발하면서 기능 추가하고 erd도 바뀔수있지만요...)

그렇기에 !!!! db를 일단 만들고 시작해보려고해요 오늘의 포스팅을 그래서

프로젝트 생성부터 데이터베이스 스키마 정의 및 실제 DB 반영까지의 과정을 다룰겁니다!

 

1단계: Next.js 프로젝트 생성

먼저, 프로젝트를 생성할 폴더로 이동한 후, VS Code 터미널에서 다음 명령어를 실행하여 Next.js 프로젝트를 생성합니다.

npx create-next-app@latest building-qr-manager

실행 중 나타나는 질문에는 다음과 같이 답변했습니다. (TypeScript, App Router 사용 권장!)

• Use TypeScript? Yes
• Use ESLint? Yes
• Use Tailwind CSS? Yes
• Use src/ directory? Yes
• Use App Router? Yes
• Customize default import alias? No

설치가 완료되면 프로젝트 폴더로 이동 후 개발 서버를 실행하여 기본 페이지(http://localhost:3000)가 잘 뜨는지 확인합니다.

cd building-qr-manager
npm run dev

 

2단계: 데이터베이스 준비 (로컬 PostgreSQL)

개발 단계에서는 로컬 환경에 PostgreSQL을 설치하여 사용하는 것이 편리합니다.

1. PostgreSQL 설치: 공식 다운로드 페이지에서 OS에 맞게 설치합니다. 설치 중 postgres 사용자의 비밀번호를 설정하게 되는데, 이 비밀번호는 꼭 기억해야 합니다!
2. 데이터베이스 생성: pgAdmin (설치 시 함께 설치했거나 별도 설치 권장) 또는 psql 명령어를 사용하여 프로젝트에서 사용할 데이터베이스를 생성합니다. 여기서는 building_qr_manager (또는 mydb - 환경에 따라 다를 수 있음)라는 이름으로 생성했습니다.
   • (pgAdmin 사용 시) 서버 연결 > Databases 우클릭 > Create > Database... > 이름 입력 후 저장
   • (psql 사용 시) psql -U postgres, 접속 후 CREATE DATABASE building_qr_manager; 실행

3단계: Prisma 연동 및 설정

Prisma는 데이터베이스 작업을 타입 안전하게 도와주는 ORM입니다.

1. Prisma 설치:

2. npm install prisma --save-dev
   npm install @prisma/client

    
3. Prisma 초기화:이 명령은 prisma/schema.prisma 파일과 .env 파일을 생성(또는 업데이트)합니다.

4. npx prisma init

    
5. schema.prisma 설정: prisma/schema.prisma 파일을 열어 datasource db 블록의 provider가 "postgresql"로 되어 있는지 확인합니다.

6. datasource db {
     provider = "postgresql" // 확인!
     url      = env("DATABASE_URL")
   }

4단계: 데이터베이스 연결 정보 설정 (.env)

프로젝트 루트의 .env 파일을 열어 PostgreSQL 연결 정보를 입력합니다. 이 파일은 민감 정보를 담고 있으므로 .gitignore에 반드시 추가하여 Git 저장소에 올라가지 않도록 주의하세요!

# .env

# PostgreSQL 연결 URL 형식: postgresql://USER:PASSWORD@HOST:PORT/DATABASE?schema=public
# 예시 (실제 사용자 이름, 비밀번호, DB 이름으로 변경 필수!)
DATABASE_URL="postgresql://postgres:여기에_설정한_비밀번호@localhost:5432/building_qr_manager?schema=public"

 

⚠️ 주의: USER와 PASSWORD, DATABASE 부분을 실제 로컬 PostgreSQL 설정에 맞게 정확히 수정해야 합니다.

비밀번호 오류 시 P1000 Authentication failed 오류가 발생합니다.

5단계: Prisma 스키마 정의 (1차 - 기본 모델)

prisma/schema.prisma 파일에 ERD를 기반으로 데이터 모델을 정의합니다. 먼저 User와 Facility 모델, 그리고 Role Enum을 정의했습니다.

// prisma/schema.prisma

generator client {
  provider = "prisma-client-js"
}

datasource db {
  provider = "postgresql"
  url      = env("DATABASE_URL")
}

enum Role {
  ADMIN
  MANAGER
  WORKER
}

model User {
  id            Int      @id @default(autoincrement())
  name          String
  email         String   @unique
  passwordHash  String
  phoneNumber   String?
  role          Role     @default(WORKER)
  pinHash       String?
  createdAt     DateTime @default(now())
  updatedAt     DateTime @updatedAt

  // 관계는 나중에 추가
}

model Facility {
  id          Int      @id @default(autoincrement())
  name        String
  description String?
  location    String?
  createdAt   DateTime @default(now())
  updatedAt   DateTime @updatedAt

  // 관계는 나중에 추가
}

 

6단계: 첫 데이터베이스 마이그레이션

정의한 스키마를 실제 데이터베이스에 테이블로 생성하는 마이그레이션을 실행합니다.

npx prisma migrate dev --name init

 

이 명령은 schema.prisma를 분석하여 SQL을 생성하고, 이를 DB에 적용합니다. prisma/migrations 폴더에 마이그레이션 기록이 저장됩니다. 성공 메시지(Your database is now in sync with your schema.)를 확인합니다.

(팁: 만약 P1000 Authentication failed 오류가 발생하면, .env 파일의 DATABASE_URL 정보, 특히 비밀번호를 다시 확인하세요!)

7단계: Prisma 스키마 정의 (2차 - 전체 모델 및 관계)

이제 나머지 모델(Checklist, ChecklistItem, Assignment 등)과 모델 간의 관계(@relation)를 schema.prisma 파일에 모두 정의합니다. 외래 키(Foreign Key), 관계 옵션(onDelete), 제약 조건(@@unique), 인덱스(@@index) 등을 설정합니다.

(전체 스키마 코드는 분량이 길어 생략합니다. 이전 대화 내용을 참고하여 작성된 전체 스키마를 사용하시면 됩니다.)

8단계: 두 번째 데이터베이스 마이그레이션

스키마 변경 사항을 다시 데이터베이스에 적용합니다.

npx prisma migrate dev --name add_relations_and_models

 

성공 메시지를 확인하여 모든 테이블과 관계가 DB에 잘 반영되었는지 확인합니다.

9단계: 최종 확인 (pgAdmin 사용)

우클릭 Properties를 누르고 Columns를 누르면 확인가능해요!

 

pgAdmin을 실행하여 로컬 PostgreSQL 서버에 연결한 후, 해당 데이터베이스 mydb > Schemas > public > Tables 경로로 이동합니다.

여기서 User, Facility, Checklist, ChecklistItem, Assignment, Submission, SubmissionAnswer, ChatMessage 테이블과 Prisma 관리용 _prisma_migrations 테이블이 모두 생성된 것을 확인할 수 있습니다. 각 테이블의 속성(Properties)을 열어 컬럼과 외래 키 제약 조건 등이 잘 설정되었는지 확인하면 더욱 좋습니다.

마무리 및 다음 단계

여기까지 Next.js 프로젝트 생성, PostgreSQL 데이터베이스 준비, Prisma 연동 및 전체 데이터 모델 정의, 그리고 실제 데이터베이스 마이그레이션까지 완료했습니다! 

 

다음 포스팅에서는 사용자 인증 기능 구현을 위해 NextAuth.js를 설정하는 과정을 다뤄볼 예정입니다.

궁금한 점이나 더 좋은 방법이 있다면 댓글로 알려주세요! 😊