258 lines
6.1 KiB
Markdown
258 lines
6.1 KiB
Markdown
# 데이터베이스 설정 가이드
|
|
|
|
## 개요
|
|
이 애플리케이션은 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
|
|
|
|
**설정**:
|
|
```yaml
|
|
spring:
|
|
batch:
|
|
jdbc:
|
|
initialize-schema: always
|
|
```
|
|
|
|
### 2. batch_history 테이블 (커스텀)
|
|
배치 작업 실행 이력을 저장하는 커스텀 테이블입니다.
|
|
|
|
**용도**:
|
|
- 배치 작업 시작/종료 시간 기록
|
|
- 배치 실행 상태 추적 (STARTED/COMPLETED/FAILED)
|
|
- 비즈니스 ID별 배치 이력 관리
|
|
|
|
## 새 환경 데이터베이스 초기 설정
|
|
|
|
### Option 1: SQL 스크립트 실행 (권장)
|
|
|
|
**1. batch_history 테이블 생성**:
|
|
```bash
|
|
# PostgreSQL에 연결
|
|
psql -h [host] -U [username] -d [database]
|
|
|
|
# schema.sql 실행
|
|
\i src/main/resources/sql/schema.sql
|
|
```
|
|
|
|
**또는 직접 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. 권한 설정** (필요한 경우):
|
|
```sql
|
|
-- 애플리케이션 사용자에게 권한 부여
|
|
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**:
|
|
```yaml
|
|
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 환경
|
|
```yaml
|
|
spring:
|
|
datasource:
|
|
url: jdbc:postgresql://localhost:5432/kamco_local
|
|
username: dev_user
|
|
password: dev_password
|
|
sql:
|
|
init:
|
|
mode: always # 자동 초기화 활성화
|
|
```
|
|
|
|
### Production 환경
|
|
```yaml
|
|
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 자동 초기화 비활성화:
|
|
```yaml
|
|
spring:
|
|
sql:
|
|
init:
|
|
mode: never
|
|
```
|
|
|
|
2. 또는 테이블 소유권 변경:
|
|
```sql
|
|
ALTER TABLE public.batch_history OWNER TO [app_user];
|
|
```
|
|
|
|
### 에러: "relation batch_history does not exist"
|
|
|
|
**원인**: batch_history 테이블이 생성되지 않음
|
|
|
|
**해결**:
|
|
1. SQL 스크립트 수동 실행:
|
|
```bash
|
|
psql -h [host] -U [user] -d [database] -f src/main/resources/sql/schema.sql
|
|
```
|
|
|
|
2. 또는 자동 초기화 활성화 (개발 환경만):
|
|
```yaml
|
|
spring:
|
|
sql:
|
|
init:
|
|
mode: always
|
|
schema-locations: classpath:sql/schema.sql
|
|
```
|
|
|
|
### 에러: "permission denied for schema public"
|
|
|
|
**원인**: DB 사용자에게 public 스키마 권한 없음
|
|
|
|
**해결**:
|
|
```sql
|
|
GRANT ALL ON SCHEMA public TO [app_user];
|
|
GRANT ALL PRIVILEGES ON ALL TABLES IN SCHEMA public TO [app_user];
|
|
```
|
|
|
|
## 데이터베이스 마이그레이션
|
|
|
|
### 기존 환경에서 테이블 확인
|
|
```sql
|
|
-- 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_*
|
|
```
|
|
|
|
### 테이블 재생성 (데이터 삭제 주의!)
|
|
```sql
|
|
-- 기존 테이블 삭제 (주의: 모든 데이터 손실!)
|
|
DROP TABLE IF EXISTS public.batch_history CASCADE;
|
|
|
|
-- schema.sql 재실행
|
|
\i src/main/resources/sql/schema.sql
|
|
```
|
|
|
|
## 백업 및 복구
|
|
|
|
### 테이블 백업
|
|
```bash
|
|
pg_dump -h [host] -U [user] -d [database] -t batch_history > batch_history_backup.sql
|
|
```
|
|
|
|
### 테이블 복구
|
|
```bash
|
|
psql -h [host] -U [user] -d [database] < batch_history_backup.sql
|
|
```
|
|
|
|
## 모니터링 쿼리
|
|
|
|
### 최근 배치 실행 이력 조회
|
|
```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;
|
|
```
|
|
|
|
### 실패한 배치 조회
|
|
```sql
|
|
SELECT *
|
|
FROM public.batch_history
|
|
WHERE status = 'FAILED'
|
|
ORDER BY created_dttm DESC;
|
|
```
|
|
|
|
### 배치 작업별 성공률
|
|
```sql
|
|
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;
|
|
```
|