Who owns this data?
Who may observe it?
Who may mutate it?
Where is it physically stored?
How is access scoped by default?
What happens if scoping fails?

repository.findById(id); // hope the caller checks tenant elsewhere

repository.findByTenantIdAndId(tenantId, id);

TenantScopedEntityManager.forCurrentTenant()
    .find(Order.class, orderId);

user_id == tenant_id

Principal identity
Authorization scope
Tenant ownership
Storage routing

Request A sets schema = tenant_a
Connection returned to pool
Request B gets same connection
Schema is still tenant_a
Request B reads tenant A data

before use: set tenant schema
finally: reset/validate schema
on error: discard unsafe connection if state unknown

create table orders (
    tenant_id uuid not null,
    id uuid not null,
    order_number varchar(64) not null,
    status varchar(32) not null,
    created_at timestamptz not null,
    primary key (tenant_id, id),
    unique (tenant_id, order_number)
);

primary key (id),
unique (order_number)

primary key (tenant_id, id),
unique (tenant_id, order_number)

Small tenants     -> shared schema
Medium tenants    -> schema per tenant
Enterprise tenant -> database per tenant
Regulated tenant  -> region-specific database

tenant_id
legal_name
status
plan
region
isolation_mode
datasource_key
schema_name
migration_version
encryption_key_ref
created_at
suspended_at

public record TenantContext(
    UUID tenantId,
    UUID principalId,
    Set<String> roles,
    String region,
    String correlationId
) {}

public final class CurrentTenant {
    private static final ThreadLocal<UUID> TENANT = new ThreadLocal<>();

    public static void set(UUID tenantId) {
        TENANT.set(tenantId);
    }

    public static UUID get() {
        return TENANT.get();
    }

    public static void clear() {
        TENANT.remove();
    }
}

public final class TenantContextHolder {
    private static final ThreadLocal<TenantContext> HOLDER = new ThreadLocal<>();

    public static TenantContext require() {
        TenantContext context = HOLDER.get();
        if (context == null) {
            throw new MissingTenantContextException();
        }
        return context;
    }

    public static void set(TenantContext context) {
        if (context == null) {
            throw new IllegalArgumentException("tenant context must not be null");
        }
        HOLDER.set(context);
    }

    public static void clear() {
        HOLDER.remove();
    }

    private TenantContextHolder() {}
}

public final class TenantContextFilter extends OncePerRequestFilter {
    private final TenantResolver tenantResolver;

    public TenantContextFilter(TenantResolver tenantResolver) {
        this.tenantResolver = tenantResolver;
    }

    @Override
    protected void doFilterInternal(
        HttpServletRequest request,
        HttpServletResponse response,
        FilterChain filterChain
    ) throws ServletException, IOException {
        try {
            TenantContext context = tenantResolver.resolve(request);
            TenantContextHolder.set(context);
            filterChain.doFilter(request, response);
        } finally {
            TenantContextHolder.clear();
        }
    }
}

X-Tenant-Id: 3b2a...

UUID tenantId = UUID.fromString(request.getHeader("X-Tenant-Id"));

Authenticate principal
Load memberships/claims
Resolve requested tenant
Verify principal may act in tenant
Build tenant context

public TenantContext resolve(HttpServletRequest request) {
    Principal principal = authenticationService.requirePrincipal();
    UUID requestedTenantId = extractRequestedTenant(request);

    TenantMembership membership = membershipRepository
        .findActiveMembership(principal.id(), requestedTenantId)
        .orElseThrow(ForbiddenTenantAccessException::new);

    return new TenantContext(
        requestedTenantId,
        principal.id(),
        membership.roles(),
        membership.region(),
        correlationIdProvider.current()
    );
}

create table cases (
    tenant_id uuid not null,
    id uuid not null,
    case_number varchar(64) not null,
    status varchar(32) not null,
    primary key (tenant_id, id),
    unique (tenant_id, case_number)
);

create table case_events (
    tenant_id uuid not null,
    id uuid primary key,
    case_id uuid not null references cases(id)
);

create table case_events (
    tenant_id uuid not null,
    id uuid not null,
    case_id uuid not null,
    event_type varchar(64) not null,
    occurred_at timestamptz not null,
    primary key (tenant_id, id),
    foreign key (tenant_id, case_id) references cases(tenant_id, id)
);

unique (email)

unique (tenant_id, email)

select *
from cases
where tenant_id = ?
  and status = ?
order by created_at desc
limit 50;

create index idx_cases_tenant_status_created
on cases (tenant_id, status, created_at desc);

@MappedSuperclass
public abstract class TenantScopedEntity {

    @Column(name = "tenant_id", nullable = false, updatable = false)
    private UUID tenantId;

    protected TenantScopedEntity() {
    }

    protected TenantScopedEntity(UUID tenantId) {
        this.tenantId = Objects.requireNonNull(tenantId);
    }

    public UUID tenantId() {
        return tenantId;
    }
}

@Entity
@Table(
    name = "cases",
    uniqueConstraints = {
        @UniqueConstraint(
            name = "uk_cases_tenant_case_number",
            columnNames = {"tenant_id", "case_number"}
        )
    }
)
public class CaseEntity extends TenantScopedEntity {

    @EmbeddedId
    private CaseEntityId id;

    @Column(name = "case_number", nullable = false, length = 64)
    private String caseNumber;

    @Enumerated(EnumType.STRING)
    @Column(name = "status", nullable = false, length = 32)
    private CaseStatus status;

    protected CaseEntity() {
    }

    public CaseEntity(UUID tenantId, UUID caseId, String caseNumber) {
        super(tenantId);
        this.id = new CaseEntityId(tenantId, caseId);
        this.caseNumber = requireNonBlank(caseNumber);
        this.status = CaseStatus.DRAFT;
    }
}

@Embeddable
public record CaseEntityId(
    @Column(name = "tenant_id") UUID tenantId,
    @Column(name = "id") UUID id
) implements Serializable {}

id uuid primary key,
tenant_id uuid not null

id uuid primary key,
tenant_id uuid not null,
unique (tenant_id, id)

public interface CaseRepository extends JpaRepository<CaseEntity, UUID> {
    Optional<CaseEntity> findById(UUID id);
}

public interface CaseRepository extends Repository<CaseEntity, CaseEntityId> {

    Optional<CaseEntity> findById(CaseEntityId id);

    @Query("""
        select c
        from CaseEntity c
        where c.id.tenantId = :tenantId
          and c.status = :status
        order by c.createdAt desc
    """)
    List<CaseEntity> findRecentByStatus(
        @Param("tenantId") UUID tenantId,
        @Param("status") CaseStatus status,
        Pageable pageable
    );
}

public final class TenantScopedCaseRepository {
    private final CaseRepository delegate;

    public Optional<CaseEntity> findById(UUID caseId) {
        UUID tenantId = TenantContextHolder.require().tenantId();
        return delegate.findById(new CaseEntityId(tenantId, caseId));
    }
}

public final class CurrentTenantResolver
    implements CurrentTenantIdentifierResolver<String> {

    @Override
    public String resolveCurrentTenantIdentifier() {
        return TenantContextHolder.require().tenantId().toString();
    }

    @Override
    public boolean validateExistingCurrentSessions() {
        return true;
    }
}

public final class TenantDataSourceConnectionProvider
    implements MultiTenantConnectionProvider<String> {

    private final TenantDataSourceRegistry registry;

    public TenantDataSourceConnectionProvider(TenantDataSourceRegistry registry) {
        this.registry = registry;
    }

    @Override
    public Connection getConnection(String tenantIdentifier) throws SQLException {
        return registry.requireDataSource(tenantIdentifier).getConnection();
    }

    @Override
    public void releaseConnection(String tenantIdentifier, Connection connection)
        throws SQLException {
        connection.close();
    }

    @Override
    public Connection getAnyConnection() throws SQLException {
        return registry.defaultDataSource().getConnection();
    }

    @Override
    public void releaseAnyConnection(Connection connection) throws SQLException {
        connection.close();
    }

    @Override
    public boolean supportsAggressiveRelease() {
        return false;
    }

    @Override
    public boolean isUnwrappableAs(Class<?> unwrapType) {
        return unwrapType.isAssignableFrom(getClass());
    }

    @Override
    public <T> T unwrap(Class<T> unwrapType) {
        if (isUnwrappableAs(unwrapType)) {
            return unwrapType.cast(this);
        }
        throw new IllegalArgumentException("Unsupported unwrap type: " + unwrapType);
    }
}

public final class TenantRoutingDataSource extends AbstractRoutingDataSource {
    @Override
    protected Object determineCurrentLookupKey() {
        return TenantContextHolder.require().tenantId();
    }
}

@Transactional
public void handle(Request request) {
    TenantContextHolder.set(resolveTenant(request)); // too late if connection already acquired
    repository.save(...);
}

public void handle(Request request) {
    TenantContextHolder.set(resolveTenant(request));
    try {
        transactionalHandler.handle(request);
    } finally {
        TenantContextHolder.clear();
    }
}

alter table cases enable row level security;

create policy tenant_isolation_on_cases
on cases
using (tenant_id = current_setting('app.tenant_id')::uuid);

set app.tenant_id = '...';

Application authorization
+ tenant-scoped repository/query
+ database constraints/FKs
+ optional row-level security
= defense in depth

@Query("select c from CaseEntity c where c.status = :status")
List<CaseEntity> findByStatus(CaseStatus status);

@Query("""
    select c
    from CaseEntity c
    where c.tenantId = :tenantId
      and c.status = :status
""")
List<CaseEntity> findByTenantAndStatus(UUID tenantId, CaseStatus status);

case_event.tenant_id = tenant_a
case_event.case_id points to tenant_b case

@GetMapping("/admin/cases/{id}")
CaseDto getCase(@PathVariable UUID id) {
    return mapper.toDto(caseRepository.findById(id).orElseThrow());
}

@GetMapping("/admin/tenants/{tenantId}/cases/{caseId}")
CaseDto getCase(
    @PathVariable UUID tenantId,
    @PathVariable UUID caseId
) {
    return adminCaseService.getCase(tenantId, caseId);
}

@Scheduled(fixedDelay = 60_000)
void expireCases() {
    caseRepository.expireOldCases(); // Which tenant?
}

@Scheduled(fixedDelay = 60_000)
void expireCases() {
    for (Tenant tenant : tenantRegistry.activeTenants()) {
        TenantContextHolder.set(tenant.toContext());
        try {
            caseExpirationService.expireForCurrentTenant();
        } finally {
            TenantContextHolder.clear();
        }
    }
}

case:{caseId}

tenant:{tenantId}:case:{caseId}

public record CaseAssignedEvent(
    UUID tenantId,
    UUID caseId,
    UUID assigneeId,
    Instant occurredAt
) {}

create table outbox_events (
    tenant_id uuid not null,
    id uuid not null,
    aggregate_type varchar(100) not null,
    aggregate_id uuid not null,
    event_type varchar(200) not null,
    payload jsonb not null,
    status varchar(32) not null,
    created_at timestamptz not null,
    published_at timestamptz,
    primary key (tenant_id, id)
);

X-Tenant-Id: ...
X-Correlation-Id: ...
X-Event-Id: ...

create table tenant_schema_version (
    tenant_id uuid primary key,
    current_version varchar(64) not null,
    last_migrated_at timestamptz not null,
    last_error text
);

1. Expand: add nullable column/table/index
2. Deploy app that writes both old and new shape
3. Backfill per tenant, throttled
4. Validate per tenant
5. Switch reads
6. Contract old shape after all tenants are safe

create table tenant_backfill_progress (
    tenant_id uuid not null,
    job_name varchar(128) not null,
    last_processed_id uuid,
    status varchar(32) not null,
    updated_at timestamptz not null,
    primary key (tenant_id, job_name)
);

tenant_id
region + tenant_id
tenant_id + created_month
hash(tenant_id)

Partition by tenant_id when one tenant owns 80% of rows.

large tenant -> dedicated database/table partition
small tenants -> shared hash partitions

tenant_id
p50/p95/p99 latency
slow query count
row count
index size
connection usage
lock wait time
queue lag
error rate

Is deletion physical or logical?
What retention rules apply?
Is tenant data under legal hold?
Are audit records retained?
Are backups purged?
Are outbox/inbox records purged?
Are search indexes purged?
Are caches invalidated?
Are object storage files removed?
Are derived analytics records removed?

create table deleted_tenants (
    tenant_id uuid primary key,
    deleted_at timestamptz not null,
    deletion_reason varchar(200),
    purge_batch_id uuid not null
);

tenant_tier = enterprise|standard|trial
isolation_mode = shared|schema|database
region = eu|us|apac
operation = case.search

tenant_id = every tenant UUID

@Test
void tenantCannotReadOtherTenantCase() {
    UUID tenantA = UUID.randomUUID();
    UUID tenantB = UUID.randomUUID();

    UUID caseId = createCaseForTenant(tenantA);

    runAsTenant(tenantB, () -> {
        Optional<CaseDto> result = caseService.findCase(caseId);
        assertThat(result).isEmpty();
    });
}

@Test
void caseNumberUniquenessIsTenantScoped() {
    createCase(tenantA, "CASE-001");
    createCase(tenantB, "CASE-001");

    runAsTenant(tenantA, () -> {
        CaseDto result = caseService.findByCaseNumber("CASE-001");
        assertThat(result.tenantId()).isEqualTo(tenantA);
    });
}

@Test
void cacheKeyMustIncludeTenant() {
    UUID sharedCaseId = UUID.randomUUID();

    createCase(tenantA, sharedCaseId, "A data");
    createCase(tenantB, sharedCaseId, "B data");

    runAsTenant(tenantA, () -> assertThat(service.get(sharedCaseId).title()).isEqualTo("A data"));
    runAsTenant(tenantB, () -> assertThat(service.get(sharedCaseId).title()).isEqualTo("B data"));
}

@Test
void scheduledJobProcessesEachTenantWithinOwnContext() {
    createExpiredCase(tenantA);
    createExpiredCase(tenantB);

    expirationJob.runOnce();

    runAsTenant(tenantA, () -> assertExpiredCount(1));
    runAsTenant(tenantB, () -> assertExpiredCount(1));
}

findById(UUID id)
findAll()
deleteAll()
@Query without tenant predicate
native query without tenant predicate
cacheable method without tenant in key

@GetMapping("/cases/{id}")
CaseDto get(@RequestHeader("X-Tenant-Id") UUID tenantId, @PathVariable UUID id) {
    return service.get(tenantId, id);
}

repository.findById(id)

@Cacheable(cacheNames = "case", key = "#caseId")
CaseDto get(UUID caseId) { ... }

@Cacheable(
    cacheNames = "case",
    key = "T(com.acme.TenantContextHolder).require().tenantId() + ':' + #caseId"
)
CaseDto get(UUID caseId) { ... }

TenantContextHolder.set(context);
filterChain.doFilter(request, response);

admin can query all tenant rows by default

admin must choose tenant, reason, ticket/reference, and access is audited

select tenant_id, count(*) from huge_table group by tenant_id;

replica / warehouse / materialized rollup / async metrics pipeline

- Many small tenants.
- Some large enterprise tenants.
- Users can belong to multiple tenants.
- Cases have tenant-local case numbers.
- Case comments, attachments, and audit records must never cross tenants.
- Enterprise tenants may require dedicated database later.
- Tenant deletion must support legal hold.
- Background jobs expire stale cases per tenant.

Shared schema for standard tenants, hybrid-ready tenant registry.
Tenant-aware composite unique constraints and FKs.
Tenant context resolved after authentication and before transaction.
Repositories do not expose tenant-agnostic findById.
Outbox/inbox records include tenant_id.
Large tenants can be rehomed by registry route + data copy + cutover.