Skip to content

공식 OpenSQL 17.8 호환성 및 성능 검증 추가 - #126

Merged
Gimini-3 merged 6 commits into
developfrom
feature/124
Aug 8, 2026
Merged

공식 OpenSQL 17.8 호환성 및 성능 검증 추가#126
Gimini-3 merged 6 commits into
developfrom
feature/124

Conversation

@Gimini-3

@Gimini-3 Gimini-3 commented Aug 8, 2026

Copy link
Copy Markdown
Contributor

변경 내용

  • 공식 OpenSQL 접속 환경 변수를 검증하고 전용 호환성·동시성·E2E·성능 작업을 추가했습니다.
  • PostgreSQL 17.8, pgvector 0.8.1, vector(1024), HNSW, <=>, SKIP LOCKED를 실제 DB에서 검증합니다.
  • Rocky Linux 9.7 x86-64 Single 환경 사전 점검 스크립트와 재현 Runbook을 추가했습니다.
  • 공식 배포본에서 수행한 Vector 검색 및 Claim 성능 결과를 민감정보 없이 기록했습니다.

검증

  • openSqlVerification: 성공
    • 호환성 3개
    • Claim·Lease·Worker 10개
    • 실제 문서/BGE-M3 전체 관통 2개
    • Claim 성능 1개(5,000 Jobs × 5회 × Worker 1/5/10/20/40)
  • 일반 테스트 강제 재실행: 709개 성공, failure/error/skipped 0
  • 25회 성능 측정에서 Worker 오류, 중복 Claim Token, 소유권 누락, Rollback, Deadlock 0건

검증 환경과 남은 확인

공급사 OpenSQL 3.17.8.7 배포본을 Rocky Linux 9.7 x86-64 Single 컨테이너에서 검증했습니다. Apple Silicon Host의 linux/amd64 에뮬레이션 경계이므로 기능 호환성 결과는 유효하지만, 성능값은 SLO로 사용하지 않습니다. 공급사 지원 VM 또는 원격 서버의 최종 인수 검증은 같은 Runbook으로 한 번 더 실행해야 하므로 이슈는 자동으로 닫지 않습니다.

설치 번들, 라이선스, 다운로드 정보, 접속 Secret은 Git 변경에 포함하지 않았습니다.

Related to #124

Summary by CodeRabbit

  • 새로운 기능

    • OpenSQL 17.8 환경의 호환성 및 성능을 검증하는 전용 테스트 명령을 추가했습니다.
    • 벡터 검색, 문서 인덱싱, Claim 동시성 및 성능 검증을 순차적으로 실행할 수 있습니다.
    • 실행 전 호스트 환경, 데이터베이스 연결, PostgreSQL 및 pgvector 버전을 자동 점검합니다.
  • 문서

    • OpenSQL 설치 조건, 검증 절차, 실행 방법 및 결과 기록을 안내하는 설계 문서와 Runbook을 추가했습니다.
    • 검증 결과와 환경별 제한 사항을 문서화했습니다.

@coderabbitai

coderabbitai Bot commented Aug 8, 2026

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@Gimini-3, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 45 minutes

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 71636d95-2afd-4b9b-b52b-7c8ee7cee2bc

📥 Commits

Reviewing files that changed from the base of the PR and between 59a202a and e105314.

📒 Files selected for processing (6)
  • build.gradle
  • docs/design/gimin-#124-opensql-compatibility-performance.md
  • docs/test-results/gimin-#124-opensql-compatibility-performance.md
  • docs/test-results/gimin-#124-opensql-verification-runbook.md
  • scripts/opensql/verify-host.sh
  • src/test/java/com/opensource/docgrid/opensql/OpenSqlCompatibilityIntegrationTest.java
📝 Walkthrough

Walkthrough

OpenSQL 17.8 및 pgvector 0.8.1 환경을 검증하는 호스트 점검 스크립트, 통합 테스트, 전용 Gradle 태스크와 실행 문서를 추가했다. 호환성 테스트는 Flyway, vector, HNSW, Top-K, SKIP LOCKED 동작과 지연 percentile을 확인한다.

Changes

OpenSQL 검증

Layer / File(s) Summary
검증 범위와 계약
docs/design/..., docs/test-results/gimin-#124-opensql-verification-runbook.md
OpenSQL 호스트 조건, 검증 범위, 성능 측정, 결과 기록 및 민감정보 제외 규칙을 문서화했다.
호스트 사전 점검
scripts/opensql/verify-host.sh, docs/test-results/gimin-#124-opensql-verification-runbook.md
필수 환경 변수, Rocky Linux 9.7 x86_64 Single 조건, PostgreSQL 17.8 계열과 pgvector 0.8.1을 확인한다.
호환성 프로브 구현
src/test/java/com/opensource/docgrid/opensql/OpenSqlCompatibilityIntegrationTest.java, docs/test-results/gimin-#124-opensql-verification-runbook.md
격리된 Schema에서 Flyway, vector 컬럼, HNSW cosine 검색, Top-K 결과, 지연 percentile, SKIP LOCKED 동작을 검증한다.
검증 태스크와 실행 기록
build.gradle, docs/test-results/gimin-#124-opensql-verification-runbook.md, docs/test-results/gimin-#124-opensql-compatibility-performance.md
OpenSQL 전용 테스트 태스크와 openSqlVerification 집계 태스크를 추가했다. 태스크 실행 순서와 E2E·Claim·성능 검증 결과를 기록했다.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Verifier
  participant openSqlVerification
  participant OpenSqlCompatibilityIntegrationTest
  participant OpenSQL
  Verifier->>openSqlVerification: start OpenSQL verification
  openSqlVerification->>OpenSqlCompatibilityIntegrationTest: run compatibility test
  OpenSqlCompatibilityIntegrationTest->>OpenSQL: verify migration, vector, HNSW, and SKIP LOCKED
  openSqlVerification->>OpenSQL: run Claim, document E2E, and performance tests
Loading

Possibly related issues

  • DocGrid/backend 이슈 124: OpenSQL 검증 태스크, 호환성 테스트, 호스트 점검 및 실행 문서의 범위가 이슈 목표와 직접 일치한다.

Possibly related PRs

  • DocGrid/backend#53: Claim 동시성과 SKIP LOCKED 동작을 검증하는 OpenSQL 호환성 테스트와 직접 연결된다.
  • DocGrid/backend#62: EmbeddingJobClaimService의 Claim 성능 검증 태스크와 직접 연결된다.
  • DocGrid/backend#98: PostgreSQL 17 및 pgvector 0.8.1 환경의 vector·인덱스 계약을 OpenSQL 검증으로 확장한다.
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed 제목이 공식 OpenSQL 17.8 호환성 및 성능 검증 추가라는 변경의 핵심을 명확하고 간결하게 설명합니다.
Description check ✅ Passed 변경 내용, 검증 결과, 환경 제약, 후속 검증 및 보안 제외 사항을 구체적으로 설명해 대부분의 템플릿 요구사항을 충족합니다.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feature/124

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 9

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@build.gradle`:
- Around line 168-176: Update openSqlDocumentE2eTest so it requires explicit
MinIO and BGE-M3 target configuration before execution, rather than allowing
defaults or mock settings when only the local-e2e tag is present. Validate the
required URL and secret configuration sources and fail the task clearly when
they are missing, without logging secret values; preserve
configureOpenSqlDatabase for database setup.

In `@docs/test-results/gimin-`#124-opensql-compatibility-performance.md:
- Around line 151-163: 문서의 “전체 실행 결과”에 Swagger 수동 테스트 결과를 추가하십시오. 실제로 수행한 각
Endpoint의 입력 조건, 관찰한 응답, 성공 여부를 기록하고, 아직 수행하지 않았다면 결과를 임의로 작성하지 말고 필요한 Swagger
검증을 먼저 실행한 뒤 반영하십시오.

In `@docs/test-results/gimin-`#124-opensql-verification-runbook.md:
- Around line 229-236: 로컬 기준선 명령의 OPENSQL_DB_PASSWORD에 비밀번호 placeholder를 직접 지정하지
마세요. Section 3의 read -s 방식으로 비밀번호를 환경 변수에 주입한 뒤, openSqlCompatibilityTest 실행 시
기존 환경 변수 OPENSQL_DB_PASSWORD를 재사용하도록 문서를 수정하세요.
- Around line 60-61: Update the password input command in the runbook to disable
read’s escape processing, preserving backslashes exactly in OPENSQL_DB_PASSWORD
and its subsequent use as PGPASSWORD.
- Around line 215-219: Update the namespace discovery query in the runbook so
every literal underscore in the LIKE pattern is escaped, ensuring it matches
only names following the exact docgrid_opensql_..._test structure rather than
treating underscores as single-character wildcards.

In `@scripts/opensql/verify-host.sh`:
- Around line 48-50: server_version 및 vector_version의 psql 실행에서 stderr를 임시 파일에
캡처하고, trap으로 임시 파일을 항상 삭제하도록 변경하세요. psql 실패 시 원본 stderr를 출력하지 말고 연결 또는 버전 조회 실패를
나타내는 일반화된 메시지만 출력하면서 기존 set -e 동작은 유지하세요.
- Around line 48-50: The two psql invocations assigning server_version and
vector_version should run with -X --no-pager and an approved upper-bound
PGCONNECT_TIMEOUT environment setting. Apply these options consistently to both
calls, keeping PGCONNECT_TIMEOUT limited to connection establishment rather than
query timeout behavior.
- Around line 23-38: Update verify-host.sh so it does not claim official OpenSQL
Host validation based only on OPENSQL_INSTALL_MODE, server_version, and pgvector
version. Add the vendor-supported OpenSQL product identifier and Single-topology
evidence checks, or explicitly relabel the output and result as a
compatible-version preflight rather than an official OpenSQL determination.

In
`@src/test/java/com/opensource/docgrid/opensql/OpenSqlCompatibilityIntegrationTest.java`:
- Line 56: Update TEST_SCHEMA in OpenSqlCompatibilityIntegrationTest to append a
short, safe identifier suffix unique to each test JVM or Gradle execution.
Ensure the resulting schema remains valid for the OpenSQL database and is used
consistently by the existing table DDL and DROP SCHEMA ... CASCADE cleanup.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 5b897c75-df9a-4d3c-aca1-ab76e5218384

📥 Commits

Reviewing files that changed from the base of the PR and between 40d6a94 and 59a202a.

📒 Files selected for processing (6)
  • build.gradle
  • docs/design/gimin-#124-opensql-compatibility-performance.md
  • docs/test-results/gimin-#124-opensql-compatibility-performance.md
  • docs/test-results/gimin-#124-opensql-verification-runbook.md
  • scripts/opensql/verify-host.sh
  • src/test/java/com/opensource/docgrid/opensql/OpenSqlCompatibilityIntegrationTest.java

Comment thread build.gradle
Comment thread docs/test-results/gimin-#124-opensql-compatibility-performance.md
Comment thread docs/test-results/gimin-#124-opensql-verification-runbook.md Outdated
Comment thread docs/test-results/gimin-#124-opensql-verification-runbook.md
Comment thread docs/test-results/gimin-#124-opensql-verification-runbook.md
Comment thread scripts/opensql/verify-host.sh
Comment thread scripts/opensql/verify-host.sh Outdated
@Gimini-3
Gimini-3 merged commit bc5531f into develop Aug 8, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant