---
title: Hibernate ORM User Guide — Multi-tenancy
source_type: official-doc
url: https://docs.jboss.org/hibernate/orm/current/userguide/html_single/Hibernate_User_Guide.html#multitenacy
archive_url:
status: raw
confidence: high
tags: [ca-multi-tenancy, hibernate, schema-per-tenant, database-per-tenant, discriminator]
related_projects: [ca-skeleton-operational-contract]
related_branches: [feature-tenant-context-policy, feature-repository-access-permission-contract]
created: 2026-05-22
last_reviewed: 2026-05-27
---

# 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 자체가 비활성 가능.

## Related / 관련

- 같은 주제 다른 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 요약: (미작성)