llm-wiki/raw/official-docs/spring-tx-propagation-required-new-nested-official.md

title, source_type, url, archive_url, related_branches, related_projects, tags, status, confidence, created

title	source_type	url	archive_url	related_branches	related_projects	tags	status	confidence	created
official-doc / Spring Framework — Transaction Propagation (REQUIRES_NEW · NESTED)	official-doc	https://docs.spring.io/spring-framework/reference/data-access/transaction/declarative/tx-propagation.html		feature-application-port-usecase-contract	ca-skeleton	official-doc ca-skeleton persistence spring-boot transaction	raw	high	2026-05-28

official-doc / Spring Framework — Transaction Propagation (REQUIRES_NEW · NESTED)

Layer: raw/official-docs/ — Spring Framework 공식 레퍼런스의 transaction propagation 섹션 원문 발췌. PROPAGATION_REQUIRES_NEW 의 independent physical transaction 보장 + connection pool 위험 + PROPAGATION_NESTED 의 savepoint 동작을 verbatim quote 로 보존.

Parent / 활용 branch

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-application-port-usecase-contract	TransactionPort.inNew (PROPAGATION_REQUIRES_NEW) 의 independent physical transaction 보장 및 connection pool exhaustion / deadlock 위험 명시 근거. 기존 spring-tx-management-reference.md 는 REQUIRES_NEW 의 connection 동작을 직접 인용하지 않아 본 문서로 보강.

출처 / Source

• 원본 URL: https://docs.spring.io/spring-framework/reference/data-access/transaction/declarative/tx-propagation.html
• 아카이브 URL: (미수집)
• 저자 / 조직: Spring Framework 프로젝트 (Pivotal / VMware / Broadcom)
• 발행일: 공식 레퍼런스 (버전 지속 갱신)
• 마지막 확인일: 2026-05-28

왜 저장했는지 / Why archived

TransactionPort.inNew 는 Spring PROPAGATION_REQUIRES_NEW 를 wrapping 하며, 이 propagation 이 독립적인 물리 커넥션을 획득하고 pool exhaustion / deadlock 위험을 수반한다는 사실을 공식 벤더 문서 verbatim 으로 증명할 필요가 있었다. spring-tx-management-reference.md 가 propagation 기본값과 readOnly 를 다루지만 REQUIRES_NEW 의 connection 동작을 직접 인용하지 않으므로 본 섹션을 별도 raw 자료로 분리 보관한다.

핵심 인용 / Key quotes (verbatim, 5개 — Self-Grep 전량 통과)

[§Understanding PROPAGATION_REQUIRES_NEW] "PROPAGATION_REQUIRES_NEW, in contrast to PROPAGATION_REQUIRED, always uses an independent physical transaction for each affected transaction scope, never participating in an existing transaction for an outer scope."

[§Understanding PROPAGATION_REQUIRES_NEW] "The resources attached to the outer transaction will remain bound there while the inner transaction acquires its own resources such as a new database connection."

[§Understanding PROPAGATION_REQUIRES_NEW] "This may lead to exhaustion of the connection pool and potentially to a deadlock if several threads have an active outer transaction and wait to acquire a new connection for their inner transaction, with the pool not being able to hand out any such inner connection anymore."

[§Understanding PROPAGATION_REQUIRES_NEW] "Do not use PROPAGATION_REQUIRES_NEW unless your connection pool is appropriately sized, exceeding the number of concurrent threads by at least 1."

[§Understanding PROPAGATION_NESTED] "PROPAGATION_NESTED uses a single physical transaction with multiple savepoints that it can roll back to."

Claims Extracted / 추출된 주장

이 자료가 직접 말하는 것만 claim 으로 분리한다.

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
SPRING-PROP-C1	PROPAGATION_REQUIRES_NEW 는 항상 독립적인 물리 트랜잭션을 사용하며 외부 scope 의 기존 트랜잭션에 참여하지 않는다	[§Understanding PROPAGATION_REQUIRES_NEW] "PROPAGATION_REQUIRES_NEW, in contrast to PROPAGATION_REQUIRED, always uses an independent physical transaction for each affected transaction scope, never participating in an existing transaction for an outer scope."	official-vendor-doc	Spring Framework 의 PROPAGATION_REQUIRES_NEW 를 사용하는 모든 @Transactional 또는 TransactionTemplate 호출	특정 DB 드라이버·커넥션 풀 구현(HikariCP 등)에서의 구체 동작 보장. ca-tmpl TransactionPort.inNew 가 실제로 이 propagation 을 사용함을 단독 증명하지 않음
SPRING-PROP-C2	REQUIRES_NEW 내부 트랜잭션이 신규 DB 커넥션을 획득하는 동안 외부 트랜잭션의 리소스는 기존 커넥션에 bound 상태를 유지한다	[§Understanding PROPAGATION_REQUIRES_NEW] "The resources attached to the outer transaction will remain bound there while the inner transaction acquires its own resources such as a new database connection."	official-vendor-doc	REQUIRES_NEW 가 외부 트랜잭션 컨텍스트 내에서 호출될 때	HikariCP 의 실제 pool-size 임계값이나 타임아웃 동작 세부. TransactionPort.inNew 의 ca-tmpl 구현 레벨 검증
SPRING-PROP-C3	여러 스레드가 활성 외부 트랜잭션을 보유한 채 내부 트랜잭션용 신규 커넥션을 대기하면 connection pool exhaustion 및 deadlock 이 발생할 수 있다	[§Understanding PROPAGATION_REQUIRES_NEW] "This may lead to exhaustion of the connection pool and potentially to a deadlock if several threads have an active outer transaction and wait to acquire a new connection for their inner transaction, with the pool not being able to hand out any such inner connection anymore."	official-vendor-doc	REQUIRES_NEW 를 동시 다수 스레드가 사용하는 환경	deadlock 이 반드시 발생한다는 보장. ca-tmpl 특정 pool size 에서의 실제 임계값
SPRING-PROP-C4	connection pool 크기가 동시 스레드 수보다 최소 1 이상 크지 않으면 PROPAGATION_REQUIRES_NEW 사용 금지	[§Understanding PROPAGATION_REQUIRES_NEW] "Do not use PROPAGATION_REQUIRES_NEW unless your connection pool is appropriately sized, exceeding the number of concurrent threads by at least 1."	official-vendor-doc	REQUIRES_NEW 를 사용하는 모든 Spring 애플리케이션	pool size 최솟값의 절대 수치 (동시 스레드 수는 애플리케이션별로 다름). HikariCP maximumPoolSize 의 구체 설정값 권고
SPRING-PROP-C5	PROPAGATION_NESTED 는 단일 물리 트랜잭션 내에 다수의 savepoint 를 사용하며 내부 scope 을 그 savepoint 까지 rollback 할 수 있다	[§Understanding PROPAGATION_NESTED] "PROPAGATION_NESTED uses a single physical transaction with multiple savepoints that it can roll back to."	official-vendor-doc	JDBC savepoint 를 지원하는 드라이버 + DataSourceTransactionManager 사용 환경	JPA / Hibernate 환경에서 NESTED 의 동작. TransactionPort 에서 NESTED 를 노출하지 않기로 한 ca-tmpl 결정 자체 (그것은 ca-tmpl 자체 계약)

Usage Boundaries / 적용 경계

• 이 자료가 직접 증명하는 것:
  • SPRING-PROP-C1: Spring PROPAGATION_REQUIRES_NEW 가 독립적 물리 트랜잭션을 사용함
  • SPRING-PROP-C2: 내부 REQUIRES_NEW 가 신규 커넥션을 필요로 하며 외부 커넥션은 점유 상태를 유지함
  • SPRING-PROP-C3: 동시 다중 스레드 환경에서 pool exhaustion / deadlock 위험이 공식 문서에서 명시됨
  • SPRING-PROP-C4: pool size ≥ (동시 스레드 수 + 1) 이라는 Spring 공식 최소 요건
  • SPRING-PROP-C5: NESTED 가 savepoint 기반 단일 물리 트랜잭션임
• 이 자료가 증명하지 않는 것:
  • ca-tmpl SpringTransactionPort.inNew 의 실제 REQUIRES_NEW propagation 설정이 올바름 (코드 레벨 검증은 별도)
  • HikariCP 또는 다른 pool 구현에서의 실제 timeout / deadlock 임계값
  • NESTED 가 JPA EntityManager 환경에서 작동함 (JDBC DataSourceTransactionManager 전용)
  • TransactionPort 에서 inNew 를 노출하고 NESTED 를 숨긴 ca-tmpl 결정 자체의 정당성
• 내 프로젝트에 적용하려면 추가 확인이 필요한 것:
  • ca-tmpl HikariCP maximumPoolSize 가 SPRING-PROP-C4 조건을 만족하는지 (pool size ≥ concurrent threads + 1) 측정 필요
  • outbox/audit row 패턴에서 inNew 를 실제 호출하는 통합 테스트 (feature-domain-event-outbox-contract 단계)

메모 / Notes

• REQUIRES_NEW 의 deadlock 경고(SPRING-PROP-C3/C4)는 Spring 공식 문서가 명시적 "Do not use … unless" 형태로 사용 제한을 걸고 있다. ca-tmpl 이 inNew 를 TransactionPort API 에 노출했으므로, pool size 설정 가이드라인이 feature-domain-event-outbox-contract 또는 infrastructure 설정 branch 에서 별도 관리되어야 한다.
• PROPAGATION_NESTED 는 JDBC savepoint + DataSourceTransactionManager 전용이라는 제약이 공식 문서에 명시됨. ca-tmpl 이 NESTED 를 TransactionPort API 에서 노출하지 않기로 한 결정(2026-05-28)은 이 제약과 일관성이 있으나, 그 결정 자체는 이 자료가 아닌 ca-tmpl 자체 계약에서 온다.
• 이 페이지에서 PROPAGATION_REQUIRED 섹션도 다루지만 해당 내용은 spring-tx-management-reference.md 에서 이미 인용 중이므로 중복 claim 생성 안 함.

Related / 관련

• raw/official-docs/spring-tx-management-reference — Spring transaction abstraction (PlatformTransactionManager SPI) + propagation 기본값 + readOnly. REQUIRES_NEW connection 동작은 본 문서가 보강.
• raw/official-docs/transaction-template-spring-official — TransactionTemplate programmatic API. SpringTransactionPort 의 구현 방식 근거.
• raw/official-docs/at-transactional-spring-official — @Transactional 선언적 API + self-invocation 함정.