kamco-cd-cron/kamco-make-dataset-generation/claudedocs/DATABASE_SETUP.md

데이터베이스 설정 가이드

개요

이 애플리케이션은 PostgreSQL 데이터베이스를 사용하며, 다음 테이블이 필요합니다:

1. Spring Batch 메타데이터 테이블 (자동 생성)
2. batch_history 테이블 (수동 생성 필요)

필수 테이블

1. Spring Batch 메타데이터 테이블

Spring Batch가 자동으로 생성합니다:

• BATCH_JOB_INSTANCE
• BATCH_JOB_EXECUTION
• BATCH_JOB_EXECUTION_PARAMS
• BATCH_STEP_EXECUTION
• BATCH_STEP_EXECUTION_CONTEXT
• BATCH_JOB_EXECUTION_CONTEXT

설정:

spring:
  batch:
    jdbc:
      initialize-schema: always

2. batch_history 테이블 (커스텀)

배치 작업 실행 이력을 저장하는 커스텀 테이블입니다.

용도:

• 배치 작업 시작/종료 시간 기록
• 배치 실행 상태 추적 (STARTED/COMPLETED/FAILED)
• 비즈니스 ID별 배치 이력 관리

새 환경 데이터베이스 초기 설정

Option 1: SQL 스크립트 실행 (권장)

1. batch_history 테이블 생성:

# PostgreSQL에 연결
psql -h [host] -U [username] -d [database]

# schema.sql 실행
\i src/main/resources/sql/schema.sql

또는 직접 SQL 실행:

-- batch_history 테이블 생성
CREATE TABLE IF NOT EXISTS public.batch_history (
    uuid UUID PRIMARY KEY,
    job VARCHAR(255) NOT NULL,
    id VARCHAR(255) NOT NULL,
    created_dttm TIMESTAMP NOT NULL,
    updated_dttm TIMESTAMP NOT NULL,
    status VARCHAR(50) NOT NULL,
    completed_dttm TIMESTAMP
);

-- 인덱스 생성
CREATE INDEX IF NOT EXISTS idx_batch_history_job ON public.batch_history(job);
CREATE INDEX IF NOT EXISTS idx_batch_history_status ON public.batch_history(status);
CREATE INDEX IF NOT EXISTS idx_batch_history_created ON public.batch_history(created_dttm DESC);

2. 권한 설정 (필요한 경우):

-- 애플리케이션 사용자에게 권한 부여
GRANT ALL PRIVILEGES ON TABLE public.batch_history TO [app_user];
GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO [app_user];

Option 2: 자동 초기화 활성화 (개발 환경만)

application-local.yml 또는 application-dev.yml:

spring:
  sql:
    init:
      mode: always
      schema-locations: classpath:sql/schema.sql

주의:

• 운영 환경에서는 mode: never 사용 권장
• 테이블이 이미 존재하면 권한 에러 발생 가능

테이블 구조

batch_history

컬럼명	데이터 타입	NULL	설명
uuid	UUID	NOT NULL	배치 실행 고유 ID (Primary Key)
job	VARCHAR(255)	NOT NULL	배치 작업 이름
id	VARCHAR(255)	NOT NULL	비즈니스 ID
created_dttm	TIMESTAMP	NOT NULL	생성 일시
updated_dttm	TIMESTAMP	NOT NULL	수정 일시
status	VARCHAR(50)	NOT NULL	상태 (STARTED/COMPLETED/FAILED)
completed_dttm	TIMESTAMP	NULL	완료 일시

인덱스:

• idx_batch_history_job: job 컬럼 인덱스
• idx_batch_history_status: status 컬럼 인덱스
• idx_batch_history_created: created_dttm 컬럼 인덱스 (DESC)

환경별 설정

Local 환경

spring:
  datasource:
    url: jdbc:postgresql://localhost:5432/kamco_local
    username: dev_user
    password: dev_password
  sql:
    init:
      mode: always  # 자동 초기화 활성화

Production 환경

spring:
  datasource:
    url: jdbc:postgresql://prod-db:5432/kamco_prod
    username: app_user
    password: ${DB_PASSWORD}
  sql:
    init:
      mode: never  # 자동 초기화 비활성화

트러블슈팅

에러: "must be owner of table batch_history"

원인: 테이블이 이미 존재하지만, 현재 DB 사용자가 owner가 아님

해결:

1. SQL 자동 초기화 비활성화:

spring:
  sql:
    init:
      mode: never

2. 또는 테이블 소유권 변경:

ALTER TABLE public.batch_history OWNER TO [app_user];

에러: "relation batch_history does not exist"

원인: batch_history 테이블이 생성되지 않음

해결:

1. SQL 스크립트 수동 실행:

psql -h [host] -U [user] -d [database] -f src/main/resources/sql/schema.sql

2. 또는 자동 초기화 활성화 (개발 환경만):

spring:
  sql:
    init:
      mode: always
      schema-locations: classpath:sql/schema.sql

에러: "permission denied for schema public"

원인: DB 사용자에게 public 스키마 권한 없음

해결:

GRANT ALL ON SCHEMA public TO [app_user];
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO [app_user];

데이터베이스 마이그레이션

기존 환경에서 테이블 확인

-- batch_history 테이블 존재 확인
SELECT EXISTS (
    SELECT FROM information_schema.tables
    WHERE table_schema = 'public'
    AND table_name = 'batch_history'
);

-- 테이블 구조 확인
\d public.batch_history

-- 인덱스 확인
\di public.idx_batch_history_*

테이블 재생성 (데이터 삭제 주의!)

-- 기존 테이블 삭제 (주의: 모든 데이터 손실!)
DROP TABLE IF EXISTS public.batch_history CASCADE;

-- schema.sql 재실행
\i src/main/resources/sql/schema.sql

백업 및 복구

테이블 백업

pg_dump -h [host] -U [user] -d [database] -t batch_history > batch_history_backup.sql

테이블 복구

psql -h [host] -U [user] -d [database] < batch_history_backup.sql

모니터링 쿼리

최근 배치 실행 이력 조회

SELECT
    uuid,
    job,
    id,
    created_dttm,
    completed_dttm,
    status,
    EXTRACT(EPOCH FROM (completed_dttm - created_dttm)) as duration_seconds
FROM public.batch_history
ORDER BY created_dttm DESC
LIMIT 10;

실패한 배치 조회

SELECT *
FROM public.batch_history
WHERE status = 'FAILED'
ORDER BY created_dttm DESC;

배치 작업별 성공률

SELECT
    job,
    COUNT(*) as total_runs,
    SUM(CASE WHEN status = 'COMPLETED' THEN 1 ELSE 0 END) as successful_runs,
    ROUND(100.0 * SUM(CASE WHEN status = 'COMPLETED' THEN 1 ELSE 0 END) / COUNT(*), 2) as success_rate
FROM public.batch_history
GROUP BY job
ORDER BY total_runs DESC;