TASK-004: 보이지 않는 데이터베이스 기반 만들기

지난 TASK에서는 사용자가 직접 보게 될 화면을 만들었습니다.
눈에 보이는 UI가 생기면 프로젝트가 꽤 앞으로 간 것처럼 느껴집니다. 버튼이 있고, 카드가 있고, 화면 흐름이 보이면 “이제 서비스 같아졌다”는 감각이 생깁니다.

그런데 이번 TASK-004는 정반대에 가까웠습니다.

사용자에게는 거의 보이지 않습니다.
화면도 크게 달라지지 않습니다.
하지만 앞으로 서비스가 실제로 동작하려면 반드시 필요한 데이터베이스 환경을 준비하는 작업이었습니다.

이번에는 로컬에서 Postgres와 Redis를 띄우고, TypeORM 마이그레이션으로 스키마를 적용한 뒤, 서비스가 시작될 때 필요한 기초 데이터(seed data) 를 넣었습니다. 마지막으로 API가 실제 DB에 연결되는지 /health로 확인했습니다.

화면 뒤쪽의 첫 번째 기반

지난 작업이 “사용자에게 무엇을 보여줄 것인가”에 가까웠다면, 이번 작업은 “그 화면이 의존할 데이터는 어디에 안전하게 저장될 것인가”에 가까웠습니다.

UI는 사용자가 바로 알아차립니다.
하지만 DB 작업은 잘 되어 있어도 티가 나지 않습니다.

오히려 제대로 되어 있을 때는 아무 일도 일어나지 않는 것처럼 보입니다.
서비스가 켜지고, API가 응답하고, 필요한 데이터가 조용히 저장되고 읽히는 상태. 그게 이번 TASK에서 만들고 싶었던 상태였습니다.

보이지 않는 곳을 단단하게 만들어야, 사용자에게 보이는 화면도 안정적으로 움직일 수 있습니다.

이번 TASK에서 다룬 범위는 작지만 중요했습니다.

이 표를 정리하면서 생각이 조금 바뀌었습니다.
처음에는 “DB 연결 확인 TASK”라고 가볍게 봤는데, 실제로는 서비스의 바닥을 깔아두는 작업에 가까웠습니다.

TASK-004의 3단계 smoke test

이번 smoke test는 복잡한 기능 검증이 아니었습니다.
작게 나누면 세 단계였습니다.

TASK-004
├─ 1단계: DB·Redis 기동
├─ 2단계: 스키마 적용 + 기초 데이터 입력
└─ 3단계: API에서 DB 연결 확인

첫 번째 단계에서는 로컬 개발에 필요한 Postgres와 Redis 컨테이너를 띄웠습니다.
여기서는 아직 서비스 로직보다 저장소가 정상적으로 준비되는지가 중요했습니다.

두 번째 단계에서는 마이그레이션과 시드를 실행했습니다.
마이그레이션은 데이터베이스에 필요한 구조를 만들고, 시드는 개발 과정에서 바로 확인할 수 있는 기본 데이터를 넣어줍니다.

세 번째 단계에서는 API 서버를 띄운 뒤 /health 응답을 확인했습니다.

{
  "status": "ok",
  "service": "api",
  "db": "connected"
}

여기서 중요한 값은 "db":"connected"였습니다.
이 값이 확인되면 API가 TypeORM을 통해 Postgres에 실제로 연결되고 있다는 뜻입니다.

이번 작업에서 일부러 확인하지 않은 것

이번 TASK에서 욕심을 내면 더 많은 것을 확인할 수도 있었습니다.
로그인 플로우, 모니터 API, UI 연동, worker probe까지 한 번에 보고 싶어질 수 있습니다.

하지만 그렇게 하면 smoke test의 목적이 흐려집니다.

이번에는 데이터베이스 기반이 준비되었는지만 확인했습니다.

이렇게 선을 그어두니 TASK가 훨씬 명확해졌습니다.

이번 TASK의 목적은 기능 완성이 아니라, 다음 기능들이 기대고 설 수 있는 데이터 기반 검증이었습니다.

보이지 않는 작업일수록 성공 기준이 필요합니다

UI 작업은 눈으로 바로 확인할 수 있습니다.
화면이 깨졌는지, 버튼이 눌리는지, 레이아웃이 어색한지 비교적 빨리 보입니다.

하지만 DB 작업은 다릅니다.
겉으로 티가 잘 나지 않습니다. 그래서 성공 기준이 더 필요했습니다.

이번에는 아래 기준으로 TASK를 닫을 수 있었습니다.

• pnpm infra:up으로 Postgres와 Redis가 기동되는지
• pnpm db:migrate가 정상 종료되는지
• pnpm db:seed가 정상 종료되는지
• pnpm dev:apps 이후 API가 정상 부팅되는지
• /health 응답에서 DB 상태가 connected인지

여기서 특히 좋았던 점은 검증 흐름이 짧다는 것이었습니다.
앞으로 DB 관련 문제가 생겼을 때도 이 3단계 smoke test를 다시 돌려보면, 어느 지점에서 문제가 생겼는지 빠르게 좁힐 수 있습니다.

작은 설정 하나가 계속 걸린 순간

작업 중간에 잠깐 막힌 부분도 있었습니다.

DB 자체가 안 뜬 문제는 아니었습니다.
로컬 Postgres는 정상적으로 떠 있었고, compose 기준도 명확했습니다. 문제는 애플리케이션이 DB에 접속할 때 사용하는 연결 정보가 로컬 DB 기준과 맞아야 한다는 점이었습니다.

이번 글에서 이 부분을 크게 다루고 싶지는 않습니다.
다만 남길 점은 있습니다.

로컬 개발 환경의 DB 연결 정보는 로컬 compose 기준과 일치해야 합니다.

이 기준이 맞지 않으면 마이그레이션 단계에서 인증 실패가 날 수 있습니다.
반대로 한 번만 맞춰두면 이후에는 매번 비밀번호를 직접 입력하지 않고도 같은 검증 흐름을 반복할 수 있습니다.

정리하면, 이번에 중요한 것은 특정 도구가 아니라 로컬 DB 기준을 하나로 맞춘 것이었습니다.

local database 기준
├─ Postgres: 애플리케이션 데이터 저장
├─ Redis: 캐시·큐 등 상태 관리 준비
├─ Migration: 테이블 구조 반영
└─ Seed: 개발용 기초 데이터 입력

기초 데이터를 넣는다는 것

seed 작업은 작아 보이지만, 개발 흐름에서는 꽤 중요합니다.

빈 데이터베이스는 깨끗하지만, 개발하기에는 불편합니다.
화면을 확인하려 해도 보여줄 데이터가 없고, API를 테스트하려 해도 비교할 기준이 없습니다.

그래서 이번 TASK에서는 스키마만 만드는 데서 멈추지 않고, 기초 데이터가 들어가는지까지 확인했습니다.

이 단계가 있어야 다음 TASK에서 로그인, 모니터링 API, UI 연동을 확인할 때 매번 수동으로 데이터를 만들지 않아도 됩니다.

제가 이번 작업에서 가장 크게 느낀 부분도 여기에 있었습니다.

데이터베이스를 만든다는 건 단순히 저장소를 켜는 일이 아니라, 다음 개발자가 바로 확인할 수 있는 상태를 준비하는 일이었습니다.

물론 여기서 말하는 다음 개발자는 미래의 저일 가능성이 높습니다.

TASK 종료 전 체크리스트

이번 TASK를 닫기 전에 확인한 항목은 아래와 같았습니다.

• Postgres와 Redis 컨테이너 기동
• TypeORM 마이그레이션 정상 적용
• 기초 데이터 seed 정상 적용
• API 서버 실행
• /health 응답 확인
• 응답에서 "db":"connected" 확인
• 다음 TASK에서 사용할 수 있는 로컬 DB 기반 확보

이 체크리스트를 모두 통과했기 때문에 TASK-004의 목표는 충족됐다고 판단했습니다.

다음 기능들이 기대게 될 바닥

이번 작업은 사용자 입장에서 바로 체감되는 변화는 거의 없습니다.
새로운 화면이 생긴 것도 아니고, 버튼이 추가된 것도 아닙니다.

하지만 앞으로 만들어질 로그인, 모니터 API, UI 연동, worker 작업은 모두 이 기반 위에 올라갑니다.

지난 TASK가 “보이는 화면”이었다면, 이번 TASK는 보이지 않는 데이터 저장 공간이었습니다.
둘 중 하나만 있어서는 서비스가 되기 어렵습니다. 화면은 데이터를 필요로 하고, 데이터는 화면과 API를 통해 의미를 갖습니다.

Build in Public으로 기록하다 보니 이런 작업도 그냥 지나치지 않게 됩니다.
사용자에게 보이는 것과 보이지 않는 것 사이에서 어떤 순서로 기반을 쌓아가는지, 계속 함께 만들어가는 기록으로 남기겠습니다.