Files
clean-architecture-backend-…/docs/jpa/postgresql-extensions.md
T
DongHyeonkaandClaude Opus 5.5 6d27356e2b refactor: 부가 기능을 capability 모듈로 포장하고 기본 조립을 web-only로 전환
설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md

- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
  (compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
  messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
  outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
  Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
  qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용

삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.

Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
2026-09-25 12:49:07 +09:00

2.5 KiB

PostgreSQL Extensions

Design §8.3, §21, §30. What the platform uses beyond portable JPA, and what each is guarded by.

Everything here is core PostgreSQL. No server extension is required.

Locking

SELECT ... FOR UPDATE with a finite bound, always. PostgreSqlLockOptions refuses an unbounded lock request because it waits as long as the holder holds it, turning one slow transaction into a pile-up of blocked connections.

NOWAIT and a wait timeout are separate requests, not two spellings of one — modelling them as a single field with a magic zero is how "no wait" becomes "wait forever".

55P03 (lock not available) and 40P01 (deadlock) drive opposite recovery and are never collapsed: the first leaves the transaction alive and the caller in control; the second has already been rolled back by the server.

JSONB

JsonDocument carries a schema name and version alongside the payload. A JSONB column is schemaless at the database level, so without an envelope the only record of what a stored document means is the code that wrote it — and a document written two releases ago is indistinguishable from a current one.

The payload never carries a Java class name. Type metadata in a JSONB column is a deserialization gadget: whoever can write a row chooses the class the reader instantiates.

Query paths are registered. A JSON path is part of the SQL text and cannot be bound, so forwarding a request field into one is concatenating untrusted input into a statement. Values are always bound.

Arrays and ranges

Arrays are built with Connection.createArrayOf, never by formatting a literal — hand-formatting is where quoting bugs live, and a tag containing a comma changes the array's shape rather than its content.

PgRange models both endpoints as independently optional and independently inclusive, because that is what a PostgreSQL range is. Whether [09:00, 10:00) and [10:00, 11:00) overlap depends on the bracket, not the values, and a pair of timestamptz columns cannot express it.

COPY (J4 admin)

COPY bypasses the Persistence Context, entity callbacks, version checks, and Envers entirely. That is why it is fast and why it is an admin capability with a registered statement, a bounded stream, a row and byte cap, a finite server-side statement_timeout, and a named operator.

The registry accepts only COPY ... FROM STDIN. COPY ... FROM '/path' reads a file on the database server as the server's OS user; it is superuser-only for exactly that reason and does not belong behind an application API.