db-schema-manager（数据库模式管理器）

DB Schema Manager

단일 진실의 소스(Single Source of Truth)로 모든 DB 테이블 스키마를 관리합니다.

⚠️ 통합 참조 문서: 모든 DB 작업 표준은 database_standards.md를 참조하세요. db-schema-manager는 스키마 정의 및 검증을 담당하고, database_standards.md는 전체 DB 사용 규칙을 정의합니다.

🎯 핵심 기능

1. 스키마 정의: 모든 테이블을 JSON으로 명확히 정의
2. 데이터 검증: 삽입 전 스키마 준수 확인
3. 스키마 비교: DB 실제 구조와 정의 비교
4. 마이그레이션: SQL 마이그레이션 자동 생성

📚 관리 중인 테이블 (5개)

🤖 AI 개발 도구 통합

코드 작성 시 자동 검증

VSCode / Antigravity / Claude: DB 관련 코드를 작성하거나 검토할 때:

1. 새 테이블 추가 시:

   # 1단계: 스키마 먼저 작성
   cat schemas/{table_name}.json
   
   # 2단계: 검증
   python scripts/validate_schema.py {table_name}
   
   # 3단계: SQL 생성
   python scripts/generate_migration.py {table_name}

1. 데이터 저장 전 검증:

   python scripts/validate_data.py {table_name} '{...json_data...}'

1. 스키마 동기화 확인:

   python scripts/compare_to_db.py {table_name}

필수 확인사항

✅ 코드 작성 전:

• schemas/{table}.json 파일 존재 여부
• database_standards.md의 네이밍 규칙 준수
• Repository 패턴 사용 여부 (backend.database.repository 확인)

❌ 절대 금지 (Zero Tolerance):

• 직접 SQL 작성 금지: SELECT, INSERT 등 raw SQL 사용 적발 시 즉시 거부
• Legacy Driver 사용 금지: psycopg2.connect() / asyncpg.connect() 직접 호출 시 즉시 거부
• 스키마 우회 금지: models.py에 정의되지 않은 컬럼 사용 금지
• Repository 우회 금지: session 객체를 직접 생성하여 사용하는 행위 금지 (get_sync_session 또는 Repository 활용)

🚀 Quick Start

스키마 확인

# 특정 테이블 스키마 보기
cat schemas/dividend_aristocrats.json

# 모든 테이블 나열
ls schemas/

데이터 검증 (삽입 전)

python scripts/validate_data.py dividend_aristocrats '{
  "ticker": "JNJ",
  "company_name": "Johnson & Johnson",
  "consecutive_years": 61,
  "sector": "Healthcare"
}'

성공: ✅ Validation passed 실패: 누락/잘못된 필드 나열

DB와 스키마 비교

# 특정 테이블 비교
python scripts/compare_to_db.py dividend_aristocrats

# 모든 테이블 검사
python scripts/compare_to_db.py --all

📄 스키마 파일 형식

각 테이블은 schemas/{table_name}.json 파일로 정의됩니다:

{
  "table_name": "dividend_aristocrats",
  "description": "배당 귀족주 (25+ 연속 배당 증가)",
  "primary_key": "ticker",
  "columns": [
    {
      "name": "ticker",
      "type": "VARCHAR(10)",
      "nullable": false,
      "description": "종목 코드",
      "example": "JNJ"
    },
    {
      "name": "company_name",
      "type": "VARCHAR(200)",
      "nullable": false,
      "description": "회사 이름"
    },
    {
      "name": "consecutive_years",
      "type": "INTEGER",
      "nullable": false,
      "description": "연속 배당 증가 연수"
    }
  ],
  "indexes": [
    {
      "name": "idx_aristocrat_ticker",
      "columns": ["ticker"],
      "unique": true
    }
  ],
  "metadata": {
    "phase": "Phase 21",
    "created": "2025-12-25",
    "update_frequency": "Annually (March 1)"
  }
}

📋 사용 패턴

1. 새 테이블 설계 확인

# 스키마 파일이 올바른지 검증
python scripts/validate_schema.py new_table

# 통과하면 마이그레이션 SQL 생성
python scripts/generate_migration.py new_table

2. 데이터 삽입 전 검증

Why: DB에 잘못된 데이터가 들어가는 것을 사전에 방지

# Python 코드에서 사용 예시
import subprocess
import json

data = {
    "ticker": "JNJ",
    "company_name": "Johnson & Johnson",
    "consecutive_years": 61
}

# 검증 스크립트 실행
result = subprocess.run(
    ["python", "scripts/validate_data.py", "dividend_aristocrats", json.dumps(data)],
    capture_output=True,
    text=True
)

if result.returncode == 0:
    print("✅ Valid - proceed to insert")
    # db.insert(data)
else:
    print(f"❌ Invalid:\n{result.stdout}")

3. 스키마 불일치 발견

Why: 코드의 모델이 실제 DB와 다를 수 있음

# 모든 테이블 검사
python scripts/compare_to_db.py --all

출력 예시:

✅ dividend_aristocrats: Schema matches!
❌ news_articles: Schema mismatch!
  ❌ Missing columns in DB: {'sentiment_score'}
  ⚠️  Extra columns in DB: {'old_field'}
  ❌ Type mismatch for published_at: defined=TIMESTAMP, actual=DATE

🔍 스키마 탐색

모든 테이블 찾기

ls schemas/*.json | sed 's/schemas\///' | sed 's/.json//'

특정 컬럼을 가진 테이블 찾기

grep -l '"name": "ticker"' schemas/*.json

테이블 메타데이터 확인

# Phase 21에 속한 테이블 찾기
grep -l '"phase": "Phase 21"' schemas/*.json

🛠️ 스크립트 상세

scripts/validate_data.py

목적: 데이터가 스키마를 만족하는지 검증

사용:

python scripts/validate_data.py <table_name> '<json_data>'

예시:

python scripts/validate_data.py dividend_aristocrats '{
  "ticker": "AAPL",
  "company_name": "Apple Inc.",
  "consecutive_years": 11
}'

Pydantic 사용: JSON 스키마 → Pydantic 모델 변환하여 타입 검증

scripts/compare_to_db.py

목적: 정의된 스키마와 실제 DB 비교

사용:

python scripts/compare_to_db.py <table_name>
python scripts/compare_to_db.py --all

확인 사항:

• 누락된 컬럼
• 추가 컬럼 (정의에 없음)
• 타입 불일치
• Nullable 속성 차이

scripts/generate_migration.py

목적: 스키마 정의에서 SQL 마이그레이션 생성

사용:

python scripts/generate_migration.py <table_name>

출력: CREATE TABLE, CREATE INDEX SQL

scripts/validate_schema.py

목적: JSON 스키마 파일 자체가 올바른지 검증

사용:

python scripts/validate_schema.py <table_name>

확인 사항:

• 필수 필드 존재 (table_name, columns)
• 타입 유효성 (VARCHAR, INTEGER 등)
• Primary key 정의
• JSON 구문 오류

📚 추가 문서

• 전체 스키마 참조: docs/SCHEMA_REFERENCE.md
• 마이그레이션 가이드: docs/MIGRATION_GUIDE.md

🎓 예제 시나리오

Scenario 1: 새 테이블 추가

User: "DividendHistory 테이블을 추가하고 싶어"

Claude:
1. templates/new_table_template.json 복사
2. 사용자와 함께 스키마 정의
3. validate_schema.py로 검증
4. generate_migration.py로 SQL 생성
5. SQL 실행하여 테이블 생성

Scenario 2: 데이터 검증 실패

User: "이 데이터를 dividend_aristocrats에 넣어줘"
Data: {"ticker": "AAPL", "consecutive_years": "invalid"}

Claude:
1. Read schemas/dividend_aristocrats.json
2. Run validate_data.py
3. 결과: ❌ Validation failed: consecutive_years must be integer
4. 사용자에게 수정 요청

Scenario 3: 스키마 불일치 해결

User: "왜 DividendAristocrat 모델이 DB와 안 맞아?"

Claude:
1. Run compare_to_db.py dividend_aristocrats
2. 불일치 발견: Missing columns: payout_ratio, market_cap
3. 설명: "models.py가 구버전입니다. DB는 18개 컬럼, 모델은 11개"
4. 제안: "models.py를 schemas/dividend_aristocrats.json 기준으로 업데이트하시겠어요?"

⚡ 빠른 참조

Version: 1.0.0 Last Updated: 2025-12-25 Maintainer: AI Trading System Team