문제: `docs/adr/`의 결정 기록 26개는 머리 블록만 한국어이고 본문이 영어다. 소유자는 2026-11-07에 결정 기록도 본문까지 한국어로 쓰기로 정했다(design-docs `repo-structure/README.md` 3.2절). 방법: 결정의 뜻을 바꾸지 않고 옮긴다. 머리 블록(상태·작성일·요약· 현재 정본·대체됨)은 한 글자도 바꾸지 않는다. 본문의 상태·날짜·범위 줄, 나중에 붙인 보완·대체 메모, 따져 본 대안도 함께 옮긴다. 코드· 명령·경로·식별자·설정 키·SQL·표 구조는 원문으로 둔다. 본문이 인용한 영어 원문(루트 CLAUDE.md의 한 문장, 플러그인 주석)은 원문을 두고 뜻을 괄호로 붙인다. 결정 기록은 본문을 고치지 않는 문서라서, 번역하며 본 지금 코드와 다른 점(예: ADR-MONGO-ADV-001은 지웠다고 적은 `scripts/verify-mongodb-advanced.sh`가 지금 있다)은 고치지 않고 보고에 남긴다. 위험: 머리 블록 둘째 줄 「본문은 결정한 때의 원문이다」는 번역한 뒤 문자 그대로는 맞지 않는다. 문구를 고칠지는 통합 단계에서 정한다. 검증: python3 scripts/check-docs.py rc=0(language 줄 26개 지움, head 실패 0), 머리 블록이 HEAD와 같은지 26개 모두 diff로 대조, check-work-docs.py --links(gates.md 범위) 깨진 링크 0.
2.1 KiB
결정 기록 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-08-11
- 요약: 영속성 계약은 실제 PostgreSQL에서 돌린다는 결정이다.
- 현재 정본:
docs/jpa/support-matrix.md
ADR-JPA-005 — 계약은 실제 PostgreSQL에 대고 돈다
- 상태: 채택
- 날짜: 2026-08-11
- 설계: §40
배경
메모리 데이터베이스는 시험을 빠르고 밀폐되게 만든다. container는 느리게 만들고 Docker를 요구한다.
결정
모든 영속 계약은 container 안의 실제 PostgreSQL 16, 17, 18에 대고 돈다. H2는 로컬 개발 편의로 남고 어떤 계약도 만족시키지 않는다. Docker가 없으면 lane은 건너뛰지 않고 실패하면 닫힌다.
결과
이 계약이 검증하는 동작은 H2에 없거나 다르다: 같은 위반의 SQLSTATE 값, FOR UPDATE SKIP LOCKED의 뜻, JSONB 연산자, 범위 타입,
concurrent index 만들기, search_path 권한, page를 나눈 컬렉션 fetch의 생성 SQL. H2 실행이 초록이면 코드가 컴파일되고 돈다는
증거이지 — 위 어느 것이 지켜진다는 증거가 아니다.
버전을 하나가 아니라 셋 두는 것은 플랫폼이 셋을 주장하기 때문이다. 16에서만 도는 계약 suite는 「17과 18에서 Stable」을 가정으로 만든다.
Docker가 없을 때 건너뛰는 것이 이 결정이 가장 피하려는 실패 방식이다: 건너뛴 계약은 성공을 알리고, CI는 결국 그 침묵을
물려받는다. PostgreSqlContainerFactory.assertDockerAvailable()은 대신 던진다.
비용은 계약 lane에 Docker가 필요하고 몇 분이 걸린다는 것이다. 단위 lane은 밀폐되고 빠른 채로 남고 대부분의 시험이 거기 있다. container lane은 실제 서버만 답할 수 있는 것을 검증한다.
강제
PostgreSqlVersion.stable(), PostgreSqlContainerFactory, 릴리스 gate postgresql-contract.