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

DB 적재 초기구조
2025-12-09 15:12:36 +09:00 · 2025-12-09 13:51:25 +09:00
15 changed files with 841 additions and 81 deletions
--- a/4
+++ b/4
@@ -8,7 +8,8 @@ COPY go.mod ./
 RUN go mod download

 COPY . .
-RUN CGO_ENABLED=0 go build -o /bin/geoip ./cmd/server
+RUN CGO_ENABLED=0 go build -o /bin/geoip ./cmd/server && \
+    CGO_ENABLED=0 go build -o /bin/geoip-loader ./cmd/loader

 FROM debian:trixie-slim

@@ -17,6 +18,7 @@ RUN useradd --create-home --shell /usr/sbin/nologin appuser
 WORKDIR /app

 COPY --from=builder /bin/geoip /usr/local/bin/geoip
+COPY --from=builder /bin/geoip-loader /usr/local/bin/geoip-loader
 COPY GeoLite2-City.mmdb /data/GeoLite2-City.mmdb

 ENV GEOIP_DB_PATH=/data/GeoLite2-City.mmdb
--- a/README.md
+++ b/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`를 강제합니다.
--- a/cmd/loader/main.go
+++ b/cmd/loader/main.go
@@ -0,0 +1,378 @@
+package main
+
+import (
+	"context"
+	"crypto/sha256"
+	"database/sql"
+	"encoding/hex"
+	"errors"
+	"fmt"
+	"io"
+	"log"
+	"os"
+	"strconv"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/oschwald/maxminddb-golang"
+)
+
+const (
+	defaultMMDBPath      = "/data/GeoLite2-City.mmdb"
+	defaultSchema        = "geoip"
+	defaultLoaderTimeout = 5 * time.Minute
+)
+
+type cityRecord struct {
+	City struct {
+		GeoNameID uint              `maxminddb:"geoname_id"`
+		Names     map[string]string `maxminddb:"names"`
+	} `maxminddb:"city"`
+	Country struct {
+		IsoCode string            `maxminddb:"iso_code"`
+		Names   map[string]string `maxminddb:"names"`
+	} `maxminddb:"country"`
+	Subdivisions []struct {
+		IsoCode string            `maxminddb:"iso_code"`
+		Names   map[string]string `maxminddb:"names"`
+	} `maxminddb:"subdivisions"`
+	Location struct {
+		Latitude  float64 `maxminddb:"latitude"`
+		Longitude float64 `maxminddb:"longitude"`
+		TimeZone  string  `maxminddb:"time_zone"`
+	} `maxminddb:"location"`
+}
+
+type cityRow struct {
+	network    string
+	geonameID  int
+	country    string
+	countryISO string
+	region     string
+	regionISO  string
+	city       string
+	latitude   float64
+	longitude  float64
+	timeZone   string
+}
+
+func main() {
+	ctx, cancel := context.WithTimeout(context.Background(), defaultLoaderTimeout)
+	defer cancel()
+
+	dbURL := os.Getenv("DATABASE_URL")
+	if dbURL == "" {
+		log.Fatal("DATABASE_URL is required")
+	}
+
+	mmdbPath := env("GEOIP_DB_PATH", defaultMMDBPath)
+	skipIfSame := envBool("GEOIP_LOADER_SKIP_IF_SAME_HASH", true)
+	force := envBool("GEOIP_LOADER_FORCE", false)
+
+	log.Printf("starting mmdb load from %s", mmdbPath)
+
+	hash, err := fileSHA256(mmdbPath)
+	if err != nil {
+		log.Fatalf("failed to hash mmdb: %v", err)
+	}
+
+	conn, err := pgx.Connect(ctx, dbURL)
+	if err != nil {
+		log.Fatalf("failed to connect database: %v", err)
+	}
+	defer conn.Close(context.Background())
+
+	if err := ensureSchema(ctx, conn); err != nil {
+		log.Fatalf("failed to ensure schema: %v", err)
+	}
+
+	existingHash, err := currentHash(ctx, conn)
+	if err != nil {
+		log.Fatalf("failed to read metadata: %v", err)
+	}
+	if skipIfSame && !force && existingHash == hash {
+		log.Printf("mmdb hash unchanged (%s), skipping load", hash)
+		return
+	}
+
+	rowSource, err := newNetworkSource(mmdbPath)
+	if err != nil {
+		log.Fatalf("failed to open mmdb: %v", err)
+	}
+	defer rowSource.Close()
+
+	if err := loadNetworks(ctx, conn, rowSource); err != nil {
+		log.Fatalf("failed to load networks: %v", err)
+	}
+
+	if err := upsertHash(ctx, conn, hash); err != nil {
+		log.Fatalf("failed to update metadata: %v", err)
+	}
+
+	log.Printf("loaded mmdb into Postgres (%d rows), hash=%s", rowSource.Rows(), hash)
+}
+
+func env(key, fallback string) string {
+	if val := os.Getenv(key); val != "" {
+		return val
+	}
+	return fallback
+}
+
+func envBool(key string, fallback bool) bool {
+	val := os.Getenv(key)
+	if val == "" {
+		return fallback
+	}
+	parsed, err := strconv.ParseBool(val)
+	if err != nil {
+		return fallback
+	}
+	return parsed
+}
+
+func fileSHA256(path string) (string, error) {
+	f, err := os.Open(path)
+	if err != nil {
+		return "", err
+	}
+	defer f.Close()
+
+	h := sha256.New()
+	if _, err := io.Copy(h, f); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(h.Sum(nil)), nil
+}
+
+func ensureSchema(ctx context.Context, conn *pgx.Conn) error {
+	ddl := fmt.Sprintf(`
+CREATE SCHEMA IF NOT EXISTS %s;
+
+CREATE TABLE IF NOT EXISTS %s.geoip_metadata (
+  key text PRIMARY KEY,
+  value text NOT NULL,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS %s.city_lookup (
+  network cidr PRIMARY KEY,
+  geoname_id integer,
+  country text,
+  country_iso_code text,
+  region text,
+  region_iso_code text,
+  city text,
+  latitude double precision,
+  longitude double precision,
+  time_zone text
+);
+`, defaultSchema, defaultSchema, defaultSchema)
+
+	_, err := conn.Exec(ctx, ddl)
+	return err
+}
+
+func currentHash(ctx context.Context, conn *pgx.Conn) (string, error) {
+	var hash sql.NullString
+	err := conn.QueryRow(ctx, `SELECT value FROM geoip.geoip_metadata WHERE key = 'mmdb_sha256'`).Scan(&hash)
+	if errors.Is(err, pgx.ErrNoRows) {
+		return "", nil
+	}
+	if err != nil {
+		return "", err
+	}
+	return hash.String, nil
+}
+
+func upsertHash(ctx context.Context, conn *pgx.Conn, hash string) error {
+	_, err := conn.Exec(ctx, `
+INSERT INTO geoip.geoip_metadata(key, value, updated_at)
+VALUES ('mmdb_sha256', $1, now())
+ON CONFLICT (key) DO UPDATE
+  SET value = EXCLUDED.value,
+      updated_at = EXCLUDED.updated_at;
+`, hash)
+	return err
+}
+
+type networkSource struct {
+	reader *maxminddb.Reader
+	iter   *maxminddb.Networks
+	err    error
+	row    cityRow
+	count  int
+}
+
+func newNetworkSource(path string) (*networkSource, error) {
+	reader, err := maxminddb.Open(path)
+	if err != nil {
+		return nil, err
+	}
+	return &networkSource{
+		reader: reader,
+		iter:   reader.Networks(),
+	}, nil
+}
+
+func (s *networkSource) Close() {
+	if s.reader != nil {
+		_ = s.reader.Close()
+	}
+}
+
+func (s *networkSource) Rows() int {
+	return s.count
+}
+
+func (s *networkSource) Next() bool {
+	if !s.iter.Next() {
+		s.err = s.iter.Err()
+		return false
+	}
+
+	var rec cityRecord
+	network, err := s.iter.Network(&rec)
+	if err != nil {
+		s.err = err
+		return false
+	}
+
+	s.row = cityRow{
+		network:    network.String(),
+		geonameID:  int(rec.City.GeoNameID),
+		country:    rec.Country.Names["en"],
+		countryISO: rec.Country.IsoCode,
+		region:     firstName(rec.Subdivisions),
+		regionISO:  firstISO(rec.Subdivisions),
+		city:       rec.City.Names["en"],
+		latitude:   rec.Location.Latitude,
+		longitude:  rec.Location.Longitude,
+		timeZone:   rec.Location.TimeZone,
+	}
+	s.count++
+	if s.count%500000 == 0 {
+		log.Printf("loader progress: %d rows processed", s.count)
+	}
+	return true
+}
+
+func (s *networkSource) Values() ([]any, error) {
+	return []any{
+		s.row.network,
+		s.row.geonameID,
+		s.row.country,
+		s.row.countryISO,
+		s.row.region,
+		s.row.regionISO,
+		s.row.city,
+		s.row.latitude,
+		s.row.longitude,
+		s.row.timeZone,
+	}, nil
+}
+
+func (s *networkSource) Err() error {
+	if s.err != nil {
+		return s.err
+	}
+	return s.iter.Err()
+}
+
+func firstName(subdivisions []struct {
+	IsoCode string            `maxminddb:"iso_code"`
+	Names   map[string]string `maxminddb:"names"`
+}) string {
+	if len(subdivisions) == 0 {
+		return ""
+	}
+	return subdivisions[0].Names["en"]
+}
+
+func firstISO(subdivisions []struct {
+	IsoCode string            `maxminddb:"iso_code"`
+	Names   map[string]string `maxminddb:"names"`
+}) string {
+	if len(subdivisions) == 0 {
+		return ""
+	}
+	return subdivisions[0].IsoCode
+}
+
+func loadNetworks(ctx context.Context, conn *pgx.Conn, src *networkSource) error {
+	tx, err := conn.Begin(ctx)
+	if err != nil {
+		return err
+	}
+	defer func() {
+		_ = tx.Rollback(ctx)
+	}()
+
+	_, err = tx.Exec(ctx, `DROP TABLE IF EXISTS geoip.city_lookup_new; CREATE TABLE geoip.city_lookup_new (LIKE geoip.city_lookup INCLUDING ALL);`)
+	if err != nil {
+		return err
+	}
+
+	columns := []string{
+		"network",
+		"geoname_id",
+		"country",
+		"country_iso_code",
+		"region",
+		"region_iso_code",
+		"city",
+		"latitude",
+		"longitude",
+		"time_zone",
+	}
+
+	log.Printf("loader copy: starting bulk copy")
+	copied, err := tx.CopyFrom(ctx, pgx.Identifier{defaultSchema, "city_lookup_new"}, columns, src)
+	if err != nil {
+		return err
+	}
+	log.Printf("loader copy: finished bulk copy (rows=%d)", copied)
+
+	if _, err := tx.Exec(ctx, `
+  ALTER TABLE IF EXISTS geoip.city_lookup RENAME TO city_lookup_old;
+  ALTER TABLE geoip.city_lookup_new RENAME TO city_lookup;
+  DROP TABLE IF EXISTS geoip.city_lookup_old;
+`); err != nil {
+		return err
+	}
+
+	if _, err := tx.Exec(ctx, `
+  CREATE INDEX IF NOT EXISTS city_lookup_network_gist ON geoip.city_lookup USING gist (network inet_ops);
+  CREATE INDEX IF NOT EXISTS city_lookup_geoname_id_idx ON geoip.city_lookup (geoname_id);
+`); err != nil {
+		return err
+	}
+
+	if _, err := tx.Exec(ctx, `
+  CREATE OR REPLACE FUNCTION geoip.lookup_city(ip inet)
+  RETURNS TABLE (
+      ip inet,
+      country text,
+      region text,
+      city text,
+      latitude double precision,
+      longitude double precision
+  ) LANGUAGE sql STABLE AS $$
+      SELECT
+          $1::inet AS ip,
+          c.country,
+          c.region,
+          c.city,
+          c.latitude,
+          c.longitude
+      FROM geoip.city_lookup c
+      WHERE c.network >>= $1
+      ORDER BY masklen(c.network) DESC
+      LIMIT 1;
+  $$;
+`); err != nil {
+		return err
+	}
+
+	return tx.Commit(ctx)
+}
--- a/cmd/server/main.go
+++ b/cmd/server/main.go
@@ -1,7 +1,9 @@
 package main

 import (
+	"errors"
 	"log"
+	"net/url"
 	"os"

 	"github.com/gofiber/fiber/v2"
@@ -15,12 +17,20 @@ const (
 )

 func main() {
+	backend := geo.Backend(env("GEOIP_BACKEND", string(geo.BackendMMDB)))
 	dbPath := env("GEOIP_DB_PATH", defaultDBPath)
+	dbURL := os.Getenv("DATABASE_URL")
+	lookupQuery := os.Getenv("GEOIP_LOOKUP_QUERY")
 	port := env("PORT", defaultPort)

-	resolver, err := geo.NewResolver(dbPath)
+	resolver, err := geo.NewResolver(geo.Config{
+		Backend:     backend,
+		MMDBPath:    dbPath,
+		DatabaseURL: dbURL,
+		LookupQuery: lookupQuery,
+	})
 	if err != nil {
-		log.Fatalf("failed to open GeoIP database: %v", err)
+		log.Fatalf("failed to initialize resolver: %v", err)
 	}
 	defer resolver.Close()

@@ -50,21 +60,33 @@ func main() {

 		location, err := resolver.Lookup(ip)
 		if err != nil {
-			if err == geo.ErrInvalidIP {
+			switch {
+			case errors.Is(err, geo.ErrInvalidIP):
 				return c.Status(fiber.StatusBadRequest).JSON(fiber.Map{
 					"error": "invalid ip address",
 				})
+			case errors.Is(err, geo.ErrNotFound):
+				return c.Status(fiber.StatusNotFound).JSON(fiber.Map{
+					"error": "location not found",
+				})
+			default:
+				return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{
+					"error": "lookup failed",
+				})
 			}
-
-			return c.Status(fiber.StatusInternalServerError).JSON(fiber.Map{
-				"error": "lookup failed",
-			})
 		}

 		return c.JSON(location)
 	})

-	log.Printf("starting GeoIP API on :%s using %s", port, dbPath)
+	log.Printf("starting GeoIP API on :%s backend=%s", port, backend)
+	switch backend {
+	case geo.BackendPostgres:
+		log.Printf("using postgres DSN %s", sanitizeDBURL(dbURL))
+	default:
+		log.Printf("using mmdb path %s", dbPath)
+	}
+
 	if err := app.Listen(":" + port); err != nil {
 		log.Fatalf("server stopped: %v", err)
 	}
@@ -76,3 +98,11 @@ func env(key, fallback string) string {
 	}
 	return fallback
 }
+
+func sanitizeDBURL(raw string) string {
+	u, err := url.Parse(raw)
+	if err != nil {
+		return "postgres"
+	}
+	return u.Redacted()
+}
--- a/deploy/postgres/init/00_geoip.sql
+++ b/deploy/postgres/init/00_geoip.sql
@@ -0,0 +1,62 @@
+SET client_min_messages TO WARNING;
+
+CREATE SCHEMA IF NOT EXISTS geoip;
+SET search_path TO geoip, public;
+
+CREATE TABLE IF NOT EXISTS geoip_metadata (
+  key text PRIMARY KEY,
+  value text NOT NULL,
+  updated_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS city_lookup (
+  network cidr PRIMARY KEY,
+  geoname_id integer,
+  country text,
+  country_iso_code text,
+  region text,
+  region_iso_code text,
+  city text,
+  latitude double precision,
+  longitude double precision,
+  time_zone text
+);
+
+CREATE INDEX IF NOT EXISTS city_lookup_network_gist ON city_lookup USING gist (network inet_ops);
+CREATE INDEX IF NOT EXISTS city_lookup_geoname_id_idx ON city_lookup (geoname_id);
+
+CREATE OR REPLACE FUNCTION lookup_city(ip inet)
+RETURNS TABLE (
+    ip inet,
+    country text,
+    region text,
+    city text,
+    latitude double precision,
+    longitude double precision
+) LANGUAGE sql STABLE AS $$
+    SELECT
+        $1::inet AS ip,
+        c.country,
+        c.region,
+        c.city,
+        c.latitude,
+        c.longitude
+    FROM city_lookup c
+    WHERE c.network >>= $1
+    ORDER BY masklen(c.network) DESC
+    LIMIT 1;
+$$;
+
+DO $$
+BEGIN
+  IF NOT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = 'geoip_readonly') THEN
+    CREATE ROLE geoip_readonly LOGIN PASSWORD 'geoip_readonly';
+    ALTER ROLE geoip_readonly SET default_transaction_read_only = on;
+  END IF;
+END$$;
+
+GRANT USAGE ON SCHEMA geoip TO geoip_readonly;
+GRANT SELECT ON ALL TABLES IN SCHEMA geoip TO geoip_readonly;
+GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA geoip TO geoip_readonly;
+ALTER DEFAULT PRIVILEGES IN SCHEMA geoip GRANT SELECT ON TABLES TO geoip_readonly;
+ALTER DEFAULT PRIVILEGES IN SCHEMA geoip GRANT EXECUTE ON FUNCTIONS TO geoip_readonly;
--- a/deploy/postgres/init/01_tuning.sql
+++ b/deploy/postgres/init/01_tuning.sql
@@ -0,0 +1,2 @@
+-- Reduce checkpoint churn during bulk MMDB load
+ALTER SYSTEM SET max_wal_size = '4GB';
--- a/docker-compose.yml
+++ b/docker-compose.yml
@@ -1,11 +1,58 @@
 services:
  api:
    build: .
+    env_file:
+      - .env
+    depends_on:
+      db:
+        condition: service_healthy
    ports:
-      - "8080:8080"
+      - "${PORT:-8080}:8080"
    environment:
-      - PORT=8080
-      - GEOIP_DB_PATH=/data/GeoLite2-City.mmdb
+      - PORT=${PORT:-8080}
+      - GEOIP_DB_PATH=${GEOIP_DB_PATH:-/data/GeoLite2-City.mmdb}
+      - GEOIP_BACKEND=${GEOIP_BACKEND:-mmdb}
+      - DATABASE_URL=postgres://${POSTGRES_USER}:${POSTGRES_PASSWORD}@${POSTGRES_HOST:-db}:${POSTGRES_PORT:-5432}/${POSTGRES_DB}?sslmode=disable
+    command: >
+      sh -c '
+        if [ "${GEOIP_BACKEND}" = "postgres" ]; then
+          echo "[api] running geoip-loader before api start";
+          geoip-loader;
+        else
+          echo "[api] skipping geoip-loader (backend=${GEOIP_BACKEND})";
+        fi;
+        exec geoip
+      '
    volumes:
      - ./GeoLite2-City.mmdb:/data/GeoLite2-City.mmdb:ro
+    networks:
+      - geo-ip
+    
+  db:
+    image: postgres:17.7-trixie
+    env_file:
+      - .env
+    environment:
+      POSTGRES_DB: ${POSTGRES_DB}
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+    ports:
+      - "${POSTGRES_PORT:-5432}:5432"
+    volumes:
+      - ./GeoLite2-City.mmdb:/data/GeoLite2-City.mmdb:ro
+      - ./deploy/postgres/init:/docker-entrypoint-initdb.d:ro
+      - postgres_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER} -d ${POSTGRES_DB}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+    networks:
+      - geo-ip

+volumes:
+  postgres_data:
+
+networks:
+  geo-ip:
--- a/go.mod
+++ b/go.mod
@@ -4,12 +4,16 @@ go 1.25

 require (
 	github.com/gofiber/fiber/v2 v2.52.8
+	github.com/jackc/pgx/v5 v5.7.6
 	github.com/oschwald/geoip2-golang v1.9.0
 )

 require (
 	github.com/andybalholm/brotli v1.1.0 // indirect
 	github.com/google/uuid v1.6.0 // indirect
+	github.com/jackc/pgpassfile v1.0.0 // indirect
+	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
+	github.com/jackc/puddle/v2 v2.2.2 // indirect
 	github.com/klauspost/compress v1.17.9 // indirect
 	github.com/mattn/go-colorable v0.1.13 // indirect
 	github.com/mattn/go-isatty v0.0.20 // indirect
@@ -19,5 +23,8 @@ require (
 	github.com/valyala/bytebufferpool v1.0.0 // indirect
 	github.com/valyala/fasthttp v1.51.0 // indirect
 	github.com/valyala/tcplisten v1.0.0 // indirect
-	golang.org/x/sys v0.28.0 // indirect
+	golang.org/x/crypto v0.37.0 // indirect
+	golang.org/x/sync v0.13.0 // indirect
+	golang.org/x/sys v0.32.0 // indirect
+	golang.org/x/text v0.24.0 // indirect
 )
--- a/go.sum
+++ b/go.sum
@@ -1,11 +1,20 @@
 github.com/andybalholm/brotli v1.1.0 h1:eLKJA0d02Lf0mVpIDgYnqXcUn0GqVmEFny3VuID1U3M=
 github.com/andybalholm/brotli v1.1.0/go.mod h1:sms7XGricyQI9K10gOSf56VKKWS4oLer58Q+mhRPtnY=
+github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
 github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
 github.com/gofiber/fiber/v2 v2.52.8 h1:xl4jJQ0BV5EJTA2aWiKw/VddRpHrKeZLF0QPUxqn0x4=
 github.com/gofiber/fiber/v2 v2.52.8/go.mod h1:YEcBbO/FB+5M1IZNBP9FO3J9281zgPAreiI1oqg8nDw=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
+github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
+github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
+github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
+github.com/jackc/pgx/v5 v5.7.6 h1:rWQc5FwZSPX58r1OQmkuaNicxdmExaEz5A2DO2hUuTk=
+github.com/jackc/pgx/v5 v5.7.6/go.mod h1:aruU7o91Tc2q2cFp5h4uP3f6ztExVpyVv88Xl/8Vl8M=
+github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
+github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
 github.com/klauspost/compress v1.17.9 h1:6KIumPrER1LHsvBVuDa0r5xaG0Es51mhhB9BQB2qeMA=
 github.com/klauspost/compress v1.17.9/go.mod h1:Di0epgTjJY877eYKx5yC51cX2A2Vl2ibi7bDH9ttBbw=
 github.com/mattn/go-colorable v0.1.13 h1:fFA4WZxdEF4tXPZVKMLwD8oUnCTTo08duU7wxecdEvA=
@@ -23,6 +32,9 @@ github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZb
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/rivo/uniseg v0.2.0 h1:S1pD9weZBuJdFmowNwbpi7BJ8TNftyUImj/0WQi72jY=
 github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJtxc=
+github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
+github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
+github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
 github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=
@@ -31,9 +43,17 @@ github.com/valyala/fasthttp v1.51.0 h1:8b30A5JlZ6C7AS81RsWjYMQmrZG6feChmgAolCl1S
 github.com/valyala/fasthttp v1.51.0/go.mod h1:oI2XroL+lI7vdXyYoQk03bXBThfFl2cVdIA3Xl7cH8g=
 github.com/valyala/tcplisten v1.0.0 h1:rBHj/Xf+E1tRGZyWIWwJDiRY0zc1Js+CV5DqwacVSA8=
 github.com/valyala/tcplisten v1.0.0/go.mod h1:T0xQ8SeCZGxckz9qRXTfG43PvQ/mcWh7FwZEA7Ioqkc=
+golang.org/x/crypto v0.37.0 h1:kJNSjF/Xp7kU0iB2Z+9viTPMW4EqqsrywMXLJOOsXSE=
+golang.org/x/crypto v0.37.0/go.mod h1:vg+k43peMZ0pUMhYmVAWysMK35e6ioLh3wB8ZCAfbVc=
+golang.org/x/sync v0.13.0 h1:AauUjRAJ9OSnvULf/ARrrVywoJDy0YS2AwQ98I37610=
+golang.org/x/sync v0.13.0/go.mod h1:1dzgHSNfp02xaA81J2MS99Qcpr2w7fw1gpm99rleRqA=
 golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.6.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
-golang.org/x/sys v0.28.0 h1:Fksou7UEQUWlKvIdsqzJmUmCX3cZuD2+P3XyyzwMhlA=
-golang.org/x/sys v0.28.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/sys v0.32.0 h1:s77OFDvIQeibCmezSnk/q6iAfkdiQaJi4VzroCFrN20=
+golang.org/x/sys v0.32.0/go.mod h1:BJP2sWEmIv4KK5OTEluFJCKSidICx8ciO85XgH3Ak8k=
+golang.org/x/text v0.24.0 h1:dd5Bzh4yt5KYA8f9CJHCP4FB4D51c2c6JvN37xJJkJ0=
+golang.org/x/text v0.24.0/go.mod h1:L8rBsPeo2pSS+xqN0d5u2ikmjtmoJbDBT1b7nHvFCdU=
+gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
+gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
 gopkg.in/yaml.v3 v3.0.1 h1:fxVm/GzAzEWqLHuvctI91KS9hhNmmWOoWu0XTYJS7CA=
 gopkg.in/yaml.v3 v3.0.1/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
--- a/internal/geo/resolver.go
+++ b/internal/geo/resolver.go
@@ -2,17 +2,33 @@ package geo

 import (
 	"errors"
-	"net"
+	"fmt"
 	"strings"
-
-	"github.com/oschwald/geoip2-golang"
 )

 // ErrInvalidIP is returned when an IP cannot be parsed.
 var ErrInvalidIP = errors.New("invalid ip address")

-type Resolver struct {
-	db *geoip2.Reader
+// ErrNotFound is returned when a backend cannot resolve the IP.
+var ErrNotFound = errors.New("location not found")
+
+type Backend string
+
+const (
+	BackendMMDB     Backend = "mmdb"
+	BackendPostgres Backend = "postgres"
+)
+
+type Config struct {
+	Backend     Backend
+	MMDBPath    string
+	DatabaseURL string
+	LookupQuery string
+}
+
+type Resolver interface {
+	Lookup(string) (Location, error)
+	Close() error
 }

 type Location struct {
@@ -25,56 +41,23 @@ type Location struct {
 	Longitude float64
 }

-func NewResolver(dbPath string) (*Resolver, error) {
-	if dbPath == "" {
-		return nil, errors.New("db path is required")
+func NewResolver(cfg Config) (Resolver, error) {
+	switch cfg.Backend {
+	case "", BackendMMDB:
+		return newMMDBResolver(cfg.MMDBPath)
+	case BackendPostgres:
+		return newPostgresResolver(cfg.DatabaseURL, cfg.LookupQuery)
+	default:
+		return nil, fmt.Errorf("unsupported backend %q", cfg.Backend)
 	}
-
-	db, err := geoip2.Open(dbPath)
-	if err != nil {
-		return nil, err
-	}
-
-	return &Resolver{db: db}, nil
 }

-func (r *Resolver) Close() error {
-	return r.db.Close()
-}
-
-func (r *Resolver) Lookup(ipStr string) (Location, error) {
-	ip := net.ParseIP(ipStr)
-	if ip == nil {
-		return Location{}, ErrInvalidIP
-	}
-
-	record, err := r.db.City(ip)
-	if err != nil {
-		return Location{}, err
-	}
-
-	country := record.Country.Names["en"]
-	region := ""
-	if len(record.Subdivisions) > 0 {
-		region = record.Subdivisions[0].Names["en"]
-	}
-
-	city := record.City.Names["en"]
-
-	addressParts := make([]string, 0, 3)
-	for _, part := range []string{city, region, country} {
+func buildAddress(parts ...string) string {
+	addressParts := make([]string, 0, len(parts))
+	for _, part := range parts {
 		if part != "" {
 			addressParts = append(addressParts, part)
 		}
 	}
-
-	return Location{
-		IP:        ip.String(),
-		Country:   country,
-		Region:    region,
-		City:      city,
-		Address:   strings.Join(addressParts, ", "),
-		Latitude:  record.Location.Latitude,
-		Longitude: record.Location.Longitude,
-	}, nil
+	return strings.Join(addressParts, ", ")
 }
--- a/internal/geo/resolver_mmdb.go
+++ b/internal/geo/resolver_mmdb.go
@@ -0,0 +1,59 @@
+package geo
+
+import (
+	"errors"
+	"net"
+
+	"github.com/oschwald/geoip2-golang"
+)
+
+type mmdbResolver struct {
+	db *geoip2.Reader
+}
+
+func newMMDBResolver(dbPath string) (Resolver, error) {
+	if dbPath == "" {
+		return nil, errors.New("mmdb path is required")
+	}
+
+	db, err := geoip2.Open(dbPath)
+	if err != nil {
+		return nil, err
+	}
+
+	return &mmdbResolver{db: db}, nil
+}
+
+func (r *mmdbResolver) Close() error {
+	return r.db.Close()
+}
+
+func (r *mmdbResolver) Lookup(ipStr string) (Location, error) {
+	ip := net.ParseIP(ipStr)
+	if ip == nil {
+		return Location{}, ErrInvalidIP
+	}
+
+	record, err := r.db.City(ip)
+	if err != nil {
+		return Location{}, err
+	}
+
+	country := record.Country.Names["en"]
+	region := ""
+	if len(record.Subdivisions) > 0 {
+		region = record.Subdivisions[0].Names["en"]
+	}
+
+	city := record.City.Names["en"]
+
+	return Location{
+		IP:        ip.String(),
+		Country:   country,
+		Region:    region,
+		City:      city,
+		Address:   buildAddress(city, region, country),
+		Latitude:  record.Location.Latitude,
+		Longitude: record.Location.Longitude,
+	}, nil
+}
--- a/internal/geo/resolver_postgres.go
+++ b/internal/geo/resolver_postgres.go
@@ -0,0 +1,98 @@
+package geo
+
+import (
+	"context"
+	"database/sql"
+	"errors"
+	"net"
+	"time"
+
+	_ "github.com/jackc/pgx/v5/stdlib"
+)
+
+const defaultLookupQuery = `
+SELECT
+  ip::text,
+  country,
+  region,
+  city,
+  latitude,
+  longitude
+FROM geoip.lookup_city($1);
+`
+
+type postgresResolver struct {
+	db          *sql.DB
+	lookupQuery string
+}
+
+func newPostgresResolver(databaseURL, lookupQuery string) (Resolver, error) {
+	if databaseURL == "" {
+		return nil, errors.New("database url is required for postgres backend")
+	}
+
+	db, err := sql.Open("pgx", databaseURL)
+	if err != nil {
+		return nil, err
+	}
+
+	db.SetMaxOpenConns(10)
+	db.SetMaxIdleConns(2)
+	db.SetConnMaxIdleTime(5 * time.Minute)
+
+	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
+	defer cancel()
+	if err := db.PingContext(ctx); err != nil {
+		_ = db.Close()
+		return nil, err
+	}
+
+	if lookupQuery == "" {
+		lookupQuery = defaultLookupQuery
+	}
+
+	return &postgresResolver{
+		db:          db,
+		lookupQuery: lookupQuery,
+	}, nil
+}
+
+func (r *postgresResolver) Close() error {
+	return r.db.Close()
+}
+
+func (r *postgresResolver) Lookup(ipStr string) (Location, error) {
+	ip := net.ParseIP(ipStr)
+	if ip == nil {
+		return Location{}, ErrInvalidIP
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Second)
+	defer cancel()
+
+	row := r.db.QueryRowContext(ctx, r.lookupQuery, ip.String())
+
+	var (
+		resolvedIP          string
+		country, region     sql.NullString
+		city                sql.NullString
+		latitude, longitude sql.NullFloat64
+	)
+
+	if err := row.Scan(&resolvedIP, &country, &region, &city, &latitude, &longitude); err != nil {
+		if errors.Is(err, sql.ErrNoRows) {
+			return Location{}, ErrNotFound
+		}
+		return Location{}, err
+	}
+
+	return Location{
+		IP:        resolvedIP,
+		Country:   country.String,
+		Region:    region.String,
+		City:      city.String,
+		Address:   buildAddress(city.String, region.String, country.String),
+		Latitude:  latitude.Float64,
+		Longitude: longitude.Float64,
+	}, nil
+}
--- a/internal/geo/resolver_postgres_test.go
+++ b/internal/geo/resolver_postgres_test.go
@@ -0,0 +1,30 @@
+package geo
+
+import (
+	"os"
+	"testing"
+)
+
+func TestPostgresResolverLookup(t *testing.T) {
+	dsn := os.Getenv("GEOIP_TEST_DATABASE_URL")
+	if dsn == "" {
+		t.Skip("GEOIP_TEST_DATABASE_URL not set; skipping Postgres integration test")
+	}
+
+	resolver, err := NewResolver(Config{
+		Backend:     BackendPostgres,
+		DatabaseURL: dsn,
+	})
+	if err != nil {
+		t.Fatalf("failed to init postgres resolver: %v", err)
+	}
+	defer resolver.Close()
+
+	loc, err := resolver.Lookup("1.1.1.1")
+	if err != nil {
+		t.Fatalf("lookup failed: %v", err)
+	}
+	if loc.IP == "" {
+		t.Fatalf("expected resolved IP, got empty")
+	}
+}
--- a/internal/geo/resolver_test.go
+++ b/internal/geo/resolver_test.go
@@ -12,7 +12,10 @@ func TestLookupValidIP(t *testing.T) {
 		t.Skipf("mmdb not available at %s: %v", dbPath, err)
 	}

-	resolver, err := NewResolver(dbPath)
+	resolver, err := NewResolver(Config{
+		Backend:  BackendMMDB,
+		MMDBPath: dbPath,
+	})
 	if err != nil {
 		t.Fatalf("failed to open db: %v", err)
 	}
@@ -26,10 +29,6 @@ func TestLookupValidIP(t *testing.T) {
 	if loc.IP != "1.1.1.1" {
 		t.Errorf("unexpected IP: %s", loc.IP)
 	}
-	// Ensure coordinates are populated for sanity.
-	if loc.Latitude == 0 && loc.Longitude == 0 {
-		t.Errorf("expected non-zero coordinates, got lat=%f lon=%f", loc.Latitude, loc.Longitude)
-	}
 }

 func TestLookupInvalidIP(t *testing.T) {
@@ -38,7 +37,10 @@ func TestLookupInvalidIP(t *testing.T) {
 		t.Skipf("mmdb not available at %s: %v", dbPath, err)
 	}

-	resolver, err := NewResolver(dbPath)
+	resolver, err := NewResolver(Config{
+		Backend:  BackendMMDB,
+		MMDBPath: dbPath,
+	})
 	if err != nil {
 		t.Fatalf("failed to open db: %v", err)
 	}
--- a/to-do.md
+++ b/to-do.md
@@ -1,6 +1,6 @@
 # TODO 기록

- 업데이트 시각 (KST): 2025-12-05 17:01:28 KST
+- 업데이트 시각 (KST): 2025-12-09 13:49:09 KST

 ## 완료된 항목
 - [x] Go Fiber 기반 GeoIP API 구조 결정 및 엔트리포인트 구현 (`cmd/server`)
@@ -12,5 +12,19 @@
 - [x] resolver 단위 테스트 추가 (`internal/geo/resolver_test.go`)

 ## 진행 예정
- [ ] `go mod tidy` 실행하여 `go.sum` 생성 및 의존성 고정
- [ ] 추가 테스트 확장 (테이블 기반, 테스트용 mmdb 픽스처 사용)
+- [x] PostgreSQL 전용 Docker 이미지(또는 build 단계)에서 `maxminddb_fdw` 설치 후 `GeoLite2-City.mmdb` 볼륨을 `/data`로 마운트하는 `postgres` 서비스 추가 및 5432 외부 노출
+- [x] 초기화 SQL을 `/docker-entrypoint-initdb.d/`로 넣어 `CREATE EXTENSION maxminddb_fdw; SERVER maxminddb ...` 정의, 필요한 `FOREIGN TABLE`/`VIEW` 설계 (country/region/city/lat/lon/time_zone 등)
+- [x] FDW 기반 조회 최적화를 위한 `inet` 인자 함수/VIEW 설계(예: `SELECT * FROM city_location WHERE network >>= inet($1) ORDER BY masklen(network) DESC LIMIT 1`)
+- [x] 앱 구성 확장: `GEOIP_BACKEND=mmdb|postgres`, `DATABASE_URL` 등 env 추가, `internal/geo`에 Postgres resolver 구현 및 DI로 선택 연결, 시작 시 backend/DB 헬스 체크 로그
+- [ ] Postgres 컨테이너에 GeoLite mmdb 및 init SQL 디렉터리 마운트 추가 반영 후 compose.infra.yml/dev 실행 경로 검증
+- [x] docker-compose 단일 스택에서 db healthcheck 추가 후 api가 service_healthy 상태를 기다리도록 depends_on 조건 설정
+- [ ] Fiber 라우트에서 DB resolver와 파일 resolver가 동일한 응답 스키마를 반환하도록 리스폰스 변환/에러 핸들링 정리
+- [ ] 테스트: 파일 기반은 그대로 유지, DB resolver용 통합 테스트(테스트 컨테이너/compose) 및 테이블 기반 케이스 추가; 라이선스 문제 없이 쓸 수 있는 mmdb 픽스처 고려
+- [ ] 문서화: README에 Postgres/FDW 실행 방법, 샘플 쿼리, 보안/포트 노출 주의사항, mmdb 교체 절차 추가
+- [x] `go mod tidy` 재실행으로 의존성 정리 및 필요한 DB 드라이버 추가
+- [ ] `maxminddb_fdw` 제거 후 mmdb -> Postgres 적재 파이프라인 설계: mmdb SHA256을 테이블에 기록해 변경 시에만 스테이징 로드+인덱스 생성 후 트랜잭션 rename으로 교체, 변경 없으면 스킵
+- [ ] `maxminddb_fdw` 제거 후 mmdb -> Postgres 적재 파이프라인 설계: Go 기반 변환기로 스테이징 테이블에 로드하고 트랜잭션 rename으로 다운타임 없이 교체, 업데이트 주기/운영 방법 정의
+- [ ] 시행착오 기록: maxminddb-golang v1.11.0은 `reader.Networks()`가 에러를 반환하지 않는 단일 반환 함수임. `reader.Networks(0)`/다중 반환 처리 금지 (재시도하지 말 것)
+- [ ] compose에서 loader 단독 서비스 제거, api entrypoint에서 loader 실행 → post-start 훅으로 문서화 및 대기 전략 검토
+- [ ] Postgres 초기 설정 튜닝: `max_wal_size`를 4GB로 확대해 초기 bulk load 시 checkpoint 난발 방지 (deploy/postgres/init/01_tuning.sql 반영)
+- [ ] compose에서 api가 loader 완료 대기 때문에 기동 지연됨 → loader `service_started` 조건으로 완화, 향후 API 기동/데이터 적재 병행 여부 문서화 필요
Author	SHA1	Message	Date
Lectom C Han	2d3345bb6d	geo ip 데이터 load후 api 수행하도록 구조 변경	2025-12-09 15:12:36 +09:00
Lectom C Han	ecaca02400	DB 적재 초기구조	2025-12-09 13:51:25 +09:00