Files

T

DongHyeonka d71669eb59 fix: 하네스 제거 및 keycloak 문서 보강

2026-07-25 12:53:13 +09:00

11 KiB

Raw Permalink Blame History

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

title

source_type

url

archive_url

status

confidence

Hibernate ORM User Guide — Multi-tenancy

Layer: raw/official-docs/ — Hibernate ORM 6.x User Guide "Multi-tenancy" 챕터. Spring Boot / Hibernate 스택에서 multi-tenancy 를 ORM 레벨에서 지원하는 공식 3 strategy (DATABASE / SCHEMA / DISCRIMINATOR) baseline. 검증된 요약은 /ingest 후 wiki/concepts/에 별도 작성.

Parent / 활용 branch (필수)

Branch	이 자료가 정당화하는 결정
raw/branch-notes/feature-tenant-context-policy	ca-tmpl 이 Hibernate Filter / `@TenantId` (Hibernate 6) 기반 DISCRIMINATOR 전략을 채택한 결정의 공식 strategy 분류 baseline.
raw/branch-notes/feature-repository-access-permission-contract	CROSS_TENANT_ADMIN capability 가 DISCRIMINATOR 전략 하에서 `CurrentTenantIdentifierResolver` 또는 Filter 우회 메커니즘으로 구현되는 정당화 근거.
raw/project-notes/ca-skeleton-operational-contract	§18 Control Plane Contract (Tenant Context Policy) 의 ORM 레벨 구현 방식 reference.

컨텍스트 / 왜 저장했는지

Spring Boot/Hibernate 스택에서 multi-tenancy 를 ORM 레벨에서 지원하는 공식 방식. ca-tmpl 이 tenant_id column (discriminator/filter) 방식을 택한 것에 대비해, Hibernate 가 공식 지원하는 3가지 strategy 의 정의 baseline.

출처 / Source

원본 URL: https://docs.jboss.org/hibernate/orm/current/userguide/html_single/Hibernate_User_Guide.html#multitenacy
관련: MultiTenantConnectionProvider, CurrentTenantIdentifierResolver
아카이브 URL: (미수집)
저자 / 조직: Hibernate ORM (Red Hat) Documentation
발행일: rolling docs (Hibernate 6.x current)
마지막 확인일: 2026-05-27
재검증 결과 (2026-05-27): WebFetch 가 페이지를 fetch 했고 (docs.jboss.org → docs.hibernate.org 301 redirect 후), Table of Contents 와 chapter 24 (현재 버전; 6.6 에서는 23) 의 sub-section 구조 (24.1 What is multitenancy? / 24.2 Multitenant data approaches → Separate database / Separate schema / Partitioned (discriminator) data / 24.3 Multitenancy in Hibernate → @TenantId, MultiTenantConnectionProvider, CurrentTenantIdentifierResolver, hibernate.tenant_identifier_resolver, hibernate.multi_tenant_connection_provider properties) 는 확인됨. 단, 본문 sentence body 는 WebFetch summary 가 truncated 되어 verbatim 재확인 불가. 사실 구조 (3 strategy + 두 config property + @TenantId) 는 official-vendor-doc 수준으로 확인, 본문 verbatim 문장은 계속 needs-confirmation.

핵심 인용 / Key quotes (verbatim, 2026-05-22 작성 시 인용)

needs-confirmation [§Multi-tenancy 정의 — 2026-05-25 capture, 2026-05-27 WebFetch body truncated] "Multi-tenancy refers to a software design principle whereby a single instance of software runs on a server, serving multiple tenants."

needs-confirmation [§Approaches — 2026-05-25 capture, 2026-05-27 WebFetch 가 sub-section 구조 (Separate database / Separate schema / Partitioned (discriminator) data) 는 확인했으나 본문 sentence verbatim 은 truncated] "Hibernate supports the following approaches: DATABASE — Separate database per tenant; SCHEMA — Same database, but different schemas per tenant; DISCRIMINATOR — Same database, same schema, with a tenant discriminator column."

needs-confirmation [§Configuration — 2026-05-25 capture, 2026-05-27 WebFetch 가 property 이름 (hibernate.tenant_identifier_resolver, hibernate.multi_tenant_connection_provider) 은 확인했으나 본문 verbatim sentence 는 truncated] "Specifying multi-tenancy support in Hibernate is achieved by setting the hibernate.tenant_identifier_resolver and hibernate.multi_tenant_connection_provider properties."

needs-confirmation [§Hibernate 6 DISCRIMINATOR — 2026-05-25 capture, 2026-05-27 WebFetch 가 @TenantId annotation 존재는 확인했으나 "previously required Hibernate Filter" 의 verbatim 은 확인 불가] "Hibernate 6 supports DISCRIMINATOR multi-tenancy natively (previously required Hibernate Filter)."

Claims Extracted / 추출된 주장

Claim ID	Claim (이 자료가 직접 말하는 것)	Evidence quote	Strength	Applies to	Does not prove
HBN-MT-C1	Multi-tenancy 는 single instance 의 software 가 multiple tenants 를 serving 하는 design principle (Hibernate 정의)	needs-confirmation [§Multi-tenancy 정의] "Multi-tenancy refers to a software design principle whereby a single instance of software runs on a server, serving multiple tenants."	`needs-confirmation`	Hibernate ORM 6.x 컨텍스트	본 정의가 SaaS 일반 정의와 동일하다는 보증은 아님 (단순 software 정의)
HBN-MT-C2	Hibernate 가 공식 지원하는 multi-tenancy strategy 3종 — DATABASE (tenant 당 별도 DB) / SCHEMA (같은 DB, 다른 schema) / DISCRIMINATOR (같은 DB+schema, tenant discriminator column)	needs-confirmation [§Approaches] "Hibernate supports the following approaches: DATABASE — Separate database per tenant; SCHEMA — Same database, but different schemas per tenant; DISCRIMINATOR — Same database, same schema, with a tenant discriminator column."	`needs-confirmation` (사실 내용은 official-vendor-doc)	Hibernate 6.x	3 strategy 의 trade-off 권장은 본 인용에 없음 — Hibernate 가 default 를 권장하지 않음
HBN-MT-C3	Multi-tenancy 활성화는 `hibernate.tenant_identifier_resolver` + `hibernate.multi_tenant_connection_provider` property 설정으로 수행	needs-confirmation [§Configuration] "Specifying multi-tenancy support in Hibernate is achieved by setting the `hibernate.tenant_identifier_resolver` and `hibernate.multi_tenant_connection_provider` properties."	`needs-confirmation` (사실 내용은 official-vendor-doc)	DATABASE / SCHEMA 전략의 Hibernate 설정	DISCRIMINATOR 전략에서 동일 property 두 개 모두 요구된다는 뜻은 아님 (DISCRIMINATOR 는 connection provider 불필요할 가능성, 별도 검증 필요)
HBN-MT-C4	Hibernate 6 에서 DISCRIMINATOR multi-tenancy 가 native 지원 (이전 버전은 Hibernate Filter 필요)	needs-confirmation [§Hibernate 6 DISCRIMINATOR] "Hibernate 6 supports DISCRIMINATOR multi-tenancy natively (previously required Hibernate Filter)."	`needs-confirmation` (사실 내용은 official-vendor-doc)	Hibernate 6+	`@TenantId` annotation 의 정확한 사용법 / native query 우회 안전성은 본 인용에 없음

Usage Boundaries / 적용 경계

이 자료가 직접 증명하는 것:
- HBN-MT-C1 ~ C4: Hibernate 공식 multi-tenancy strategy 3종의 존재 및 설정 property 의 이름 (재확인 필요한 verbatim)
이 자료가 증명하지 않는 것:
- 2026-05-25 인용 verbatim 의 현재 페이지 존재 여부 (WebFetch 차단으로 재확인 실패)
- 3 strategy 의 권장 사용 시나리오 (Hibernate 는 strategy 만 제공, 선택은 application 책임)
- DISCRIMINATOR 가 native query / JDBC bypass 에 안전하다는 보장 (JPQL 만 적용)
- HikariCP 같은 connection pool 과 DATABASE 전략의 결합 권장 패턴
내 프로젝트에 적용하려면 추가 확인이 필요한 것:
- ca-tmpl 이 사용하는 Hibernate 버전이 6+ 인지 (DISCRIMINATOR native 지원 가능성)
- @TenantId annotation 적용 시 entity 별 강제 여부 (opt-in 모델과 호환되는지)
- CurrentTenantIdentifierResolver 구현체에서 ThreadLocal vs SecurityContextHolder 의 선택 (Spring Security 와의 통합)
- CROSS_TENANT_ADMIN capability 가 Hibernate Filter disable / resolver override 중 어느 메커니즘으로 구현되는지
- 본 raw 인용 verbatim 의 정확성은 페이지 사람 검증 또는 archive.org snapshot 으로 보강

메모 / Notes (내 프로젝트 해석)

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

isolation 수준 (shared/schema-per-tenant/db-per-tenant):
- 3가지 전부 공식 지원: DATABASE / SCHEMA / DISCRIMINATOR
tenant resolution 방식: CurrentTenantIdentifierResolver 인터페이스 (보통 ThreadLocal에서 가져옴). resolution 자체는 framework 위(filter/interceptor)에서 결정.
scale 한계:
- DATABASE: connection pool이 tenant 수 × pool size로 폭증 → connection multiplexing 필요
- SCHEMA: Postgres는 schema 수 수천 단위에서 catalog overhead 발생
- DISCRIMINATOR: index에 tenant_id 포함 필요, query plan 캐시 효율 ↓ 가능성
운영 복잡도:
- DATABASE: Flyway/Liquibase가 tenant 수만큼 마이그레이션 반복
- SCHEMA: Flyway schemas 옵션으로 일괄 처리 가능하나 schema 추가/삭제 자동화 필요
- DISCRIMINATOR: 단일 마이그레이션. 가장 단순
security/compliance: DATABASE > SCHEMA > DISCRIMINATOR 순으로 강함. DISCRIMINATOR는 application bug 한 줄로 cross-tenant leak 가능.
비용: DATABASE가 가장 비쌈. DISCRIMINATOR가 가장 쌈.
장점: Hibernate가 connection acquisition 시 tenant resolver를 자동 호출 → app 코드는 tenant 분기 없음.
단점:
- DISCRIMINATOR는 native query/JDBC bypass 시 leak 위험. JPQL만 사용하면 안전.
- SCHEMA/DATABASE는 connection pool 설계가 까다로움 (HikariCP per tenant vs single pool with USE schema).
ca-tmpl과의 차이: ca-tmpl은 Hibernate Filter 또는 JPA @TenantId (Hibernate 6) 사용 가정. discriminator 전략에 해당. opt-in이라 resolver 자체가 비활성 가능.

같은 주제 다른 raw:
- raw/official-docs/multitenancy-aws-saas-tenant-isolation-whitepaper — AWS 의 Silo/Pool/Bridge 분류
- raw/official-docs/multitenancy-microservices-io-pattern — microservices.io 의 database-per-service 패턴
- raw/company-tech-blogs/multitenancy-stripe-citus-schema-per-tenant — schema-per-tenant 의 Postgres 한계치
- raw/company-tech-blogs/multitenancy-atlassian-tenant-context — shard + tenant context 운영 사례
인용하는 branch:
- raw/branch-notes/feature-tenant-context-policy
- raw/branch-notes/feature-repository-access-permission-contract
인용하는 project:
- raw/project-notes/ca-skeleton-operational-contract (§18)
인용한 wiki 요약: (미작성)

11 KiB Raw Permalink Blame History Unescape Escape