name	db-validate
description	Validate Laravel database configuration and test actual connections. Use when user reports "database connection error", "hosts array is empty", "could not connect to database", or wants to verify database setup is correct.
allowed-tools	Bash, Read, Grep

Database Connection Validator

Laravel 데이터베이스 설정을 검증하고 실제 연결을 테스트하는 Skill입니다.

🎯 자동 실행 트리거

다음 상황에서 자동으로 실행:

"Database connection error" 오류
"Database hosts array is empty" 오류
"Could not connect to database" 오류
"SQLSTATE[HY000]" 오류
"DB 연결 확인해줘"
"데이터베이스 설정 맞나?"

🔍 검증 체크리스트

1. .env 파일 DB 설정 확인

# DB 관련 환경변수 추출
grep -E "^(DB_CONNECTION|DB_HOST|DB_HOST_LOCAL|DB_PORT|DB_PORT_LOCAL|DB_DATABASE|DB_DATABASE_LOCAL|DB_USERNAME|DB_USERNAME_LOCAL|DB_PASSWORD|DB_PASSWORD_LOCAL)=" .env

기대값 (로컬 개발):

DB_CONNECTION=pgsql_local
DB_HOST_LOCAL=localhost
DB_PORT_LOCAL=5432
DB_DATABASE_LOCAL=ykp_dashboard_local
DB_USERNAME_LOCAL=postgres
DB_PASSWORD_LOCAL=1234

검증 항목:

✅ DB_CONNECTION이 정의되어 있나?
✅ 연결 이름과 일치하는 HOST/DATABASE 변수가 있나?
- pgsql_local → DB_HOST_LOCAL, DB_DATABASE_LOCAL 필요
- pgsql → DB_HOST, DB_DATABASE 필요
✅ 비밀번호가 설정되어 있나?

2. config/database.php 연결 설정 확인

# pgsql_local 연결 설정 확인
grep -A 15 "'pgsql_local'" config/database.php

확인 사항:

연결 정의 존재 여부
env() 함수가 올바른 변수명 사용
올바른 드라이버 ('driver' => 'pgsql')

3. 실제 DB 연결 테스트

# 현재 설정으로 연결 테스트
php artisan tinker --execute="
try {
    echo 'Testing Connection: ' . config('database.default') . PHP_EOL;
    echo 'Host: ' . config('database.connections.' . config('database.default') . '.host') . PHP_EOL;
    echo 'Database: ' . config('database.connections.' . config('database.default') . '.database') . PHP_EOL;

    \$count = DB::connection()->table('users')->count();
    echo 'SUCCESS: Connected! Users found: ' . \$count . PHP_EOL;
} catch (Exception \$e) {
    echo 'FAILED: ' . \$e->getMessage() . PHP_EOL;
}
"

4. PostgreSQL 서버 상태 확인 (로컬)

# PostgreSQL 프로세스 확인
tasklist /FI "IMAGENAME eq postgres.exe" 2>/dev/null || echo "PostgreSQL not running"

# 포트 5432 리스닝 확인
netstat -ano | findstr :5432

🛠️ 문제별 해결 방법

문제 1: "Database hosts array is empty"

원인: Session/Cache 드라이버가 database인데, 연결 설정이 없음

진단:

# Session/Cache 드라이버 확인
grep -E "^(SESSION_DRIVER|SESSION_CONNECTION|CACHE_STORE|CACHE_DATABASE_CONNECTION)=" .env

해결:

로컬 개발: 파일 드라이버 사용 (권장)
```
SESSION_DRIVER=file
CACHE_STORE=file
```

DB 드라이버 계속 사용:

SESSION_DRIVER=database
SESSION_CONNECTION=pgsql_local  # 명시적 연결
CACHE_STORE=database
CACHE_DATABASE_CONNECTION=pgsql_local

사용자 안내:

⚠️ "Database hosts array is empty" 감지

원인: Session/Cache가 database 드라이버를 사용하려는데, 연결 설정(SESSION_CONNECTION)이 지정되지 않았습니다.

권장 해결 (로컬 개발):
SESSION_DRIVER=file
CACHE_STORE=file
QUEUE_CONNECTION=sync
또는 DB 연결 명시:
SESSION_CONNECTION=pgsql_local
CACHE_DATABASE_CONNECTION=pgsql_local
수정 후:
php artisan optimize:clear

문제 2: "Could not connect to server"

원인: PostgreSQL 서버가 실행 중이지 않음 (로컬)

진단:

# PostgreSQL 실행 여부 확인
tasklist /FI "IMAGENAME eq postgres.exe"

해결:

# PostgreSQL 시작
postgresql-17.6-2-windows-x64-binaries/bin/pg_ctl.exe -D postgresql-data start

# 상태 확인
postgresql-17.6-2-windows-x64-binaries/bin/pg_ctl.exe -D postgresql-data status

사용자 안내:

⚠️ PostgreSQL 서버 미실행

로컬 PostgreSQL 서버가 실행되고 있지 않습니다.

해결:
# PostgreSQL 시작
postgresql-17.6-2-windows-x64-binaries/bin/pg_ctl.exe -D postgresql-data start

# 연결 테스트
php artisan tinker --execute="DB::connection()->getPdo();"
자동 시작 설정 (선택사항): Windows Services에 PostgreSQL 등록하여 부팅 시 자동 시작

문제 3: "Access denied for user"

원인: 비밀번호 불일치 또는 사용자 권한 부족

진단:

# 직접 PostgreSQL 연결 테스트
postgresql-17.6-2-windows-x64-binaries/bin/psql.exe -U postgres -d ykp_dashboard_local -c "SELECT 1;"

해결:

비밀번호 확인:

DB_PASSWORD_LOCAL=1234  # 실제 PostgreSQL 비밀번호

사용자 권한 확인:

-- PostgreSQL에 접속하여 실행
\du  -- 사용자 목록 및 권한 확인

사용자 안내:

⚠️ 인증 실패

PostgreSQL 사용자 인증에 실패했습니다.

체크리스트:
.env 파일의 DB_PASSWORD_LOCAL 확인
psql로 직접 연결 테스트:
psql -U postgres -d ykp_dashboard_local
비밀번호가 다르면 PostgreSQL 재설정:
psql -U postgres
ALTER USER postgres PASSWORD '새비밀번호';

문제 4: "Database does not exist"

원인: 데이터베이스가 생성되지 않음

진단:

# 데이터베이스 목록 확인
postgresql-17.6-2-windows-x64-binaries/bin/psql.exe -U postgres -c "\l"

해결:

# 데이터베이스 생성
postgresql-17.6-2-windows-x64-binaries/bin/psql.exe -U postgres -c "CREATE DATABASE ykp_dashboard_local;"

# 마이그레이션 실행
php artisan migrate
php artisan db:seed

사용자 안내:

⚠️ 데이터베이스 미존재

ykp_dashboard_local 데이터베이스가 생성되지 않았습니다.

해결:
# 1. 데이터베이스 생성
psql -U postgres -c "CREATE DATABASE ykp_dashboard_local;"

# 2. 마이그레이션 실행
php artisan migrate

# 3. 테스트 데이터 시딩
php artisan db:seed

문제 5: 로컬/프로덕션 DB 혼동

증상: 로컬 환경인데 Supabase 연결 시도

진단:

# 현재 연결 확인
php artisan tinker --execute="
echo 'Connection: ' . config('database.default') . PHP_EOL;
echo 'Host: ' . config('database.connections.' . config('database.default') . '.host') . PHP_EOL;
"

위험 신호:

APP_ENV=local인데 DB_HOST=aws-1-ap-southeast-1.pooler.supabase.com

해결: .env 파일 수정:

# 로컬 개발용
DB_CONNECTION=pgsql_local
DB_HOST_LOCAL=localhost
DB_DATABASE_LOCAL=ykp_dashboard_local

사용자 안내:

🚨 위험: 프로덕션 DB 연결 시도 감지!

로컬 환경(APP_ENV=local)인데 Supabase 프로덕션 DB에 연결하려고 합니다!

즉시 수정:
DB_CONNECTION=pgsql_local
DB_HOST_LOCAL=localhost
DB_DATABASE_LOCAL=ykp_dashboard_local
캐시 클리어:
php artisan optimize:clear
⚠️ 프로덕션 데이터를 실수로 수정할 뻔했습니다!

📊 검증 보고서

모든 검증 완료 후 보고:

🗄️ 데이터베이스 연결 검증 완료

✅ 환경 설정:
- APP_ENV: local
- DB_CONNECTION: pgsql_local

✅ 연결 설정:
- Host: localhost:5432
- Database: ykp_dashboard_local
- Username: postgres

✅ PostgreSQL 서버:
- 상태: 실행 중 ✅
- 버전: PostgreSQL 17.6
- 포트: 5432 리스닝 중

✅ 연결 테스트:
- 연결 성공 ✅
- Users 테이블: 63 rows
- 응답 시간: < 50ms

🎯 추천 사항:
- ✅ 모든 설정이 올바릅니다
- ✅ 데이터베이스 정상 작동 중
- ℹ️  테스트 계정: admin@ykp.com / password

🔧 연결 설정 참조

로컬 개발 환경 (pgsql_local)

DB_CONNECTION=pgsql_local
DB_HOST_LOCAL=localhost
DB_PORT_LOCAL=5432
DB_DATABASE_LOCAL=ykp_dashboard_local
DB_USERNAME_LOCAL=postgres
DB_PASSWORD_LOCAL=1234

프로덕션 환경 (pgsql - Supabase)

Railway 환경변수에서 설정:

DB_CONNECTION=pgsql
DB_HOST=aws-1-ap-southeast-1.pooler.supabase.com
DB_PORT=5432
DB_DATABASE=postgres
DB_USERNAME=postgres.qwafwqxdcfpqqwpmphkm
DB_PASSWORD=<Supabase 비밀번호>
DB_SSLMODE=require

🚨 프로덕션 DB 안전 수칙

절대 금지

❌ 로컬에서 프로덕션 DB 직접 연결
❌ .env 파일에 Supabase 자격증명 저장
❌ 프로덕션 DB에서 migrate:fresh 실행
❌ 테스트 데이터를 프로덕션에 삽입

권장 사항

✅ 로컬은 항상 pgsql_local 사용
✅ Supabase는 Railway 환경변수에서만 관리
✅ 프로덕션 작업 전 백업 필수
✅ 읽기 전용 연결로 프로덕션 확인

🎓 트러블슈팅 플로우차트

DB 연결 오류 발생
     ↓
[1] PostgreSQL 실행 중?
     No → 서버 시작
     Yes ↓
[2] .env 파일 올바른 설정?
     No → pgsql_local 설정 확인
     Yes ↓
[3] 캐시 문제?
     Yes → optimize:clear
     No ↓
[4] 데이터베이스 존재?
     No → CREATE DATABASE
     Yes ↓
[5] 비밀번호 일치?
     No → .env 수정 또는 PG 재설정
     Yes ↓
[6] env-health Skill 실행

💡 학습 포인트

이 Skill을 통해 배운 핵심:

연결 이름의 일관성:
- DB_CONNECTION=pgsql_local
- → DB_HOST_LOCAL, DB_DATABASE_LOCAL 사용
- 접미사 일치 중요!
Session/Cache 드라이버 함정:
- SESSION_DRIVER=database
- → SESSION_CONNECTION 필수!
- 없으면 "hosts array is empty" 오류
로컬/프로덕션 명확한 분리:
- 로컬: localhost PostgreSQL
- 프로덕션: Supabase (Railway 환경변수)
- 절대 혼용 금지!

다음에 DB 문제 발생 시:

PostgreSQL 실행 확인
.env 파일 검증
캐시 클리어
연결 테스트 (tinker)

db-validate

Install Skill

SKILL.md

Database Connection Validator

🎯 자동 실행 트리거

🔍 검증 체크리스트

1. .env 파일 DB 설정 확인

2. config/database.php 연결 설정 확인

3. 실제 DB 연결 테스트

4. PostgreSQL 서버 상태 확인 (로컬)

🛠️ 문제별 해결 방법

문제 1: "Database hosts array is empty"

문제 2: "Could not connect to server"

문제 3: "Access denied for user"

문제 4: "Database does not exist"

문제 5: 로컬/프로덕션 DB 혼동

📊 검증 보고서

🔧 연결 설정 참조

로컬 개발 환경 (pgsql_local)

프로덕션 환경 (pgsql - Supabase)

🚨 프로덕션 DB 안전 수칙

절대 금지

권장 사항

🎓 트러블슈팅 플로우차트

💡 학습 포인트