llm-wiki/raw/official-docs/persistence-spring-dataaccessexception-hierarchy.md

---
title: Spring DataAccessException hierarchy & exception translation (공식 문서 + Javadoc)
source_type: official-doc
status: raw
confidence: high
url: https://docs.spring.io/spring-framework/reference/data-access/dao.html
archive_url:
tags: [ca-persistence-failure, spring, jdbc, jpa, exception-translation, official-doc]
related_branches: [feature-persistence-failure-baseline, feature-operational-error-observability-foundation]
related_projects: [ca-skeleton-operational-contract]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# Spring DataAccessException hierarchy & exception translation

> Layer: `raw/official-docs/` — Spring Framework Reference + `DataAccessException` Javadoc 발췌. ca-tmpl persistence failure 분류의 **공식 backbone**.

## Parent / 활용 branch (필수)

| Branch | 이 자료가 정당화하는 결정 |
|---|---|
| [[raw/branch-notes/feature-persistence-failure-baseline]] | ca-tmpl SQLState 9-row matrix 가 임의 분류가 아니라 Spring 의 `DataAccessException` hierarchy 위에 SQLState 를 입힌 형태라는 사실 근거 |
| [[raw/branch-notes/feature-operational-error-observability-foundation]] | error code → retryable / non-retryable / recoverable 의 3-way classifier 가 Spring 공식 hierarchy 와 정합한다는 근거 |

특정 branch 없이 foundational 조사로 수집한 경우:

- [[raw/project-notes/ca-skeleton-operational-contract]] — ca-tmpl persistence failure baseline + error observability 의 초기 조사

## 컨텍스트 / 왜 저장했는지

ca-tmpl persistence failure 분류의 **공식 기준**. SQLState 9-row matrix 가 임의 분류가 아니라 Spring 이 이미 채택한 hierarchy (`DataAccessException` 하위) 를 따른다는 근거.

## 출처 / Source

- 원본 URL: https://docs.spring.io/spring-framework/reference/data-access/dao.html
- 보조 URL: https://docs.spring.io/spring-framework/docs/current/javadoc-api/org/springframework/dao/DataAccessException.html (Javadoc — `Direct Known Subclasses` 확정)
- 아카이브 URL: (미수집)
- 저자 / 조직: Spring Team (VMware/Broadcom)
- 발행일: rolling (Spring Framework current)
- 마지막 확인일: 2026-05-27 (WebFetch 검증: dao.html landing 의 high-level translation quote + Javadoc 의 Direct Known Subclasses 확보. `sql-error-codes.xml` 및 상세 subclass 그룹 quote 는 본 세션 verbatim 미확보 — Javadoc 으로 보강)
- 보조 자료: `SQLExceptionTranslator`, `SQLErrorCodeSQLExceptionTranslator` Javadoc (별도 raw 미수집)

## 핵심 인용 / Key quotes (verbatim)

> [Spring Framework Reference §Consistent Exception Hierarchy] "Spring provides a convenient translation from technology-specific exceptions, such as `SQLException` to its own exception class hierarchy, which has `DataAccessException` as the root exception. These exceptions wrap the original exception so that there is never any risk that you might lose any information about what might have gone wrong."

> [Spring Framework Reference §Consistent Exception Hierarchy] "In addition to JDBC exceptions, Spring can also wrap JPA- and Hibernate-specific exceptions, converting them to a set of focused runtime exceptions."

> [`DataAccessException` Javadoc — class description] "Root of the hierarchy of data access exceptions discussed in Expert One-On-One J2EE Design and Development. ... This exception hierarchy aims to let user code find and handle the kind of error encountered without knowing the details of the particular data access API in use (for example, JDBC). Thus, it is possible to react to an optimistic locking failure without knowing that JDBC is being used. As this class is a runtime exception, there is no need for user code to catch it or subclasses if any error is to be considered fatal (the usual case)."

> [`DataAccessException` Javadoc — Direct Known Subclasses] "`NonTransientDataAccessException`, `RecoverableDataAccessException`, `ScriptException` (org.springframework.jdbc.datasource.init), `ScriptException` (org.springframework.r2dbc.connection.init), `TransientDataAccessException`"

## Claims Extracted / 추출된 주장

| Claim ID | Claim (이 자료가 직접 말하는 것) | Evidence quote | Strength | Applies to | Does not prove |
|---|---|---|---|---|---|
| SDA-EX-C1 | Spring 은 `SQLException` 같은 technology-specific exception 을 `DataAccessException` 을 root 로 하는 자체 hierarchy 로 변환하며, 원본 exception 정보를 wrap 으로 보존 | [Reference §Consistent Exception Hierarchy] "Spring provides a convenient translation from technology-specific exceptions, such as `SQLException` to its own exception class hierarchy, which has `DataAccessException` as the root exception. These exceptions wrap the original exception so that there is never any risk that you might lose any information about what might have gone wrong." | `official-vendor-doc` | Spring JDBC / Spring Data JPA / Spring Data R2DBC 사용 환경 | "모든 vendor exception 이 100% 손실 없이 매핑된다" 는 강한 주장은 아님 — wrap 으로 보존되지만 변환 표는 `sql-error-codes.xml` 의 한계 안에서 동작 |
| SDA-EX-C2 | `DataAccessException` 은 unchecked runtime exception 이며, user code 가 catch 할 필요가 없음 (fatal 처리 default 가정) | [Javadoc] "As this class is a runtime exception, there is no need for user code to catch it or subclasses if any error is to be considered fatal (the usual case)." | `official-reference` | DAO 호출 측 코드 일반 | "절대 catch 하지 말라" 는 뜻 아님 — retry 가능한 transient 류는 의도적으로 catch 하는 것이 ca-tmpl 의 retry 정책과 정합 |
| SDA-EX-C3 | `DataAccessException` 의 **Direct Known Subclasses** 는 `NonTransientDataAccessException`, `RecoverableDataAccessException`, `TransientDataAccessException` (그리고 init 패키지의 `ScriptException` 2종). 즉 top-level 3-way 분류: transient / non-transient / recoverable | [Javadoc — Direct Known Subclasses] "NonTransientDataAccessException, RecoverableDataAccessException, ScriptException (org.springframework.jdbc.datasource.init), ScriptException (org.springframework.r2dbc.connection.init), TransientDataAccessException" | `official-reference` | Spring DAO hierarchy 분류 일반 | 각 sub-tree (`QueryTimeoutException`, `ConcurrencyFailureException` 등) 의 정확한 부모는 별도 Javadoc 확인 필요 (본 인용은 Direct Known Subclasses 만 보장) |
| SDA-EX-C4 | Spring 은 JDBC exception 외에도 JPA / Hibernate 의 vendor-specific exception 을 별도 runtime exception 집합으로 변환 | [Reference §Consistent Exception Hierarchy] "In addition to JDBC exceptions, Spring can also wrap JPA- and Hibernate-specific exceptions, converting them to a set of focused runtime exceptions." | `official-vendor-doc` | Spring Data JPA + Hibernate 사용 환경 | "어떤 Hibernate exception 이 어떤 Spring exception 으로 매핑되는지" 의 정확한 표는 본 인용 범위 밖 — `HibernateJpaDialect` 별도 |
| SDA-EX-C5 | hierarchy 의 의도: user code 가 vendor (JDBC 등) 디테일을 모르고도 error kind 별로 핸들링 가능 (예: optimistic locking failure 를 JDBC 사용 여부 무관하게 처리) | [Javadoc] "This exception hierarchy aims to let user code find and handle the kind of error encountered without knowing the details of the particular data access API in use (for example, JDBC). Thus, it is possible to react to an optimistic locking failure without knowing that JDBC is being used." | `official-reference` | DAO portability / handler 분리 | "모든 사용자 코드가 vendor-agnostic 해야 한다" 는 prescriptive 주장 아님 — 가능성을 의도한다는 뜻 |
| SDA-EX-C6 | `sql-error-codes.xml` 의 error code mapping 을 통해 vendor-specific SQL error 가 Spring DAO hierarchy 로 매핑된다는 메커니즘 | (원본 frontmatter 발췌 — 본 세션 WebFetch 로 verbatim 직접 재확인 미완료. dao.html landing 에는 등장하지 않음, javadoc 별도 확인 필요) | `needs-confirmation` | `SQLErrorCodeSQLExceptionTranslator` 사용 환경 | 본 세션 verbatim 미확보 — 후속 라운드에 `SQLErrorCodeSQLExceptionTranslator` Javadoc 또는 Reference 의 JDBC 섹션에서 verbatim 재확인 필요 |
| SDA-EX-C7 | SQLState 8\* (connection 계열) / 40001 (serialization) / 40P01 (deadlock) / 23\* (integrity) / 23505 (unique violation) 와 Spring exception class 간의 구체적 매핑 (`DataAccessResourceFailureException`, `ConcurrencyFailureException` 계열, `DataIntegrityViolationException`, `DuplicateKeyException`) | (원본 frontmatter 발췌 — 본 세션 dao.html landing 에 등장하지 않음. `sql-error-codes.xml` source 또는 vendor-specific Javadoc 별도 확인 필요) | `needs-confirmation` | PostgreSQL / vendor 환경에서의 ca-tmpl SQLState matrix 정당성 | 본 세션 verbatim 미확보 — ca-tmpl 9-row matrix 의 SQLState ↔ Spring class 매핑은 후속 라운드에 vendor 별 `sql-error-codes.xml` 로 직접 검증 필요 |

## Usage Boundaries / 적용 경계

- **이 자료가 직접 증명하는 것**:
  - `SDA-EX-C1` ~ `C5`: Spring 의 `DataAccessException` hierarchy 가 존재하며 vendor exception 을 변환한다는 사실, hierarchy 가 unchecked 이며 portability 를 의도한다는 사실, top-level 3-way 분류 (`Transient` / `NonTransient` / `Recoverable`) 의 존재
- **이 자료가 증명하지 않는 것**:
  - `sql-error-codes.xml` 의 정확한 매핑 표 (`SDA-EX-C6` — `needs-confirmation`)
  - 특정 SQLState (8\*, 23\*, 40001, 23505 등) 가 어떤 Spring exception 으로 매핑되는지의 vendor-별 표 (`SDA-EX-C7` — `needs-confirmation`). ca-tmpl 9-row matrix 의 vendor 정당성은 별도 검증 필요
  - 각 sub-tree (`QueryTimeoutException`, `OptimisticLockingFailureException` 등) 의 직접 부모가 `TransientDataAccessException` 인지 `RecoverableDataAccessException` 인지의 정확한 위계 — Javadoc 별도 확인 필요
- **내 프로젝트에 적용하려면 추가 확인이 필요한 것**:
  - ca-tmpl 9-row matrix 의 SQLState → ca-tmpl code 매핑이 Spring 공식 `sql-error-codes.xml` 의 PostgreSQL/MySQL section 과 일치하는지 코드 검증
  - `DB_UNIQUE_VIOLATION` 을 별도 code 로 가져가는 결정이 `DuplicateKeyException` 의 위계 (구체 부모는 `DataIntegrityViolationException`) 와 정합한지 javadoc 확인
  - JPA / Hibernate exception 매핑이 ca-tmpl 의 `retryable` 분류와 충돌하지 않는지 별도 검증

## 메모 / Notes (내 프로젝트 해석 — 검증 전 추론)

> 본 섹션은 자료 직접 인용 아님. ca-tmpl 결정 컨텍스트 해석.

- **핵심 의미 (해석)**:
  - `TransientDataAccessException` = retry 로 회복 가능 → ca-tmpl `retryable=true` 후보
  - `NonTransientDataAccessException` = retry 무의미 → ca-tmpl `retryable=false` 후보
  - `RecoverableDataAccessException` = 환경 정상화 후 재시도 가능 (커넥션 재획득 등)
- **SQLState 매핑 (해석 — `SDA-EX-C7` 의 needs-confirmation 영역)**:
  - SQLState 8\* 는 connection 계열 → `DataAccessResourceFailureException` 으로 매핑된다는 통설. ca-tmpl `DB_UNAVAILABLE` 매핑과 일치한다는 가정
  - SQLState 40001(serialization), 40P01(deadlock) → `ConcurrencyFailureException` 계열. ca-tmpl `DB_SERIALIZATION_FAILURE`, `DB_DEADLOCK` 와 일치한다는 가정
  - SQLState 23\* → `DataIntegrityViolationException`. ca-tmpl `DATA_INTEGRITY` family 가정
  - 23505 unique violation 은 `DuplicateKeyException` 으로 더 specific 함 → ca-tmpl 이 별도 code `DB_UNIQUE_VIOLATION` 로 가져가는 근거
- **시사점**: ca-tmpl 9-row matrix 는 **자의적 분류가 아니라** Spring DAO hierarchy 의 3-way 분류 (`SDA-EX-C3`) 에 SQLState 를 입힌 형태. canonical 로 승급 시 인용 가능 — 단 vendor 매핑은 `sql-error-codes.xml` 로 보강 필요.

## Related / 관련

- 같은 주제 다른 official-doc / company-tech-blog:
  - [[raw/official-docs/persistence-r2dbc-reactive-spring]] (R2DBC 도 동일 `DataAccessException` hierarchy 재사용)
  - [[raw/official-docs/persistence-osiv-antipattern-hibernate-vladmihalcea]] (JPA / Hibernate exception 변환 컨텍스트)
- 인용하는 branch:
  - [[raw/branch-notes/feature-persistence-failure-baseline]]
  - [[raw/branch-notes/feature-operational-error-observability-foundation]]
- 인용하는 wiki: (미작성)
- 대안 그룹 (ca-tmpl 결정 컨텍스트): **Group G-C — Persistence failure** (대안: Spring DAO hierarchy [ca-tmpl 채택] / R2DBC reactive / JOOQ SQL-first / 직접 JDBC + 자체 classifier / DB-specific vendor classification)