> **결정 기록** 본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지 않았다). 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다. - 상태: 채택 - 작성일: 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`.