5.2. 데이터베이스 설계 규칙

5.2.1. 테이블 네이밍

규칙	예시
소문자 + snake_case	user_profiles
복수형 사용	users, orders
접두사 금지	tbl_users (X) → users (O)
예약어 사용 금지	user (X) → users (O)

5.2.2. 컬럼 네이밍

규칙	예시
소문자 + snake_case	created_at, user_name
테이블명 접두사 금지	user_user_name (X) → user_name (O)
Boolean 컬럼	is_ 또는 has_ 접두사
날짜/시간 컬럼	_at 접미사

5.2.3. 필수 컬럼

모든 테이블에 다음 컬럼을 포함해야 합니다.

컬럼	타입	설명
id	BIGSERIAL 또는 UUID	기본 키
created_at	TIMESTAMP WITH TIME ZONE	생성 시각
updated_at	TIMESTAMP WITH TIME ZONE	수정 시각

CREATE TABLE users (
    id          BIGSERIAL PRIMARY KEY,
    name        VARCHAR(100) NOT NULL,
    email       VARCHAR(255) NOT NULL UNIQUE,
    is_active   BOOLEAN NOT NULL DEFAULT true,
    created_at  TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
    updated_at  TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now()
);

5.2.4. 기본 키 전략

전략	타입	사용 기준
BIGSERIAL	자동 증가 정수	일반적인 비즈니스 엔티티 (기본값)
UUID	uuid	분산 환경, 외부 노출 식별자

UUID 사용 시:

CREATE EXTENSION IF NOT EXISTS "pgcrypto";

CREATE TABLE documents (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    title       VARCHAR(255) NOT NULL,
    created_at  TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now(),
    updated_at  TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT now()
);

5.2.5. 인덱스 네이밍

idx_{테이블명}_{컬럼명}

유형	네이밍	예시
일반 인덱스	idx_{table}_{column}	idx_users_email
복합 인덱스	idx_{table}_{col1}_{col2}	idx_orders_user_id_status
유니크 인덱스	uniq_{table}_{column}	uniq_users_email

CREATE INDEX idx_users_email ON users (email);
CREATE UNIQUE INDEX uniq_users_email ON users (email);
CREATE INDEX idx_orders_user_id_status ON orders (user_id, status);

5.2.6. 외래 키 네이밍

fk_{테이블명}_{참조테이블명}

ALTER TABLE orders
    ADD CONSTRAINT fk_orders_users
    FOREIGN KEY (user_id) REFERENCES users (id);

5.2.7. 금지 사항

금지 항목	사유
복합 기본 키	조인 복잡도 증가, jOOQ 코드 생성 복잡
TEXT 타입 남용	길이 제한 없는 컬럼은 명시적으로 필요한 경우만
FLOAT / DOUBLE	금융 데이터 정밀도 문제 → NUMERIC 사용
예약어 테이블/컬럼명	SQL 호환성 문제
트리거 기반 비즈니스 로직	애플리케이션 레이어에서 처리