App ↔ DB 연동 스펙 — 핵심 개념

이 문서는 DB_SPEC_DEFINITION.md의 기술 스펙을 엔지니어링 배경지식 없이도 이해할 수 있도록 풀어 설명합니다.

목차

1. 전체 그림: 앱은 데이터를 어디에 저장하나?
2. 핵심 구성 요소 소개
3. 로컬 vs 클라우드 — 3계층 환경 모델
4. 데이터 흐름: 앱 → ORM → DB
5. 환경변수: 접속 정보와 설정값 관리
6. 마이그레이션: DB 구조의 버전 관리
7. 안전장치: 운영 데이터 보호
8. 배포: 코드와 DB 변경이 반영되는 과정
9. 헬스체크: DB 연결 상태 확인
10. 한눈에 보는 요약표

1. 전체 그림: 앱은 데이터를 어디에 저장하나?

웹 앱은 사용자가 입력한 정보(회원 정보, 글, 설정 등)를 영구적으로 보관해야 합니다. 이 저장소가 데이터베이스(DB) 이고, 앱과 DB 사이를 연결하는 전체 구조는 다음과 같습니다.

flowchart TB
    User("👤 사용자 (브라우저)")
    App["Next.js 앱<br>요청을 받아 처리"]
    ORM["Prisma ORM<br>프로그래밍 언어 ↔ SQL 변환"]
    DB[("PostgreSQL<br>데이터 저장·조회")]

    User <--->|"HTTP 요청/응답"| App
    App <--->|"데이터 읽기/쓰기"| ORM
    ORM <--->|"SQL 쿼리"| DB

    style User fill:#f3e5f5,stroke:#7b1fa2,color:#4a148c
    style App fill:#e3f2fd,stroke:#1565c0,color:#0d47a1
    style ORM fill:#fff3e0,stroke:#ef6c00,color:#e65100
    style DB fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20

각 계층이 담당하는 역할이 명확히 분리되어 있습니다. 하나씩 설명합니다.