[Feat] PostgreSQL 17 및 pgvector 0.8.1 로컬 실행 환경 지원 추가 구현

[Gimini-3]

배경

현재 로컬 DB 실행 경로는 다음과 같이 OpenSQL/PostgreSQL 14.6 환경에 강하게 결합되어 있다.

• docker/opensql/Dockerfile: tmaxopensql/postgres:14.6 기반 및 pgvector 0.8.0 소스 빌드
• docker/opensql/init-and-start.sh: /usr/pgsql-14, /var/lib/pgsql/14/data 경로 사용
• docker-compose.yml: linux/amd64 강제, opensql_data 볼륨과 PostgreSQL 14 전용 Health Check 사용
• Local/Test Datasource: 로컬 컨테이너 기본 설정과 맞지 않는 sslmode=require 기본값
• Claim 성능 Benchmark: PostgreSQL 14.6 버전을 실행 전제조건으로 고정
• README와 로컬 DB 문서: 더 이상 사용할 수 없는 14.6 실행 절차 안내

공식 OpenSQL 설치 환경은 Rocky Linux 9.7 x86-64 단일 서버로 제한되므로 macOS 개발 환경에서 직접 실행하는 기준으로 사용할 수 없다. 로컬 개발은 PostgreSQL 17 + pgvector 0.8.1로 표준화하고, 공식 OpenSQL 17.8 환경 검증은 별도 원격 환경에서 수행한다.

목표

• macOS arm64 및 일반 x86-64 개발 환경에서 동일한 로컬 DB를 실행할 수 있도록 구성
• PostgreSQL 17과 pgvector 0.8.1 버전을 재현 가능하게 고정
• 기존 JDBC, Flyway, vector(1024), HNSW 검색 계약 유지
• PostgreSQL 14 데이터 볼륨을 잘못 재사용하지 않는 안전한 전환
• 공급사 설치 파일, 라이선스, 다운로드 정보와 비밀정보가 Git 저장소나 Docker Build Context에 포함되지 않도록 경계 명시
• 공식 OpenSQL 원격 검증으로 이어질 수 있도록 로컬/공식 환경의 공통 검증 SQL과 차이점 문서화

핵심 설계

1. 로컬 DB 이미지

• 공개 공식 이미지 pgvector/pgvector:0.8.1-pg17을 사용한다.
• 기존 공급사 이미지 위에 pgvector를 직접 컴파일하는 Custom Dockerfile은 로컬 기본 경로에서 제거한다.
• platform: linux/amd64 강제를 제거하고 이미지 Manifest가 호스트 아키텍처를 선택하도록 한다.
• 이미지의 공식 PostgreSQL Entry Point와 POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD 계약을 사용한다.
• DB 비밀번호는 기존과 같이 환경변수로 주입하며 Repository 설정 파일에 실제 운영 비밀정보를 추가하지 않는다.

2. pgvector 초기화 및 Flyway 순서

• docker-entrypoint-initdb.d 아래 초기화 SQL로 대상 DB에 CREATE EXTENSION IF NOT EXISTS vector를 실행한다.
• pgvector Extension은 Flyway가 V32의 vector(1024) 타입과 HNSW 인덱스를 적용하기 전에 준비되어야 한다.
• 기존 Flyway Migration과 Java float[]/PGobject 매핑은 변경하지 않는다.
• Application 기동 시 Flyway 전체 적용 후 Hibernate ddl-auto=validate가 통과해야 한다.

3. 데이터 볼륨 분리

• PostgreSQL 14용 opensql_data를 PostgreSQL 17에서 재사용하지 않는다.
• PostgreSQL 17 전용 새 Named Volume과 표준 경로 /var/lib/postgresql/data를 사용한다.
• 기존 볼륨은 자동 삭제하거나 변환하지 않는다. 필요한 데이터 이전은 별도 백업/복원 작업으로 분리한다.
• Rollback 시 기존 14 볼륨이 그대로 남아 있어야 한다.

4. Compose와 Health Check

• PostgreSQL 17 표준 pg_isready 경로를 사용한다.
• Health Check의 사용자와 DB 이름은 Compose 환경변수 기본값과 동일한 값에서 해석한다.
• 기본 포트 55432, DB app, 사용자 app 계약은 유지한다.
• PostgreSQL Service만 단독 기동해도 Extension과 Application Schema 준비가 가능해야 한다.
• MinIO, Embedding Server, Ollama 구성은 이 작업에서 변경하지 않는다.

5. Local/Test 연결 계약

• 암호화되지 않은 로컬 Docker 연결의 기본 DB_SSLMODE를 disable로 맞춘다.
• 환경변수로 다른 SSL Mode를 덮어쓸 수 있는 계약은 유지한다.
• Production Datasource와 운영 비밀정보 주입 방식은 변경하지 않는다.
• Test Profile의 격리 Schema와 public Search Path를 유지해 pgvector 타입을 찾을 수 있어야 한다.

6. Benchmark 환경 가드

• Claim 성능 Benchmark의 PostgreSQL 실행 전제조건을 17 계열로 갱신한다.
• pgvector Extension 존재 여부만 확인하지 않고 extversion = 0.8.1을 검증한다.
• 실행 결과 Fingerprint에 PostgreSQL과 pgvector 실제 버전을 계속 기록한다.
• 성능 기준값 자체를 이번 작업에서 재정의하지 않는다. 새 환경 측정값은 실행 결과 문서에 별도로 남긴다.

7. 공급사 파일과 라이선스 경계

• OpenSQL 설치 Archive, 압축 해제 비밀번호, 다운로드 URL, 라이선스 XML은 Repository 내부에 두지 않는다.
• 해당 파일은 Repository 외부의 접근 제한 디렉터리 또는 원격 Rocky Linux 9.7 서버에서만 관리한다.
• Docker Build Context에 공급사 파일을 복사하거나 Mount하지 않는다.
• 문서에는 설치 파일 자체가 아니라 공식 원격 검증의 환경 조건과 안전한 절차만 기록한다.

변경 대상

• docker-compose.yml
• 로컬 PostgreSQL 초기화 SQL 및 관련 Docker 디렉터리
• src/main/resources/application-local.yml
• src/main/resources/application-test.yml
• src/test/java/.../EmbeddingJobClaimPerformanceBenchmark.java
• README.md 및 현재 로컬 DB 실행 문서
• 상세 설계 docs/design/
• 실제 실행 결과 docs/test-results/
• 필요 시 공급사 로컬 파일 유입 방지를 위한 제한적인 .gitignore 규칙

과거 환경에서 작성된 기존 docs/test-results/ 문서는 당시 실행 사실을 보존해야 하므로 소급 수정하지 않는다.

제외 범위

• 공식 OpenSQL 17.8 설치 파일 또는 라이선스의 Repository 포함
• Rocky Linux 9.7 원격 서버 생성, 공급사 라이선스 재발급 및 실제 설치
• PostgreSQL 14 데이터의 자동 In-place Upgrade
• Flyway Schema 또는 Vector 차원 변경
• pgvector 0.8.1 이외의 최신 버전 자동 추종
• pgvectorscale 도입
• Embedding Model, Chunking 규칙, 검색 Ranking 로직 변경
• MinIO, Embedding Server, Ollama 구성 변경
• 과거 테스트 결과 문서의 버전 표기 변경

검증 계획

정적 검증

• docker compose config
• Repository와 Build Context에 공급사 Archive/License/비밀정보가 없는지 확인
• Compose에서 PostgreSQL 14 전용 경로, 이미지, 강제 아키텍처와 기존 볼륨 참조가 제거됐는지 확인

DB 실행 검증

1. PostgreSQL 17 전용 새 볼륨으로 DB 기동
2. SHOW server_version 결과가 17 계열인지 확인
3. SELECT extversion FROM pg_extension WHERE extname = 'vector' 결과가 0.8.1인지 확인
4. Flyway 전체 Migration 적용
5. embeddings.vector가 vector(1024)인지 확인
6. embeddings에 HNSW/코사인 연산자 인덱스가 생성됐는지 확인
7. Application Local Profile 기동과 Hibernate Schema Validation 확인

회귀 검증

• ./gradlew test
• 실제 PostgreSQL이 필요한 Claim 동시성 통합 테스트
• 문서 인덱싱 완료/실패/Lease 복구/Worker Polling 통합 테스트
• Vector 저장 및 검색 경로 검증
• Claim 성능 Benchmark의 환경 사전검증과 짧은 Smoke 실행
• 실행 환경과 결과를 docs/test-results/에 기록

완료 조건

• pgvector/pgvector:0.8.1-pg17 기반 로컬 DB가 호스트 아키텍처 강제 없이 기동된다.
• PostgreSQL 실제 버전은 17 계열, pgvector 실제 버전은 0.8.1이다.
• PostgreSQL 14의 opensql_data를 재사용하거나 삭제하지 않는다.
• Vector Extension이 Flyway보다 먼저 생성된다.
• Flyway 전체 Migration과 Hibernate Schema Validation이 통과한다.
• vector(1024) 저장과 HNSW 인덱스가 유지된다.
• Local/Test 기본 연결이 로컬 컨테이너의 SSL 설정과 일치한다.
• Production Datasource 계약은 변경되지 않는다.
• Benchmark가 PostgreSQL 17 + pgvector 0.8.1이 아닌 환경을 명확하게 거부한다.
• README와 현재 로컬 DB 문서가 새 실행·검증·Rollback 절차를 안내한다.
• 공급사 Archive, 라이선스, URL, 비밀번호와 실제 비밀정보가 Git 추적 대상 및 Docker Build Context에 포함되지 않는다.
• 전체 테스트와 실제 PostgreSQL 회귀 검증이 통과하고 결과가 기록된다.

후속 작업

공식 OpenSQL 17.8은 Rocky Linux 9.7 x86-64 단일 원격 환경에 설치한 뒤, 이 작업에서 확정한 공통 검증 SQL과 Application 회귀 시나리오로 별도 검증한다. 로컬 PostgreSQL과 공식 OpenSQL의 결과 차이는 독립된 호환성 이슈로 관리한다.

[Gimini-3]

팀 적용 안내

이 변경은 공식 OpenSQL 지원을 제거하는 작업이 아니라, 로컬 개발 환경과 공식 호환성 검증 환경을 분리하는 작업입니다.

PR 병합 후 로컬 적용

git pull
docker compose pull postgres
docker compose up -d postgres
docker compose ps

기본 로컬 계약은 다음과 같습니다.

• 이미지: pgvector/pgvector:0.8.1-pg17
• PostgreSQL: 17 계열
• pgvector: 0.8.1
• 접속: localhost:55432
• Database/User: app / app
• 로컬 DB_SSLMODE: disable
• 신규 볼륨: docgrid_postgres17_data

반드시 확인할 주의사항

• 기존 opensql_data 볼륨은 자동 이전하거나 삭제하지 않습니다.
• PostgreSQL Major Version이 다른 Data Directory를 직접 재사용하지 않습니다.
• docker compose down -v를 실행하지 마세요. PostgreSQL뿐 아니라 다른 서비스 볼륨까지 삭제될 수 있습니다.
• OpenSQL 설치 Archive, 라이선스, 다운로드 정보, 암호와 원격 인증정보는 Commit·Issue·Log에 기록하지 않습니다.
• 공급사 파일을 로컬에 둘 경우 Git에서 제외된 .local-vendor/만 사용합니다.
• Claim Benchmark는 PostgreSQL 17 + pgvector 0.8.1이 아닌 환경을 의도적으로 거부합니다.

현재 검증 결과

• PostgreSQL 17.8 / pgvector 0.8.1 기동 확인
• Flyway 37개 Migration 적용 및 Hibernate Schema Validation 확인
• vector(1024)와 HNSW cosine index 확인
• 전체 테스트, Claim 동시성 테스트, 축소 Benchmark와 Gradle Build 성공
• 기존 opensql_data 볼륨 보존 확인

자세한 실행·복구 절차는 PR 병합 후 docs/local-db.md를 기준으로 진행합니다. 공식 OpenSQL 17.8 호환성은 Rocky Linux 9.7 x86-64 Single 원격 환경에서 별도로 검증하고, 차이가 있으면 독립 호환성 이슈로 관리합니다.