database

Database Skill

데이터베이스 스키마를 설계하고 안전하게 마이그레이션하는 스킬입니다.

스키마 설계 원칙

정규화 기본

정규형	규칙	예시
1NF	원자값, 반복 그룹 없음	전화번호 배열 → 별도 테이블
2NF	부분 함수 종속 제거	복합 키의 일부에만 의존하는 컬럼 분리
3NF	이행 종속 제거	A→B→C이면 C를 별도 테이블로

명명 규칙

-- 테이블: 복수형, snake_case
CREATE TABLE users (...)
CREATE TABLE order_items (...)

-- 컬럼: snake_case, 의미 명확
user_id, created_at, is_active

-- 인덱스: idx_{table}_{columns}
CREATE INDEX idx_users_email ON users(email);

-- 외래 키: fk_{table}_{ref_table}
CONSTRAINT fk_orders_users FOREIGN KEY (user_id) REFERENCES users(id)

공통 컬럼 패턴

CREATE TABLE users (
    id          BIGSERIAL PRIMARY KEY,
    -- 비즈니스 컬럼
    name        VARCHAR(255) NOT NULL,
    email       VARCHAR(255) NOT NULL UNIQUE,
    -- 감사 컬럼
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    deleted_at  TIMESTAMPTZ  -- soft delete
);

마이그레이션 관리

마이그레이션 파일 구조

migrations/
├── 000001_create_users.up.sql
├── 000001_create_users.down.sql
├── 000002_add_user_email_index.up.sql
├── 000002_add_user_email_index.down.sql

프로젝트별 넘버링 규칙

• 먼저 소유 repo와 migration directory를 확정합니다. 예: Autopus/backend/migrations, db/migrations, database/migrations.
• 새 migration pair/stem 번호는 해당 directory 안의 기존 *.sql 파일만 기준으로 max(existing_number)+1을 사용합니다. 다른 프로젝트나 workspace root의 번호를 섞지 않습니다.
• 파일명은 {6자리 zero-padded 번호}_{description}.{up,down}.sql 형식을 사용합니다.
• 동일 migration directory에 새 파일을 만드는 작업은 병렬로 번호를 예약하지 않습니다. 여러 task가 같은 directory를 만지면 순차 실행하고, 앞 작업이 merge/rebase된 뒤 다음 번호를 계산합니다.
• .up.sql과 .down.sql은 같은 번호와 같은 stem (same stem)을 사용합니다. 예: 000425_add_table.up.sql ↔ 000425_add_table.down.sql.
• 기존 orphaned migration을 복구하기 위해 missing same-stem counterpart를 추가하는 경우에만 기존 번호 재사용을 허용합니다.
• 배포된/커밋된 기존 migration은 renumber하지 않습니다. 현재 task에서 만든 uncommitted 파일만 이름을 바꿉니다.
• 배포 전 검증은 directory 단위로 수행합니다: unpadded 파일, 중복 번호+stem, orphaned up/down, 같은 번호의 다른 description이 있으면 실패로 처리합니다.