PostgreSQL 학습 환경

Docker와 Go 및 Bun ORM을 사용한 PostgreSQL 기능의 포괄적인 학습 환경입니다.

환경 설정

사전 요구사항

• Docker Engine 20.10+
• Docker Compose 2.0+
• Go 1.21+
• Task (선택사항, 설치: go install github.com/go-task/task/v3/cmd/task@latest)

설치 및 실행

1. 환경 시작

   task dev
   # 또는 docker-compose up -d

2. PostgreSQL 연결 확인

   task db-connect
   # 또는 docker-compose exec postgres psql -U postgres -d postgres_learning -c "SELECT version();"

3. pgAdmin 접속

   • URL: http://localhost:8080
   • 이메일: admin@example.com
   • 비밀번호: admin

4. Go 애플리케이션 실행

   task run-dev step01
   # 또는 docker-compose exec app go run src/main.go step01

사용법

Task 명령어

프로젝트에서는 Task를 사용하여 일반적인 작업들을 수행할 수 있습니다.

# 사용 가능한 작업 목록
task

# 빌드
task build

# 개발 모드로 실행
task run-dev step01

# 테스트 실행
task test

# Docker 서비스 시작
task docker-up

# Docker 서비스 중지
task stop

# 데이터베이스 연결
task db-connect

# pgAdmin 열기
task pgadmin-open

CLI 명령어

# 도움말
task run-dev --help
# 또는 go run src/main.go --help

# 특정 단계 실행
task run-dev step01  # 데이터 타입 학습
task run-dev step02  # 쿼리 및 인덱싱 학습
# ... step12까지
# 또는 go run src/main.go step01

Docker 컨테이너 관리

# 컨테이너 상태 확인
docker-compose ps

# 로그 확인
task docker-logs
# 또는 docker-compose logs postgres
# docker-compose logs app

# 컨테이너 재시작
task docker-restart
# 또는 docker-compose restart

# 환경 정지
task stop
# 또는 docker-compose down

프로젝트 구조

postgresql-learning/
├── Taskfile.yml               # Task 설정 파일
├── docker-compose.yml          # Docker Compose 설정
├── Dockerfile                  # Go 애플리케이션용
├── src/
│   ├── go.mod                  # Go 모듈
│   ├── main.go                 # CLI 애플리케이션 진입점
│   └── cmd/                    # CLI 명령어
│       ├── step01.go          # STEP01 명령어
│       ├── step02.go          # STEP02 명령어
│       └── ...
├── scripts/
│   └── init-db.sh             # 데이터베이스 초기화
├── tasks/
│   ├── CURRICULUM.md          # 학습 커리큘럼
│   ├── PRD.md                 # 프로젝트 요구사항
│   └── feature*.md            # 기능 문서
├── docs/
│   ├── index.html             # 메인 페이지
│   ├── step*.html             # 각 단계 페이지
│   └── step_template.html     # 페이지 템플릿
└── README.md                  # 이 파일

학습 단계

1. STEP01: PostgreSQL 데이터 타입
2. STEP02: 쿼리 및 인덱싱
3. STEP03: 동시성과 트랜잭션
4. STEP04: 보안 기능
5. STEP05: 확장성
6. STEP06: hstore 확장
7. STEP07: pg_trgm 확장
8. STEP08: PostGIS 확장
9. STEP09: pg_stat_statements 확장
10. STEP10: pgcrypto 확장
11. STEP11: pgvector 확장 (벡터화/임베딩)
12. STEP12: pg_buffercache 확장 (KVS/캐시)

데이터베이스 연결 정보

• 호스트: postgres (Docker 내부) / localhost (외부)
• 포트: 5432
• 데이터베이스: postgres_learning
• 사용자: postgres
• 비밀번호: password

확장 기능

환경이 시작되면 다음 확장 기능이 자동으로 활성화됩니다:

• uuid-ossp
• hstore
• pg_trgm
• tablefunc
• pgcrypto
• pgvector
• pg_buffercache
• pg_stat_statements

문제 해결

일반적인 문제

1. 포트 충돌

   # 사용 중인 포트 확인
   netstat -an | grep :5432
   netstat -an | grep :8080
   
   # docker-compose.yml에서 포트 변경
   ports:
     - "5433:5432"  # PostgreSQL
     - "8081:80"    # pgAdmin

2. 권한 문제

   # 파일 권한 설정
   chmod +x scripts/init-db.sh

3. 메모리 부족

   # Docker Desktop 메모리 설정 증가
   # 또는 시스템 메모리 확보

로그 확인

# PostgreSQL 로그
docker-compose logs postgres

# 애플리케이션 로그
docker-compose logs app

# 모든 로그
docker-compose logs

기여

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

라이선스

This project is licensed under the MIT License - see the LICENSE file for details.