geo ip 데이터 load후 api 수행하도록 구조 변경

README.md

@@ -1,6 +1,6 @@
 # GeoIP REST (Go Fiber)
 
-간단한 GeoIP 조회 API입니다. `GeoLite2-City.mmdb`를 사용해 IP를 나라/지역/도시/위도/경도로 매핑합니다.
+간단한 GeoIP 조회 API입니다. 기본은 `GeoLite2-City.mmdb`를 사용해 IP를 나라/지역/도시/위도/경도로 매핑하며, 선택적으로 PostgreSQL + `maxminddb_fdw`로 가져온 데이터를 조회할 수 있습니다. 초기 적재 후에는 DB만으로 조회가 가능하도록 읽기 전용 테이블과 함수가 생성됩니다.
 
 ## 요구 사항
 - Go 1.25+
@@ -14,16 +14,31 @@ go mod tidy            # 필요한 경우 go.sum 생성
 PORT=8080 GEOIP_DB_PATH=./GeoLite2-City.mmdb go run ./cmd/server
 ```
 
-### Docker Compose
+### Docker 최초 실행시
+```bash
+docker network create --driver bridge --attachable geo-ip
+``` 
+
+### Docker Compose (PostgreSQL + FDW + API)
 ```bash
 docker compose up --build
 ```
-- `GeoLite2-City.mmdb`가 컨테이너에 read-only로 마운트됩니다.
-- 기본 포트: `8080`.
+- 서비스
+  - `postgres` (5432): `Dockerfile.postgres`로 `maxminddb_fdw`를 빌드하여 확장 설치 후 `GeoLite2-City.mmdb`를 FDW로 읽고, 로컬 테이블로 적재합니다. 초기 적재 완료 후 mmdb 없이도 DB에서 조회가 가능합니다.
+  - `api` (8080): 기본적으로 Postgres 백엔드(`GEOIP_BACKEND=postgres`)를 사용해 조회합니다.
+- 볼륨
+  - `./GeoLite2-City.mmdb:/data/GeoLite2-City.mmdb:ro` (Postgres 초기 적재용)
+  - `pgdata` (DB 데이터 지속)
 
 ## 환경 변수
-- `PORT` (기본 `8080`): 서버 리스닝 포트
-- `GEOIP_DB_PATH` (기본 `/data/GeoLite2-City.mmdb`): GeoIP 데이터베이스 경로
+- 공통
+  - `PORT` (기본 `8080`): 서버 리스닝 포트
+  - `GEOIP_BACKEND` (`mmdb`|`postgres`, 기본 `mmdb`)
+- MMDB 모드
+  - `GEOIP_DB_PATH` (기본 `/data/GeoLite2-City.mmdb`): GeoIP 데이터베이스 경로
+- Postgres 모드
+  - `DATABASE_URL`: 예) `postgres://geoip_readonly:geoip_readonly@postgres:5432/geoip?sslmode=disable`
+  - `GEOIP_LOOKUP_QUERY` (선택): 기본은 `geoip.lookup_city($1)` 사용
 
 ## 사용법
 - 헬스체크: `GET /health`
@@ -49,6 +64,17 @@ curl "http://localhost:8080/lookup?ip=1.1.1.1"
 ```
 
 ## 개발 참고
-- 주요 코드: `cmd/server/main.go`, `internal/geo/resolver.go`
+- 주요 코드: `cmd/server/main.go`, `internal/geo` (MMDB/Postgres resolver)
 - 테스트 실행: `go test ./...`
+  - Postgres 통합 테스트 실행 시 `GEOIP_TEST_DATABASE_URL`을 설정하면 DB 백엔드 조회 테스트가 수행됩니다(미설정 시 skip).
 - 컨테이너 빌드: `docker build -t geoip:local .`
+
+## Postgres/FDW 쿼리 예시
+- 단건 조회 함수 (CIDR 매칭): `SELECT * FROM geoip.lookup_city('1.1.1.1');`
+- 원시 테이블 조회: `SELECT * FROM geoip.city_blocks LIMIT 5;`
+- API는 `lookup_city(inet)`를 사용하여 가장 구체적인 네트워크(prefix) 한 건을 반환합니다.
+
+## 보안 및 운영 주의사항
+- GeoLite2 라이선스 준수: `GeoLite2-City.mmdb` 교체 시 기존 파일을 대체하여 재시작하세요.
+- Postgres 포트(5432) 외부 노출 시 방화벽/보안 그룹으로 제한하고 강한 비밀번호를 사용하세요.
+- DB는 읽기 전용 계정(`geoip_readonly`)을 기본으로 사용하며, 초기 스키마에서 `default_transaction_read_only`를 강제합니다.