← 목록으로

대기측정 보고서 시스템설계

멀티테넌트 구조를 스키마 방식에서 행 단위 방식으로 바꾼 이유

고객사마다 스키마를 나누던 대기측정 보고서 시스템을 공용 테이블과 회사 구분 컬럼으로 바꾼 이유, 전환 순서, 격리를 지키려고 둔 장치와 테스트를 정리했습니다.

기술
Spring Boot, JPA, PostgreSQL
결과
가입마다 스키마 생성(초기화 DDL 80개) → 공용 테이블에 행 추가 (개발 단계 전환)

대기측정 보고서 시스템은 운영 중인 기존 시스템을 여러 고객사가 함께 쓸 수 있는 구조로 다시 만드는 프로젝트입니다. 처음에는 고객사마다 PostgreSQL 스키마를 따로 두었다가, 2026년 7월에 공용 테이블과 회사 구분 컬럼으로 나누는 행 단위 방식으로 바꿨습니다. 스키마를 나누니 같은 테이블이 스키마마다 생겨, 구조를 바꿀 때마다 모든 스키마에 적용해야 했기 때문입니다. 바꾼 뒤에는 조회마다 회사 조건이 빠지지 않아야 해서, Hibernate의 @TenantId로 조건을 한 곳에서 붙이고 회사 간 교차 조회를 막는 테스트를 붙였습니다. 백엔드는 Spring Boot와 JPA입니다. 이 전환은 운영에 올리기 전 개발 단계에서 했습니다.

처음 택한 방식: 스키마 나누기

2025년 9월에 시작할 때는 고객사마다 스키마를 따로 두었습니다. 요청이 들어오면 현재 고객사를 식별하고, 그 고객사의 스키마로 연결을 바꾸는 구조입니다. 데이터가 스키마 단위로 나뉘어 있어서 고객사별 격리가 분명합니다. 격리가 지켜지는지는 실제 PostgreSQL 컨테이너를 띄우는 통합 테스트(Testcontainers)로 확인하도록 구성했습니다.

바꾼 이유: 테이블 변경을 모든 스키마에 적용해야 했다

스키마를 나누면 같은 테이블이 스키마마다 생깁니다. 테이블 구조를 바꾸는 변경을 모든 스키마에 적용해야 했고, 같은 작업을 여러 곳에 반복하면 빠뜨리는 곳이 생기기 쉽습니다. 가입할 때마다 스키마를 새로 만드는 코드와 초기화 DDL도 따로 관리해야 했습니다. 전환할 때 걷어낸 초기화 DDL이 80개였습니다.

전환 순서

  1. 토큰에 담는 테넌트 식별 값을 문자열에서 회사 식별자(숫자)로 바꿨습니다.
  2. 루트 엔티티에 회사 식별자 기준의 격리를 적용하고, 서비스와 컨트롤러를 회사 식별자 기준으로 바꿨습니다.
  3. 가입마다 스키마를 만들던 코드와 초기화 DDL 80개를 걷어냈습니다.
  4. 회사 조건을 붙이는 방식은 필터와 AOP로 먼저 만들었다가 Hibernate의 @TenantId로 바꿨습니다. @TenantId를 쓰면 엔티티를 조회할 때 회사 조건이 자동으로 붙어서, 쿼리마다 조건을 직접 쓰지 않아도 됩니다.
  5. 기존 스키마의 데이터는 개발 서버에서만 옮겼습니다. 운영 전이어서 운영 데이터를 옮기는 일은 없었습니다.

바꾼 뒤 신경 쓴 점

행 단위 방식에서는 조건이 한 쿼리라도 빠지면 다른 고객사의 데이터가 섞여 보일 수 있습니다. 그래서 다음을 챙겼습니다.

  • 최상위 관리 회사 소속은 전체 회사를 조회할 수 있게 하고, 그 밖의 사용자는 자기 회사 범위로 묶었습니다.
  • 전체 조회를 뜻하는 루트 식별자를 0으로 분리해, 특정 회사의 데이터에도 회사 조건이 적용되게 고쳤습니다.
  • 회사 A의 사용자가 회사 B의 데이터를 조회하지 못하는지 확인하는 격리 시나리오 테스트를 추가했습니다.

얻은 것, 버린 것, 배운 점

구분내용
얻은 것테이블 변경을 한 번만 적용합니다. 가입할 때 스키마를 만들 필요가 없습니다.
버린 것스키마 단위의 분명한 격리입니다. 격리는 이제 코드의 장치와 테스트에 기대야 합니다.
한계@TenantId는 Hibernate를 거치는 조회에만 붙습니다. MyBatis로 쓴 쿼리는 회사 조건을 직접 넣어야 합니다. 전환 전후를 수치로 비교하지 않았습니다.
배운 점고객사 수와 변경 빈도를 먼저 보고 골라야 합니다. 열 달 뒤에 구조를 바꾸느라 엔티티, 서비스, 컨트롤러를 다시 손봤습니다.