전체 메뉴

테마

Chapter 11

Oracle 연결과 JSON 매핑

Spring Boot에서 H2와 Oracle Profile을 분리하고 Oracle JSON 함수와 MyBatis TypeHandler로 JSON 컬럼을 안전하게 질의하고 변환합니다.

난이도
중급 심화
예상 학습
180분
Spring Boot 기준
Spring Boot 4.1.1
JDK 기준
JDK 21
최종 검토

전체 24개 Chapter 중 Chapter 11입니다. 예제 코드는 공개 저장소 spring-boot-curriculum의 examples/ch13-oracle-connection 폴더에서 확인할 수 있습니다.

오후 햇살이 드는 책상에서 데이터베이스 연결에 성공한 화면을 보며 기뻐하는 아빠와 아들 개발자
Profile과 환경 변수로 Oracle 연결 설정을 안전하게 분리합니다.

Learning goals

오늘 배울 내용

  • H2와 Oracle 설정을 Profile과 환경 변수로 분리하기
  • Oracle JSON 함수의 역할과 반환 타입 구분하기
  • JSON 숫자와 문자열 비교 차이를 테스트로 확인하기
  • MyBatis TypeHandler로 JSON 컬럼과 Java record 변환하기
  • 조건부 테스트의 실행과 건너뜀을 구분하기
  1. Profile 분리
  2. Oracle 연결
  3. JSON 함수 질의
  4. TypeHandler 변환
  5. 변환 규칙 검증
이 Chapter의 진행 흐름

지금까지는 JVM 안의 H2에 붙었습니다. 실무에서는 Oracle 같은 외부 데이터베이스에 붙습니다. 그런데 Oracle은 개발 PC마다 있지도 않고, 접속 정보를 코드에 적을 수도 없습니다. 테스트는 Oracle이 없는 환경에서도 돌아야 합니다. 이 Chapter의 전반은 이 문제를 푸는 방법입니다.

후반은 JSON입니다. 상품마다 속성이 다릅니다. 노트북은 무게와 색상, 마우스는 연결 방식, 옷은 사이즈가 있습니다. 속성마다 컬럼을 만들면 컬럼이 끝없이 늘어납니다. 속성을 JSON 한 덩어리로 저장하고 필요한 값만 SQL로 꺼내 쓰는 방법을 Oracle로 다루고, 그 JSON을 자바 record로 바로 읽고 쓰는 방법과 데이터베이스마다 JSON 지원이 어떻게 다른지를 정리합니다.

이 Chapter에서 만드는 것

만드는 것 설명
Profile 분리 설정 기본 H2, oracle Profile일 때만 Oracle. 접속 정보는 환경 변수
compose.yml 비밀번호를 파일에 적지 않는 Oracle Free 컨테이너
Oracle 전용 테스트 Oracle이 있을 때만 실행되고 없으면 건너뜀
상품 속성 JSON 질의 JSON_VALUE, JSON_QUERY, JSON_EXISTS, JSON_TABLE
JsonTypeHandler JSON 컬럼과 record를 오가는 MyBatis 변환기
테스트 ch13: H2 4건 + Oracle 6건, ch14: 1건 + Oracle 10건, ch15: 14건 + Oracle 3건

준비물과 예제 저장소

이 Chapter의 구조와 예제 모듈

이 Chapter는 세 예제를 순서대로 씁니다(Chapter 번호와 예제 모듈 번호가 다릅니다).

다루는 절 예제 모듈 핵심
“기본은 H2, oracle Profile일 때만 Oracle”부터 “Oracle 연결 오류 읽기”까지 examples/ch13-oracle-connection Profile로 H2/Oracle 전환, 컨테이너 접속, 조건부 테스트, 접속 오류
“JSON을 저장하는 두 방법”부터 “숫자 비교와 API, JSON 함수 오류”까지 examples/ch14-oracle-json Oracle JSON 타입과 CLOB + IS JSON, JSON 함수 질의(oracle Profile 전용)
“DB별 JSON 지원 비교”부터 “시행착오와 오류”까지 examples/ch15-json-typehandler DB별 JSON 지원 비교, TypeHandler로 JSON과 record 사이 변환(H2와 Oracle)

검증 범위

구분 어디서 확인했나
H2에서 도는 코드(ch13 기본 Profile, ch15 기본 Profile) 로컬 Docker(JDK 21)에서 빌드·테스트 실행 가능
Oracle에서 도는 코드(ch13 oracle Profile, ch14, ch15의 Oracle 테스트) 예제를 작성할 때 Oracle 23ai Free 컨테이너에서 실행한 기록. 이후 Oracle 컨테이너를 다시 띄워 재검증하지는 않았습니다
PostgreSQL, MariaDB 문서 수준 비교이며 이 저장소에 예제가 없어 MyBatis로 확인하지 않았습니다

Oracle의 JSON 기능은 다른 데이터베이스와 같지 않습니다. 함수 이름, 경로 문법, 타입 이름이 DB마다 다르므로 이 Chapter의 질의 SQL을 다른 DB에 그대로 옮길 수 없습니다. 절마다 어느 DB에서 확인한 내용인지 밝혀 둡니다.

사전 지식

  • Chapter 02의 Profile과 환경 변수, Chapter 08의 MyBatis XML, Chapter 07의 DataSource.
  • Oracle 컨테이너를 쓰려면 Docker가 필요합니다. 없어도 H2 부분은 따라올 수 있습니다.
  • 코드는 examples/ch13-oracle-connection, ch14-oracle-json, ch15-json-typehandler입니다.

확인 환경

Oracle 부분의 실행 결과는 gvenzl/oracle-free:23-slim-faststart(Oracle Database 23ai Free) 컨테이너에서 얻은 값입니다. 19c 같은 이전 버전, Wallet 접속은 다루지 않았습니다. Windows 실행은 검증하지 못했습니다.

기본은 H2, oracle Profile일 때만 Oracle

Oracle에 붙으려면 JDBC 드라이버, URL, 계정이 필요합니다. 하지만 모든 개발자 PC에 Oracle이 있을 수는 없고 CI에서 매번 띄우기도 부담입니다. 해결책은 기본은 H2, oracle Profile이 켜질 때만 Oracle로 나누는 것입니다. Chapter 02의 Profile이 쓰이는 대표적 사례입니다.

설정을 둘로 나눈다

application.yml은 H2이고, application-oracle.yml은 oracle Profile이 켜질 때 위에 덮어씁니다.

# application.yml (기본)
spring:
  datasource:
    url: jdbc:h2:mem:curriculum-${random.uuid}
    username: sa
    password: ""
  sql:
    init:
      # schema-h2.sql, data-h2.sql만 읽는다. Oracle용 스크립트는 oracle Profile에서 따로 쓴다.
      platform: h2
# application-oracle.yml
spring:
  datasource:
    url: ${ORACLE_URL}
    username: ${ORACLE_USERNAME}
    password: ${ORACLE_PASSWORD}
    hikari:
      pool-name: oracle-pool
      maximum-pool-size: 5
      connection-test-query: SELECT 1 FROM DUAL
  sql:
    init:
      mode: never

주요 코드 설명

  • 파일 이름 application-oracle.yml의 oracle이 Profile 이름입니다. --spring.profiles.active=oracle로 켜면 기본 설정 위에 이 파일이 덮어씁니다(Chapter 02의 우선순위).
  • ${ORACLE_URL} 같은 환경 변수 참조: 값은 파일에 없습니다. 비밀값이 저장소에 들어가지 않게 하는 가장 단순한 방법입니다.
  • connection-test-query: SELECT 1 FROM DUAL: 풀이 연결이 살아 있는지 확인하는 쿼리입니다. 이 예제는 구버전 Oracle과도 호환되도록 FROM DUAL 형태를 씁니다. Oracle 23ai(Free 23 포함) 이상은 FROM 없는 SELECT 1도 허용하므로 DUAL이 반드시 필요한 것은 아니고, 그 이전 버전에서는 필수였습니다(Oracle 공식 문서). 이 버전 차이는 문서로 확인했고 Oracle에 직접 질의해 보지는 않았습니다.
  • sql.init.mode: never: 운영 데이터베이스에 스크립트를 자동 실행하지 않겠다는 뜻입니다. Chapter 07에서 외부 DB는 기본이 never라고 했는데, 의도를 드러내려고 명시했습니다.
  • 기본 설정의 sql.init.platform: h2: schema-h2.sql, data-h2.sql만 읽게 합니다.

드라이버는 둘 다 둔다

runtimeOnly 'com.h2database:h2'
runtimeOnly 'com.oracle.database.jdbc:ojdbc11:23.26.3.0.0'

JDBC URL을 보고 알맞은 드라이버가 골라집니다(Chapter 07의 JDBC 드라이버). 두 드라이버가 클래스패스에 있어도 충돌하지 않습니다. ojdbc11은 Java 11 이상용 Oracle 드라이버입니다.

스키마도 DB별로 나눈다

타입 이름부터 다릅니다.

항목 H2 Oracle
큰 정수 BIGINT NUMBER(19)
정수 INT NUMBER(10)
문자열 VARCHAR(50) VARCHAR2(50)
생성 시각 기본값 CURRENT_TIMESTAMP SYSTIMESTAMP

H2용은 schema-h2.sql, Oracle용은 oracle/schema-oracle.sql에 두었습니다. 같은 파일 하나로 두 DB를 모두 지원하려 하면 SQL이 복잡해지므로 DB별로 나누는 편이 단순합니다. 마이그레이션 도구가 이 문제를 어떻게 다루는지는 이 Chapter에서 다루지 않았습니다.

따라 하기: H2 Profile로 먼저 확인

Oracle이 없어도 기본 Profile은 H2로 동작합니다.

./gradlew :examples:ch13-oracle-connection:bootRun
curl http://localhost:8080/db/info

product가 H2, activeProfiles가 []이면 성공입니다. Oracle Profile 실행은 아래 “접속 정보는 환경 변수, Oracle은 컨테이너로” 절에서 다룹니다.

두 설정의 차이를 표로 보기

항목 application.yml(기본, H2) application-oracle.yml(Oracle)
JDBC URL jdbc:h2:mem:... ${ORACLE_URL} (환경 변수)
계정 sa ${ORACLE_USERNAME}, ${ORACLE_PASSWORD}
스크립트 sql.init.mode: always, platform: h2 sql.init.mode: never
풀 헬스체크 쿼리 드라이버 기본 SELECT 1 FROM DUAL(Oracle 23 이상은 SELECT 1도 가능)

직접 해 보기

  1. Profile 없이 bootRun해서 H2로 뜨는 것을 확인하세요. GET /db/info의 product가 H2입니다(아래 “/db/info로 확인” 절).
  2. application-oracle.yml의 ${ORACLE_URL} 대신 임의 문자열을 적으면 어떤 시점에 어떤 오류가 날지 예측해 보세요. 이 Chapter에서는 환경 변수 자체를 틀리게 한 오류만 다뤘습니다.
  3. 두 DB의 타입 이름 표에 TEXT/CLOB 같은 행을 더 추가해 보세요(자신의 경험을 바탕으로).

접속 정보는 환경 변수, Oracle은 컨테이너로

Oracle을 PC에 직접 설치하지 않고 컨테이너로 띄우면 간단합니다. 이 절에서는 compose.yml로 Oracle Free를 띄우고, 환경 변수 세 개로 접속 정보를 넘겨 oracle Profile로 실행하는 전 과정을 봅니다. 비밀번호는 어디에도 적지 않습니다.

compose.yml

# 로컬 Oracle Free 컨테이너. 비밀번호는 파일에 적지 않고 실행할 때 환경 변수로 넘긴다.
#
#   ORACLE_SYS_PASSWORD=... ORACLE_APP_PASSWORD=... docker compose up -d
#
# 접속 URL: jdbc:oracle:thin:@//localhost:1521/FREEPDB1
services:
  oracle:
    image: gvenzl/oracle-free:23-slim-faststart
    ports:
      - "1521:1521"
    environment:
      ORACLE_PASSWORD: ${ORACLE_SYS_PASSWORD:?ORACLE_SYS_PASSWORD를 지정하세요}
      APP_USER: curriculum
      APP_USER_PASSWORD: ${ORACLE_APP_PASSWORD:?ORACLE_APP_PASSWORD를 지정하세요}
    healthcheck:
      test: ["CMD", "healthcheck.sh"]
      interval: 10s
      timeout: 5s
      retries: 30

두 개의 비밀번호(관리자용, 앱용)는 컨테이너에, 앱용 비밀번호와 접속 정보는 앱에 환경 변수로만 전달됩니다.

주요 코드 설명

  • image: gvenzl/oracle-free:23-slim-faststart: Oracle Database 23ai Free를 담은 커뮤니티 이미지입니다. faststart는 시작을 빠르게 한 변형입니다.
  • ports: "1521:1521": 컨테이너의 Oracle 리스너 포트를 PC의 1521에 연결합니다.
  • ${ORACLE_SYS_PASSWORD:?메시지}: 환경 변수가 없으면 시작하지 않고 메시지를 보여 줍니다. 비밀번호를 빠뜨린 채 실행되는 일을 막습니다. 비밀번호 값은 파일에 없습니다.
  • APP_USER: curriculum: 이미지가 앱용 계정을 하나 만들어 줍니다. 비밀번호는 APP_USER_PASSWORD로 받습니다.
  • healthcheck: 컨테이너가 실제로 접속을 받을 준비가 되었는지 주기적으로 확인합니다.

실행

ORACLE_SYS_PASSWORD='<정한 값>' ORACLE_APP_PASSWORD='<정한 값>' docker compose up -d

컨테이너가 준비되면 애플리케이션용 환경 변수 세 개를 정하고 oracle Profile로 실행합니다.

export ORACLE_URL='jdbc:oracle:thin:@//localhost:1521/FREEPDB1'
export ORACLE_USERNAME='curriculum'
export ORACLE_PASSWORD='<정한 값>'
./gradlew :examples:ch13-oracle-connection:bootRun --args='--spring.profiles.active=oracle'
  • JDBC URL의 형식은 jdbc:oracle:thin:@//호스트:포트/서비스이름입니다. FREEPDB1은 이 이미지의 기본 서비스 이름입니다.
  • <정한 값>은 직접 정한 비밀번호이며 이 절과 저장소 어디에도 적지 않았습니다. 터미널 기록에 남지 않게 하려면 환경 변수를 파일에서 읽는 등의 방법을 쓸 수 있습니다. 이 Chapter는 그 방법을 다루지 않았습니다.

/db/info로 확인

어떤 Profile로 어떤 데이터베이스에 붙었는지만 보여 주는 확인용 엔드포인트입니다. 접속 URL이나 계정은 응답에 싣지 않습니다.

GET /db/info
  -> 200 {"activeProfiles":["oracle"],"product":"Oracle","driver":"Oracle JDBC driver","ping":1}

ping은 Oracle에서 SELECT 1 FROM DUAL로 확인한 값입니다. DUAL을 쓰는 이유는 앞의 “설정을 둘로 나눈다” 절에서 설명했습니다. H2에서는 SELECT 1만 씁니다. 기본 Profile에서는 product가 H2로, activeProfiles가 빈 배열로 나옵니다.

항목 기본 Profile oracle Profile
activeProfiles [] ["oracle"]
product H2 Oracle
핑 쿼리 SELECT 1 SELECT 1 FROM DUAL(Oracle 23 이상은 SELECT 1도 가능)

따라 하기(Oracle 컨테이너를 쓸 수 있는 환경)

  1. 비밀번호를 정해 docker compose up -d로 컨테이너를 띄웁니다.
  2. 컨테이너가 healthy가 될 때까지 기다립니다. 처음에는 이미지 내려받기와 초기화로 시간이 걸립니다.
  3. 환경 변수 세 개를 정하고 oracle Profile로 앱을 실행합니다.
  4. curl http://localhost:8080/db/info의 product가 Oracle이면 성공입니다.

Oracle 컨테이너를 사용할 수 없는 환경이라면 이 절은 읽기만 하고, 같은 구조를 H2로 확인한 앞의 “따라 하기: H2 Profile로 먼저 확인” 실습까지 진행해도 됩니다.

직접 해 보기

  1. 컨테이너를 띄우고 위 순서대로 접속해 /db/info가 Oracle을 보여 주는지 확인하세요. Docker가 없다면 이 과정은 건너뛰고 기본 Profile만 확인해도 됩니다.
  2. ORACLE_APP_PASSWORD 없이 docker compose up을 실행해 :? 메시지를 확인하세요.
  3. 응답에 접속 URL을 싣지 않은 이유를 한 문장으로 적어 보세요.

Oracle이 있을 때만 도는 테스트

Oracle이 필요한 테스트를 그대로 두면 Oracle이 없는 PC와 CI에서 build가 실패합니다. 반대로 모두 빼면 Oracle 동작을 검증할 수 없습니다. 해법은 조건부 테스트입니다. 환경 변수가 있을 때만 실행하고 없으면 건너뜁니다.

조건부 테스트

@Tag("oracle")
@EnabledIfEnvironmentVariable(named = "ORACLE_URL", matches = ".+")
@SpringBootTest
@ActiveProfiles("oracle")
class OracleConnectionTests { ... }

주요 코드 설명

  • @EnabledIfEnvironmentVariable(named = "ORACLE_URL", matches = ".+"): 환경 변수 ORACLE_URL이 비어 있지 않을 때만(.+는 한 글자 이상) 이 클래스의 테스트를 실행합니다.
  • @ActiveProfiles("oracle"): 이 테스트에서 oracle Profile을 켭니다. Chapter 02의 Profile을 테스트에서 지정하는 방법입니다.
  • @Tag("oracle"): 테스트에 이름표를 붙입니다. 이름표별로 실행을 나눌 때 씁니다(예: CI에서 Oracle 잡만 실행).
  • 반대로 H2 테스트(H2ProfileTests)는 환경 변수와 무관하게 항상 실행됩니다.

건너뛴 테스트는 SKIPPED

그래서 ./gradlew build는 Oracle이 없는 PC에서도 통과합니다. 건너뛴 테스트는 결과에 SKIPPED로 남습니다.

환경 H2 테스트 Oracle 테스트 build
Oracle 없음 4건 실행·통과 6건 SKIPPED 통과
Oracle 있음(ORACLE_URL 설정) 4건 실행·통과 6건 실행·통과 통과

환경이 있는 곳에서는 같은 테스트가 실제로 실행됩니다. 이 저장소의 CI는 일회용 Oracle 컨테이너를 띄우는 별도 잡에서 이 테스트를 돌립니다. Chapter 22 운영에서 CI 구성을 다룹니다.

주의: SKIPPED는 통과가 아니다

SKIPPED는 “실행하지 않았다”는 뜻이지 검증되었다는 뜻이 아닙니다. 건너뛴 테스트가 있는 build 성공만 보고 “Oracle에서 동작 확인”이라고 말하면 안 됩니다. 이 Chapter의 Oracle 결과는 컨테이너에서 실제로 실행된 값만 적었습니다.

따라 하기

  1. Oracle 환경 변수 없이 ./gradlew :examples:ch13-oracle-connection:test를 실행합니다.
  2. 결과에서 H2 테스트는 PASSED, Oracle 테스트는 SKIPPED로 표시되는지 확인합니다.
  3. build가 성공해도 Oracle 테스트는 실행되지 않았다는 점을 기억하고, Oracle 동작을 주장할 때는 Oracle 테스트가 실제로 PASSED로 실행된 결과만 근거로 삼습니다.

SKIPPED를 어떻게 다룰까

질문 답
CI가 초록색인데 Oracle이 검증되었나? Oracle 테스트가 실행되는 잡이 있고 그 잡이 통과해야 검증된 것
로컬에서는 SKIPPED여도 괜찮나? 로컬은 괜찮지만, CI에서는 실제로 실행되는 경로가 있어야 함
환경 변수를 비워 두면? 조건이 거짓이라 테스트가 건너뛰어짐

확인 문제

  1. @EnabledIfEnvironmentVariable이 거짓일 때 테스트는 실패하나요, 건너뛰나요?
  2. Oracle 테스트를 CI에서 별도 잡으로 두는 이유는 무엇인가요?

답: 1) 건너뜁니다(SKIPPED). 2) 일반 빌드를 가볍게 유지하면서도 Oracle 컨테이너가 있는 잡에서는 테스트를 실제로 실행하기 위해서입니다.

직접 해 보기

  1. Oracle 없이 ./gradlew :examples:ch13-oracle-connection:build를 실행하고 테스트 결과에서 SKIPPED를 찾아보세요.
  2. ORACLE_URL을 설정하지 않고 Oracle 테스트만 지정해 실행하면 어떻게 되는지 관찰하세요.
  3. 팀 프로젝트에서 외부 시스템이 필요한 테스트를 어떻게 분리하고 있는지 떠올려 보세요.

같은 Mapper를 Oracle에서 돌렸더니 달라진 것

Chapter 08과 같은 방식의 Mapper를 Oracle에서 실행했습니다. 대부분은 H2와 같게 동작했지만, 세 가지가 달랐습니다. 이 차이를 알아야 두 DB를 오가는 코드를 안전하게 쓸 수 있습니다.

같게 동작한 것

OFFSET ... ROWS FETCH NEXT ... ROWS ONLY 페이징(Chapter 09), 식별 컬럼의 생성 키 받기(Chapter 08), UNIQUE 위반이 DuplicateKeyException으로 번역되는 것은 H2와 같게 동작했습니다. 표준 SQL과 Spring의 예외 번역 덕분입니다.

다른 것 1: null을 넣었더니 JDBC 타입 오류가 났다

선택 컬럼 nickname에 null을 넣는 테스트가 Oracle에서 실패했습니다.

TypeException: Could not set parameters for mapping: ParameterMapping{property='nickname', ...}
Cause: org.apache.ibatis.type.TypeException: Error setting null for parameter #3 with JdbcType OTHER . Try setting ...

값이 null이면 MyBatis는 드라이버에 “이 자리의 JDBC 타입”을 알려 줘야 하는데, 알 수 없을 때 기본값으로 OTHER를 보내고 Oracle 드라이버가 이것을 받아들이지 못합니다. jdbc-type-for-null 설정으로 기본 타입을 바꿔야 합니다. 처음에 이렇게 적었는데도 같은 오류가 그대로 났습니다.

mybatis:
  configuration:
    jdbc-type-for-null: NULL

YAML에서 따옴표 없는 NULL은 문자열 “NULL”이 아니라 null 값이기 때문에, 설정이 아예 비어 있는 것과 같았습니다. 따옴표로 감싸니 해결되었습니다.

    jdbc-type-for-null: "NULL"

증상은 데이터베이스 쪽에서 났지만 원인은 설정 파일의 표기였습니다.

다른 것 2: 빈 문자열이 NULL로 저장된다

Oracle은 빈 문자열("")을 NULL로 저장합니다. 닉네임에 빈 문자열을 넣고 다시 읽으면 null입니다.

User user = new User("park", "park@example.com", "", 42);
mapper.insert(user);

assertNull(mapper.findById(user.getId()).getNickname());

H2나 다른 데이터베이스에서는 빈 문자열이 그대로 남으므로, 두 데이터베이스를 오가는 코드는 “빈 값”을 null과 빈 문자열 중 하나로 통일해서 다뤄야 합니다. 예를 들어 서비스에서 빈 문자열을 null로 바꿔 저장하는 규칙을 둘 수 있습니다. 이 Chapter는 그 통일 방법을 정하지 않았고 차이만 확인했습니다.

다른 것 3: 테이블 스크립트는 한 번만 실행해야 한다

외부 데이터베이스는 프로세스를 다시 시작해도 테이블이 남아 있습니다. 같은 CREATE TABLE을 또 실행하면 ORA-00955: name is already used by an existing object가 납니다. 이 오류 문구는 CI에서 두 테스트가 같은 테이블을 동시에 만들려다 난 로그로 확인했고, 재시작 시나리오 자체는 따로 재현하지 않았습니다. 그래서 oracle Profile은 시작 시 스크립트를 자동으로 돌리지 않고(앞의 “설정을 둘로 나눈다” 절의 mode: never), 테스트가 시작 전에 DROP TABLE IF EXISTS users(23ai 구문)로 지우고 다시 만듭니다. DROP TABLE IF EXISTS는 23ai 구문이라 이전 버전에서는 다른 방식이 필요합니다.

항목 H2(인메모리) Oracle(외부)
재시작 후 테이블 사라짐 남아 있음
시작 시 스크립트 자동 실행 자동 실행 안 함

세 차이를 한 장으로 정리

차이 H2에서 Oracle에서 대응
null 바인딩 기본 설정으로 통과 ORA-17004(JDBC 타입 OTHER) jdbc-type-for-null: "NULL"(따옴표 필수)
빈 문자열 "" 그대로 저장 NULL로 저장 서비스에서 빈 문자열을 null로 통일
스크립트 재실행 인메모리라 매번 새로 시작 ORA-00955 스크립트를 한 번만 실행하거나 존재 여부 확인

따라 하기(H2에서 가능한 부분)

H2와 Oracle의 첫 번째 차이는 설정 파일의 문자열 표기와 관련이 있어, Oracle 없이도 YAML이 값을 어떻게 읽는지는 확인할 수 있습니다. Chapter 02에서 따옴표 없는 !가 빈 값이 되는 경우를 봤듯이, 따옴표 없는 NULL도 문자열이 아니라 null 값으로 해석되어 설정이 비어 있는 것과 같아집니다. 이 절의 Oracle 결과는 예제를 작성할 때 컨테이너에서 확인한 것입니다.

직접 해 보기

  1. jdbc-type-for-null을 따옴표 없이 NULL로 적고 H2에서도 같은 오류가 나는지 확인하세요. H2에서는 문제가 없었다는 것이 이 Chapter의 결과입니다.
  2. 빈 문자열을 null로 통일하는 서비스 규칙을 한 줄로 적어 보세요(value == null || value.isBlank() ? null : value 등).
  3. 이미 테이블이 있는 외부 DB에서 schema.sql을 자동 실행하면 어떤 일이 벌어질지 설명해 보세요.

Oracle 연결 오류 읽기

Oracle 연결 오류는 번호(ORA-)가 원인을 가르쳐 줍니다. 아래는 이 예제의 설정을 한 군데씩 바꿔 Oracle 컨테이너에 붙여 얻은 결과입니다. 바꾼 설정은 되돌렸고 저장소에는 올리지 않았습니다.

접속 실패 세 가지

환경 변수만 바꿔서 같은 테스트를 돌렸습니다. 모두 CannotGetJdbcConnectionException: Failed to obtain JDBC Connection 아래에 Caused by로 번호가 붙었습니다.

만든 실수 얻은 메시지
비밀번호 틀림 ORA-01017: invalid credential or not authorized; logon denied
서비스 이름 틀림(/NOSUCH) ORA-12514: Cannot connect to database. Service NOSUCH is not registered with the listener at host ... port 1521
포트 틀림(1599) ORA-12541: Cannot connect. No listener at host ... port 1599

위쪽 Failed to obtain JDBC Connection은 세 경우가 같으므로 Caused by의 ORA 번호를 봅니다. 12514는 호스트와 포트까지는 닿았고 서비스 이름이 틀렸다는 뜻이고, 12541은 그 포트에서 아무도 듣지 않는다는 뜻입니다. 둘을 구분하면 URL의 어느 부분을 의심할지 정해집니다. 이 실험에서 테스트 10건 중 H2 쪽 4건은 통과하고 Oracle 쪽 6건이 실패했습니다.

null을 넣을 때만 ORA-17004

jdbc-type-for-null: "NULL" 설정을 OTHER로 바꾸거나, 따옴표 없이 NULL로 적으면 같은 오류가 납니다. 후자는 YAML이 NULL을 문자열이 아니라 null 값으로 읽어 기본값(OTHER)이 적용되기 때문입니다.

MyBatisSystemException: ### Error updating database.  Cause: org.apache.ibatis.type.TypeException: Could not set parameters for mapping: ParameterMapping{property='nickname', ... jdbcType=null ...}
Cause: java.sql.SQLException: ORA-17004: Invalid column type: 1111

테스트 10건 중 nickname에 null이 들어가는 3건만 실패했고, H2에서는 같은 설정이 문제를 일으키지 않았습니다. 값이 null일 때만 실패하고 DB 종류에 따라 갈린다는 점이 단서입니다. 메시지의 1111은 JDBC의 OTHER 타입 번호입니다.

접속이 안 될 때 점검하는 순서

  1. docker ps로 Oracle 컨테이너가 떠 있고 healthy인지 확인합니다.
  2. ORACLE_URL의 형식이 jdbc:oracle:thin:@//호스트:포트/서비스이름인지 봅니다. 이 이미지의 서비스 이름은 FREEPDB1입니다.
  3. 환경 변수 세 개가 앱을 실행하는 같은 셸에 설정되어 있는지 echo $ORACLE_URL로 확인합니다(비밀번호는 출력하지 않습니다).
  4. 그래도 안 되면 앞의 “접속 실패 세 가지” 표와 아래 “증상별 점검표”로 돌아가 ORA 번호로 원인을 좁힙니다.

이 절의 Oracle 오류 메시지는 예제를 작성할 때 Oracle 컨테이너에서 얻은 것이며, 이후 다시 재현하지는 않았습니다.

증상별 점검표

증상 가장 먼저 볼 것
ORA-01017 사용자 이름, 비밀번호 환경 변수
ORA-12514 URL 끝의 서비스 이름
ORA-12541 호스트, 포트, 컨테이너 실행 여부
ORA-17004 (null 입력) jdbc-type-for-null과 YAML 따옴표

직접 해 보기

  1. Oracle이 있다면 환경 변수 비밀번호를 틀리게 하고 ORA-01017을 직접 확인하세요.
  2. 컨테이너를 멈추고 같은 테스트를 돌려 ORA-12541 계열 메시지가 나오는지 관찰하세요. 이 Chapter에서는 포트를 틀리게 한 경우만 확인했습니다.
  3. 오류 로그에서 Caused by를 아래에서부터 읽는 연습을 해 보세요.

JSON을 저장하는 두 방법: JSON 타입과 CLOB

상품마다 속성이 다릅니다. 노트북에는 무게와 색상이, 마우스에는 연결 방식이 있습니다. 속성마다 컬럼을 만들면 상품 종류가 늘 때마다 테이블을 고쳐야 합니다. 그래서 속성을 JSON 한 덩어리로 한 컬럼에 저장합니다. Oracle에서는 이 컬럼을 만드는 방법이 두 가지입니다.

테이블 두 개

-- Oracle 21c 이상의 JSON 타입 컬럼. 저장할 때 JSON 문법을 검사하고 내부 이진 형식으로 보관한다.
CREATE TABLE products (
    id         NUMBER(19)    GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    name       VARCHAR2(100) NOT NULL,
    attributes JSON          NOT NULL
);

-- 12c 이상에서도 쓸 수 있는 방식: CLOB에 IS JSON 제약을 건다. 내용은 문자열 그대로 보관된다.
CREATE TABLE products_clob (
    id         NUMBER(19)    GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    name       VARCHAR2(100) NOT NULL,
    attributes CLOB          NOT NULL,
    CONSTRAINT ck_products_clob_json CHECK (attributes IS JSON)
);

주요 코드 설명

  • attributes JSON: Oracle 21c부터 있는 컬럼 타입입니다. 넣을 때 문법을 검사하고, 내부 이진 형식으로 보관합니다.
  • attributes CLOB + CHECK (attributes IS JSON): 큰 문자열 컬럼에 “이 값이 올바른 JSON이어야 한다”는 제약을 건 방식입니다. 주석처럼 12c부터 쓸 수 있다고 알려져 있으나, 이 Chapter에서는 23ai에서만 실행했습니다.
  • GENERATED BY DEFAULT AS IDENTITY: 번호가 자동 증가하는 식별 컬럼입니다(Chapter 08의 생성 키).

두 방식의 차이를 테스트로 확인

세 가지를 확인했습니다. 상품 데이터는 {"brand":"acme","price":1200,"tags":["new","sale"],"specs":{"color":"red","weightKg":1.5}} 같은 JSON 한 줄입니다.

1. 잘못된 JSON은 둘 다 거절한다

Product broken = new Product("broken", "{not json");

assertThrows(DataAccessException.class, () -> mapper.insert(broken));
assertEquals(3, mapper.count());   // 실패한 행은 들어가지 않았다

JSON 타입은 ORA-40441: JSON syntax error, CLOB은 체크 제약 위반 ORA-02290: check constraint (CURRICULUM.CK_PRODUCTS_CLOB_JSON) violated입니다(sqlplus로 직접 넣어 얻은 메시지). 같은 거절이지만 번호가 달라서 오류를 읽을 때 어느 방식의 컬럼인지 알 수 있습니다.

2. 저장된 모양이 달라진다

String spaced = "{ \"brand\" :  \"acme\" }";
// CLOB: 넣은 그대로 돌아온다
assertEquals(spaced, mapper.findClobById(clob.getId()).getAttributes());
// JSON 타입: 공백이 정리되어 돌아온다
assertEquals("{\"brand\":\"acme\"}", mapper.findById(jsonId).getAttributes());
항목 JSON 타입 CLOB + IS JSON
잘못된 JSON 거절(ORA-40441) 거절(ORA-02290)
저장 형태 내부 이진 형식, 공백 정규화 입력한 문자열 그대로
사용 가능 버전 21c 이상 12c 이상으로 알려짐(이 Chapter에서 확인 못 함)

원문 그대로 보관해야 하면(감사, 서명 등) CLOB이, 질의 위주라면 JSON 타입이 자연스럽습니다. 성능 차이와 인덱스는 이 Chapter에서 확인하지 않았습니다.

읽을 때는 JSON_SERIALIZE

JSON 타입 컬럼을 문자열로 읽을 때는 JSON_SERIALIZE(attributes)로 텍스트로 바꿨습니다. 제거해 보는 실험에서는 11건이 모두 통과해 필수는 아니었지만, “JSON 타입의 값을 텍스트로 바꾼다”는 의도를 드러내려고 남겼습니다. 이 드라이버가 JSON 컬럼을 문자열로 읽어 준 덕분일 수 있고, 다른 환경에서도 같은지는 확인하지 못했습니다.

확인 문제

  1. JSON 타입과 CLOB + IS JSON이 모두 잘못된 JSON을 거절하는데, 오류 번호가 다른 이유는 무엇인가요?
  2. 입력한 JSON 문자열을 그대로 돌려받아야 하는 요구가 있다면 어느 방식을 고르나요?

답: 1) 검사하는 계층이 다르기 때문입니다. JSON 타입은 타입 자체가 문법을 검사하고, CLOB은 체크 제약이 검사합니다. 2) 원문을 그대로 보관하는 CLOB + IS JSON입니다.

직접 해 보기

  1. 두 테이블에 {"a" : 1}을 넣고 읽어 공백이 어떻게 보이는지 비교하세요(Oracle이 있다면).
  2. {not json을 각각 넣고 오류 번호를 확인하세요.
  3. 자신의 서비스에서 “원문 그대로”가 필요한 데이터가 있을지 떠올려 보세요.

JSON 함수 네 가지

JSON을 통째로 저장했다면 그 안의 값으로 검색도 해야 합니다. Oracle은 JSON 안을 SQL에서 직접 들여다보는 함수를 제공합니다. 같은 데이터에 네 가지를 써 보았습니다. MyBatis에는 JSON 질의 기능이 따로 없으므로 이 함수들은 XML에 SQL로 그대로 씁니다.

데이터

{"brand":"acme","price":1200,"tags":["new","sale"],"specs":{"color":"red","weightKg":1.5}}

세 상품이 들어 있습니다: laptop(acme, 1200, 태그 new·sale), phone(zeta, 800, 태그 new), mouse(acme, 30, 태그 없음).

한눈에 보기

함수 용도 예 결과
JSON_VALUE 경로의 스칼라 값 하나 JSON_VALUE(attributes, '$.brand') acme
JSON_QUERY 경로의 객체나 배열을 JSON 텍스트로 JSON_QUERY(attributes, '$.specs') {"color":"red","weightKg":1.5} 형태
JSON_EXISTS 조건에 맞는 값이 있는 행만 JSON_EXISTS(attributes, '$.tags[*]?(@ == $tag)' PASSING #{tag} AS "tag") 태그가 sale인 laptop
JSON_TABLE 배열 원소를 행으로 펼침 JSON_TABLE(p.attributes, '$.tags[*]' COLUMNS (tag VARCHAR2(50) PATH '$')) new, sale

경로의 $는 JSON 전체, $.specs.color는 안쪽 객체의 키, [*]는 배열의 모든 원소입니다.

Mapper XML

<select id="findBrand" resultType="string">
    SELECT JSON_VALUE(attributes, '$.brand') FROM products WHERE id = #{id}
</select>

<select id="findSpecs" resultType="string">
    SELECT JSON_QUERY(attributes, '$.specs') FROM products WHERE id = #{id}
</select>

<select id="findByTag" resultMap="productMap">
    SELECT id, name, JSON_SERIALIZE(attributes) AS attributes
    FROM products
    WHERE JSON_EXISTS(attributes, '$.tags[*]?(@ == $tag)' PASSING #{tag} AS "tag")
    ORDER BY id
</select>

<select id="findTags" resultType="string">
    SELECT jt.tag
    FROM products p,
         JSON_TABLE(p.attributes, '$.tags[*]' COLUMNS (tag VARCHAR2(50) PATH '$')) jt
    WHERE p.id = #{id}
</select>

주요 코드 설명

  • JSON_VALUE는 값 하나를 꺼냅니다. 기본 반환 타입은 문자열이라 resultType="string"으로 받았습니다. 경로에 값이 없으면 오류 없이 NULL입니다.
  • JSON_QUERY는 객체나 배열을 JSON 텍스트 그대로 꺼냅니다. 테스트는 결과에 "color":"red"와 "weightKg":1.5가 들어 있는지만 확인했습니다. 정확한 문자열 형태는 고정해 두지 않았습니다.
  • JSON_EXISTS의 ?(@ == $tag)는 “현재 원소(@)가 변수 $tag와 같다”는 조건입니다. 변수 $tag의 값은 PASSING #{tag} AS "tag"로 넘깁니다. 검색어를 SQL 문자열에 이어 붙이지 않고 바인딩하므로, 입력값이 경로 문법으로 해석되지 않습니다(Chapter 08의 #{}와 같은 원칙).
  • JSON_TABLE은 배열 원소 하나를 행 하나로 펼칩니다. COLUMNS (tag VARCHAR2(50) PATH '$')는 각 원소를 tag 컬럼으로 만든다는 뜻입니다. 태그가 없는 mouse는 행이 0개입니다.

테스트로 고정한 결과

assertEquals("acme", mapper.findBrand(laptopId));
assertEquals(List.of("laptop", "phone"), mapper.findByTag("new").stream().map(Product::getName).toList());
assertEquals(List.of("laptop"), mapper.findByTag("sale").stream().map(Product::getName).toList());
assertEquals(List.of(), mapper.findByTag("none"));
assertEquals(List.of("new", "sale"), mapper.findTags(laptopId));
assertEquals(List.of(), mapper.findTags(mouseId));

따라 하기(Oracle 환경)

examples/ch14-oracle-json은 oracle Profile에서만 동작합니다. Oracle 환경에서 OracleJsonTests를 실행하면 이 절의 결과(laptop, phone 등)가 PASSED로 확인됩니다.

ORACLE_URL=... ORACLE_USERNAME=... ORACLE_PASSWORD=... \
./gradlew :examples:ch14-oracle-json:test

환경 변수가 없으면 이 테스트는 SKIPPED이므로 통과로 보지 않습니다. H2에서는 이 함수들이 없어 같은 SQL이 실행되지 않습니다(아래 “DB별 JSON 지원 비교: H2에서 되는 것과 안 되는 것” 절).

직접 해 보기

  1. '$.specs.color'로 JSON_VALUE를 써서 색상을 꺼내 보세요.
  2. 태그 sale을 PASSING으로 넘기는 대신 SQL에 문자열로 이어 붙이면 왜 위험한지 Chapter 08의 ${} 설명과 연결해 적어 보세요.
  3. JSON_TABLE로 모든 상품의 태그를 한 번에 펼치는 쿼리를 구상해 보세요(특정 상품을 p.id로 거르지 않고 모든 행을 대상으로).

숫자 비교와 API, JSON 함수 오류

JSON 함수는 틀려도 오류 없이 빈 값이나 엉뚱한 결과를 돌려주는 경우가 많습니다. 오류 메시지가 없는 오류가 가장 찾기 어렵습니다. 이 절에서는 숫자 비교의 함정을 보고, API로 결과를 확인한 뒤, 이 예제의 SQL을 한 군데씩 바꿔 얻은 실제 오류를 정리합니다.

숫자를 비교할 때 RETURNING NUMBER를 빼면 사전순이 된다

가격이 500보다 비싼 상품을 찾습니다. JSON_VALUE의 기본 반환 타입은 문자열입니다.

<select id="findPriceOver" resultMap="productMap">
    SELECT id, name, JSON_SERIALIZE(attributes) AS attributes FROM products
    WHERE JSON_VALUE(attributes, '$.price' RETURNING NUMBER) &gt; #{min}
    ORDER BY id
</select>

&gt;는 XML에서 >를 쓰는 표기입니다(Chapter 09). RETURNING NUMBER가 있으면 숫자로 비교합니다. 이를 빼고 문자열로 비교한 쿼리(findPriceOverComparedAsText)를 따로 두고 결과를 비교했습니다.

쿼리 결과
RETURNING NUMBER 있음 laptop(1200), phone(800)
문자열 비교(RETURNING 없음) phone만

"1200"은 사전순으로 "500"보다 앞이라 laptop이 빠졌습니다. 이 결과는 sqlplus에서도 같았습니다(문자열 비교 phone, 숫자 비교 laptop, phone). 테스트가 두 결과를 모두 고정합니다.

초기에는 테스트 주석에 “문자열 비교였다면 mouse가 섞였을 것”이라고 잘못 적었습니다. 실제 동작을 확인하지 않고 쓴 추측이었고, sqlplus로 확인한 뒤 고치고 그 동작을 고정하는 테스트를 추가했습니다. 직관으로 쓴 주석은 틀릴 수 있어서 실행해 확인해야 합니다.

API로 확인

oracle Profile로 실행한 JAR의 응답입니다. 컨트롤러는 attributes를 JSON 텍스트 그대로 응답에 끼웁니다.

GET /products/1
  -> 200 {"id":1,"name":"laptop","attributes":{"brand":"acme","price":1200,"tags":["new","sale"],"specs":{"color":"red","weightKg":1.5}}}

GET /products/1/tags
  -> 200 ["new","sale"]

GET /products?minPrice=500
  -> 200 ["laptop","phone"]

GET /products?tag=sale
  -> 200 ["laptop"]

GET /products/999
  -> 404

@GetMapping, ResponseEntity, 404 처리는 Chapter 04와 같습니다. 이 예제는 문자열을 이어 붙여 응답을 만드는데, 이름에 따옴표 같은 문자가 들어가면 JSON이 깨질 수 있어 학습용 단순화입니다. 객체로 바꿔 쓰는 방법은 아래 “TypeHandler로 JSON 컬럼을 record에 매핑하기” 절에서 다룹니다. 예제를 작성할 때는 기본 Profile 1건(Mapper XML이 문법 오류 없이 로드되는지)과 Oracle 10건이 모두 통과했습니다. 이후 Oracle을 다시 실행하지는 않았고, 환경 변수가 없으면 Oracle 10건은 SKIPPED입니다.

자주 만나는 오류

1. 오류 없이 null이 나온다: 경로 오타

'$.brand'를 '$.brnd'로 틀리게 적었습니다.

jsonValueExtractsScalar()
AssertionFailedError: expected: <acme> but was: <null>

SQL은 성공했고 값만 null입니다. 경로에 값이 없으면 JSON_VALUE는 기본 설정에서 오류 대신 NULL을 돌려줍니다. 값이 비어 있으면 경로 철자부터 의심합니다. 경로는 컴파일러가 검사해 주지 않습니다.

2. ORA-40655: no PASSING clause specified

JSON_EXISTS에서 PASSING #{tag} AS "tag"를 지우면 $tag가 어디서 오는지 알 수 없습니다.

UncategorizedSQLException: ### Error querying database.  Cause: java.sql.SQLException: ORA-40655: no PASSING clause specified

경로 안의 $tag는 이어 붙이기가 아니라 PASSING으로 넘기는 바인딩 변수입니다.

3. 오류가 나지 않은 실험 두 가지

RETURNING NUMBER를 뺀 변경과 JSON_SERIALIZE를 뺀 변경은 11건이 모두 통과했습니다. 앞의 것은 문자열 비교를 보여 주는 별도 쿼리가 이미 기대 동작으로 고정돼 있어서이고, 뒤의 것은 이 드라이버가 JSON 컬럼을 문자열로 읽을 수 있었기 때문으로 보입니다. 통과했다는 사실만 확인했고 다른 환경은 알 수 없습니다.

증상 가장 먼저 볼 것
값이 null JSON 경로 철자, 대소문자
ORA-40655 PASSING 절
숫자 비교 결과가 이상함 RETURNING NUMBER 유무
ORA-40441 / ORA-02290 저장하려는 JSON 문법

숫자 비교의 함정을 값으로 이해하기

문자열은 사전순으로 비교되므로 "1200"과 "500"을 비교하면 첫 글자 1이 5보다 앞에 와서 "1200" < "500"입니다. 숫자로 비교하려면 RETURNING NUMBER로 반환 타입을 지정해야 합니다.

비교 1200 대 500 결과
문자열(사전순) "1200" < "500" 1200이 500보다 작다고 판단
숫자 1200 > 500 1200이 크다고 판단

이 원리는 데이터베이스와 무관한 일반 규칙이고, Oracle에서 확인한 결과는 앞의 “숫자를 비교할 때 RETURNING NUMBER를 빼면 사전순이 된다” 절의 표에 있습니다.

직접 해 보기

  1. minPrice=500으로 두 쿼리 결과가 어떻게 다른지 직접 호출해 보세요(Oracle이 있다면).
  2. minPrice=50으로 바꾸면 문자열 비교 결과는 어떻게 될까요? 예측한 뒤 확인해 보세요. 이 Chapter에서는 500만 확인했습니다.
  3. 경로 오타를 일부러 내고 null이 되는 것을 확인하세요.

DB별 JSON 지원 비교: H2에서 되는 것과 안 되는 것

지금까지 세 절은 Oracle의 JSON 저장 방식과 함수를 다뤘습니다. 그런데 Oracle이 없는 환경에서 공부하는 분도 많고, 회사와 개인 프로젝트에서 쓰는 DB가 다를 수도 있습니다. 이 절은 같은 JSON 질의가 DB마다 얼마나 다른지를 정리하고, 개인 학습 환경에서 어디까지 확인할 수 있는지 분명히 합니다.

확인 범위를 먼저 밝힌다

구분 내용
예제 작성 때 이 저장소의 예제로 MyBatis까지 실행해 검증 H2(ch15), Oracle 23ai(ch14, ch15)
별도로 SQL을 직접 실행해 기록한 것 H2 2.3.232 의 JSON 기능
MyBatis 경유 동작은 검증하지 않음 PostgreSQL 17, MariaDB 11.8 (저장소에 예제 없음)

아래 표 중 PostgreSQL과 MariaDB 열은 이 Chapter의 계획 단계에서 정리한 내용이며, 이 저장소에 해당 DB 예제가 없어 MyBatis로 실행해 확인하지 않았습니다. 사용할 때는 해당 DB 공식 문서로 다시 확인하세요. 또 ch15가 쓰는 H2는 Boot 관리 버전 2.4.240이고 아래 H2 기록은 2.3.232에서 한 것이라, 버전에 따라 달라졌을 수 있습니다.

비교표

DB 저장 잘못된 JSON 거절 값 꺼내기 배열 펼치기
H2 JSON 타입, FORMAT JSON, IS JSON 거절함 JSON_VALUE, JSON_EXISTS, -> 없음. 문자열로 바꿔 LIKE로만 검색 JSON_TABLE 없음
PostgreSQL 17 jsonb 거절함 ->>, jsonb_path_query_first, ?, JSON_VALUE(17부터) jsonb_array_elements_text
MariaDB 11.8 JSON(검사 제약) 거절함 JSON_VALUE, JSON_EXISTS, JSON_QUERY JSON_TABLE
Oracle 23ai JSON 타입 또는 CLOB + IS JSON 거절함(이 Chapter에서 실행) JSON_VALUE, JSON_QUERY, JSON_EXISTS JSON_TABLE

읽는 법은 단순합니다. 저장하고 검증하는 것은 어디서나 되지만, 안쪽 값을 SQL로 꺼내는 문법은 DB마다 다릅니다. 그래서 같은 JSON 질의 SQL은 다른 DB로 그대로 옮길 수 없습니다.

H2에서 학습할 때

H2는 JSON을 저장할 수는 있지만 JSON_VALUE 같은 함수가 없습니다. 그래서 앞의 “JSON 함수 네 가지” 절의 쿼리는 H2에서 돌릴 수 없고, ch14가 oracle Profile 전용인 이유입니다. H2에서 할 수 있는 것은 두 가지입니다.

  1. JSON 문자열을 저장하고 통째로 읽기. 이것이 아래 “TypeHandler로 JSON 컬럼을 record에 매핑하기” 절의 방식입니다.
  2. 앱에서 읽어 자바 객체로 바꾼 뒤 자바 코드로 필터링하기.

H2 JSON 타입에는 함정도 있습니다. 문자열 파라미터를 setString으로 넣으면 JSON 객체가 아니라 JSON 문자열 값으로 저장됩니다(자세히는 아래 “시행착오 1: H2의 JSON 타입” 절). 그래서 ch15는 H2에서 CLOB을 씁니다.

그럼 Oracle 없이 JSON 질의를 연습하려면

PostgreSQL이나 MariaDB 컨테이너로도 JSON 질의를 연습할 수 있습니다. 단, 이 저장소에는 그 예제가 없고 MyBatis로 돌려 확인하지도 않았습니다. 따라 하다 막히면 그 DB의 공식 문서가 기준입니다.

선택 기준

상황 방법
JSON을 저장하고 읽기만 함 TypeHandler + 아무 DB(CLOB/문자열 컬럼 포함)
JSON 안의 값으로 검색·집계 그 DB의 JSON 함수. 이식성은 포기
여러 DB를 지원해야 함 자주 검색하는 값은 별도 컬럼으로 꺼내 저장하고 JSON은 나머지 용도로

세 번째 방법은 이 Chapter에서 코드로 검증하지 않은 설계 제안입니다.

이 비교를 어떻게 활용할까

상황 방법 근거
H2로 JSON 학습 문자열 저장·통째로 읽기, 자바에서 필터링 이 저장소 ch15에서 실행 확인
Oracle로 JSON 질의 JSON_VALUE, JSON_EXISTS, JSON_TABLE 이 저장소 ch14에서 실행 확인(예제 작성 때)
PostgreSQL, MariaDB 해당 DB 공식 문서 이 저장소에서는 실행 확인 없음

“JSON을 지원한다”는 말은 DB마다 다른 것을 뜻합니다. 앞의 비교표에서 본 대로 차이는 안쪽 값을 꺼내는 문법에 있습니다. 이 절의 표는 학습 방향을 잡는 용도이고, 실제 도입은 사용하는 DB의 문서와 직접 실행으로 확인해야 합니다.

자주 하는 오해

오해 사실
모든 DB가 JSON_VALUE를 지원한다 H2에는 없고, DB마다 이름과 문법이 다릅니다
JSON 타입이면 어느 DB에서나 같은 SQL이 된다 타입 이름, 경로 문법, 반환 타입이 다릅니다
H2에서 통과하면 Oracle에서도 통과한다 JSON 함수는 H2에서 실행조차 되지 않습니다

직접 해 보기

  1. 자신이 쓰는 DB의 JSON 지원 문서를 찾아 위 표의 한 행을 직접 채워 보세요.
  2. H2에서 JSON 컬럼에 {"a":1}을 setString으로 넣고 읽어 보세요(아래 “시행착오 1: H2의 JSON 타입” 절의 결과와 비교).
  3. 검색이 잦은 JSON 키 한 개를 골라 “별도 컬럼으로 빼면 무엇이 편해지고 무엇이 불편한가”를 적어 보세요.

TypeHandler로 JSON 컬럼을 record에 매핑하기

앞의 “API로 확인” 절의 컨트롤러는 JSON을 문자열로 이어 붙였습니다. 이제 JSON 구조를 자바 record로 옮기고, MyBatis가 JSON 컬럼과 record 사이를 자동으로 변환하게 하겠습니다. 이를 해 주는 장치가 TypeHandler입니다.

JSON 구조를 그대로 옮긴 record

public record ProductAttributes(String brand, int price, List<String> tags, Specs specs) {

    public record Specs(String color, double weightKg) {
    }
}

JSON의 키 이름과 record 필드 이름이 같습니다. Chapter 01에서 record 필드 이름이 JSON 키가 된다고 했던 것과 같은 규칙으로, Jackson이 둘을 잇습니다.

공통 변환기

public abstract class JsonTypeHandler<T> extends BaseTypeHandler<T> {

    private final JsonMapper mapper;
    private final Class<T> type;

    protected JsonTypeHandler(JsonMapper mapper, Class<T> type) { ... }

    @Override
    public void setNonNullParameter(PreparedStatement ps, int i, T parameter, JdbcType jdbcType) throws SQLException {
        try {
            ps.setString(i, mapper.writeValueAsString(parameter));
        } catch (JacksonException e) {
            throw new IllegalArgumentException("JSON으로 바꿀 수 없습니다: " + type.getSimpleName(), e);
        }
    }

    @Override
    public T getNullableResult(ResultSet rs, String columnName) throws SQLException {
        return parse(rs.getString(columnName));
    }
    // 컬럼 번호/CallableStatement 버전도 같은 parse를 호출한다

    private T parse(String json) {
        if (json == null || json.isBlank()) {
            return null;
        }
        try {
            return mapper.readValue(json, type);
        } catch (JacksonException e) {
            throw new IllegalStateException("컬럼 값을 " + type.getSimpleName() + "로 읽을 수 없습니다: " + json, e);
        }
    }
}

주요 코드 설명

  • BaseTypeHandler<T>: MyBatis가 제공하는 변환기 뼈대입니다. 쓸 때(setNonNullParameter)와 읽을 때(getNullableResult)를 구현합니다.
  • setNonNullParameter: 객체를 JSON 문자열로 바꿔 ps.setString으로 넣습니다. 이름에 NonNull이 있는 것은, 객체가 null이면 BaseTypeHandler가 알아서 SQL NULL을 넣어 주기 때문에 여기서는 null을 신경 쓰지 않아도 되기 때문입니다.
  • getNullableResult 세 개: 컬럼 이름, 컬럼 번호, 저장 프로시저 결과 어느 경로로 읽든 같은 parse를 부릅니다.
  • parse: 값이 null이거나 공백이면 null을 돌려주고, 아니면 JSON을 객체로 읽습니다. 실패하면 JSON 원문을 메시지에 넣은 IllegalStateException을 던집니다. 원문이 있으면 어떤 값이 문제였는지 바로 압니다.
  • JsonMapper와 JacksonException은 tools.jackson 패키지입니다. Boot 4가 쓰는 Jackson 3의 이름으로, Jackson 3의 예외는 모두 런타임 예외라 SQLException으로 바꾸지 않고 메시지만 보강해 던졌습니다.

타입별 구체 클래스와 등록

@Component
@MappedTypes(ProductAttributes.class)
public class ProductAttributesTypeHandler extends JsonTypeHandler<ProductAttributes> {

    public ProductAttributesTypeHandler(JsonMapper mapper) {
        super(mapper, ProductAttributes.class);
    }
}
  • @Component: Chapter 03의 Bean 등록입니다. Bean이 되면 MyBatis 스타터가 TypeHandler로 등록해 줍니다. 이 등록이 빠지면 변환이 안 되는 오류가 납니다(아래 “오류 1: Error setting non null for parameter … with JdbcType null” 절).
  • 생성자 파라미터 JsonMapper: Boot가 구성한 Jackson을 주입받습니다. 웹 계층(요청·응답 변환)과 같은 Jackson 설정을 쓴다는 뜻입니다.
  • @MappedTypes(ProductAttributes.class): 이 핸들러가 어느 자바 타입을 담당하는지 밝힙니다. 이 애노테이션을 지워도 17건이 모두 통과했지만, 의도를 드러내려고 남겼습니다.
  • 타입마다 이 작은 클래스 하나만 만들면 되고, 변환 로직은 공통 부모가 가집니다.

Mapper XML에는 변환 코드가 없다

<insert id="insert" useGeneratedKeys="true" keyProperty="id" keyColumn="id">
    INSERT INTO product_catalog (name, attributes) VALUES (#{name}, #{attributes})
</insert>

<select id="findById" resultType="Product">
    SELECT id, name, attributes FROM product_catalog WHERE id = #{id}
</select>

Product의 attributes 필드가 ProductAttributes 타입이라서 등록된 핸들러가 자동으로 적용됩니다. SQL에는 JSON 변환이 한 줄도 없고, 서비스와 컨트롤러는 JSON 문자열을 만지지 않고 record만 다룹니다.

한 바퀴

예제를 작성할 때는 H2와 Oracle 모두에서 한 바퀴를 확인했고, 이후에는 H2만 다시 확인했으며 Oracle은 실행하지 않았습니다.

POST /products {"name":"laptop","attributes":{"brand":"acme","price":1200,"tags":["new","sale"],"specs":{"color":"red","weightKg":1.5}}}
  -> 201 Location: /products/1 {"id":1,"name":"laptop","attributes":{...}}

GET /products/1
  -> 200 {"id":1,"name":"laptop","attributes":{"brand":"acme","price":1200,"tags":["new","sale"],"specs":{"color":"red","weightKg":1.5}}}

Oracle에 저장된 값을 SQL로 꺼내 보면 record가 평범한 JSON으로 들어 있습니다.

SELECT JSON_SERIALIZE(attributes) FROM product_catalog;
{"brand":"acme","price":1200,"tags":["new","sale"],"specs":{"color":"red","weightKg":1.5}}

그래서 앞의 “JSON 함수 네 가지” 절의 JSON_VALUE 같은 함수로 자바가 쓴 데이터를 곧바로 질의할 수 있습니다. 테스트에서 JSON_VALUE(attributes, '$.brand')가 acme, RETURNING NUMBER로 꺼낸 가격이 1200이었습니다.

따라 하기(H2, Oracle 없이 가능)

./gradlew :examples:ch15-json-typehandler:bootRun
curl -i -X POST http://localhost:8080/products -H "Content-Type: application/json" \
  -d '{"name":"laptop","attributes":{"brand":"acme","price":1200,"tags":["new","sale"],"specs":{"color":"red","weightKg":1.5}}}'
curl http://localhost:8080/products/1

응답의 attributes가 JSON 문자열이 아니라 중첩된 JSON 객체로 나오면 성공입니다. 요청 JSON이 record로, record가 DB 문자열로, 다시 record로, 응답 JSON으로 한 바퀴 도는 과정이 모두 자동입니다.

TypeHandler가 호출되는 시점

쓸 때는 객체 → JSON 문자열, 읽을 때는 JSON 문자열 → 객체로 바뀝니다. SQL XML은 이 변환을 모릅니다.

직접 해 보기

  1. ProductAttributes에 필드를 하나 더하고(예: String model) 저장·조회가 되는지 확인해 보세요. JSON 구조가 바뀌면 record도 함께 바뀌어야 합니다.
  2. 다른 JSON 컬럼용 핸들러를 만들려면 몇 줄이 필요한지 세어 보세요(구체 클래스는 생성자 한 개).
  3. JsonMapper를 주입받는 대신 new로 만들면 웹 계층과 설정이 어떻게 갈라질지 Chapter 03의 DI 관점에서 설명해 보세요.

JSON이 어긋날 때의 변환 규칙

다른 시스템이 쓴 JSON은 record와 구조가 어긋날 수 있습니다. 키가 빠지거나, 모르는 키가 늘거나, 아예 깨져 있을 수도 있습니다. 변환 규칙을 하나씩 테스트로 고정해 두면 나중에 동작이 바뀌었을 때 바로 알 수 있습니다.

규칙표

입력 결과
키 순서와 공백이 다른 JSON 같은 객체로 읽힘
컬럼이 NULL 또는 공백 null
객체가 null 컬럼에 SQL NULL 저장
record에 없는 키가 있음 ("discontinued":true) 무시하고 읽음 (Boot의 JsonMapper)
객체 타입 키(tags, specs)가 없음 그 필드는 null
기본형 키(price)가 없음 읽기 실패
문법이 틀린 JSON 문제의 값을 메시지에 넣은 IllegalStateException

예상과 다르게 동작한 것: 기본형이 빠지면 실패

다섯 번째 줄까지는 예상대로였는데 여섯 번째는 달랐습니다. {"brand":"acme"}처럼 int price가 빠진 JSON을 읽으면 0이 되지 않고 실패합니다.

Cannot map `null` into type `int` (set `DeserializationFeature.FAIL_ON_NULL_FOR_PRIMITIVES` to 'false' to allow)

처음에는 “키 누락은 null 또는 0”이라는 테스트(missingKeysBecomeNullOrZero)를 썼고 그 테스트가 실패했습니다. 실제 동작을 확인하고 테스트를 “객체 타입 키 누락은 null”, “기본형 키 누락은 실패” 두 건으로 나눠 사실을 고정했습니다.

Jackson 3는 기본형에 null을 넣지 못하게 막습니다. Chapter 05의 PUT/PATCH에서 본 int와 Integer의 차이, Chapter 06에서 요청 본문의 int 필드를 빼면 400이 되던 것과 같은 원리입니다. 없을 수 있는 값은 Integer로 선언해야 합니다. 반대로 추가된 키는 무시되어, 다른 시스템이 키를 늘려도 읽기가 깨지지 않습니다.

Spring 없이 변환기를 시험한다

JsonMapper mapper = JsonMapper.builder().build();

변환기는 PreparedStatement, ResultSet 같은 JDBC 객체를 받으므로, 가짜(mock) 객체를 넣어 쓰기가 기대한 JSON 문자열을 만드는지, 읽기가 위 규칙대로 동작하는지 확인합니다. 이런 가짜 객체를 쓰는 방법은 Chapter 19 단위·슬라이스 테스트에서 본격적으로 다룹니다. 주의할 점은, “모르는 키를 무시한다”는 위 규칙을 Boot가 구성한 JsonMapper로만 확인했다는 것입니다. JsonMapper.builder().build()만으로 만든 단독 Mapper에서의 동작은 확인하지 않았습니다.

ch15-json-typehandler의 테스트는 기본 Profile 14건과 Oracle 3건입니다. 기본 Profile 쪽은 통과를 확인했지만, Oracle 3건이 통과했다는 것은 예제를 작성할 때의 기록이며, 이후에는 Oracle 컨테이너를 띄우지 못해 다시 실행하지 않았습니다. Oracle이 없으면 이 3건은 SKIPPED입니다.

테스트 파일 확인하는 것
JsonTypeHandlerUnitTests Spring 없이 쓰기·읽기 규칙
ProductMapperTests H2에서 Mapper 한 바퀴
ProductApiTests POST/GET API
OracleJsonColumnTests Oracle JSON 컬럼 3건(환경 있을 때만)
OS 실행 이 Chapter만 빌드
Linux / macOS ./gradlew :examples:ch15-json-typehandler:bootRun ./gradlew :examples:ch15-json-typehandler:build
Windows gradlew.bat :examples:ch15-json-typehandler:bootRun gradlew.bat :examples:ch15-json-typehandler:build

규칙표를 시험으로 확인

./gradlew :examples:ch15-json-typehandler:test --tests '*JsonTypeHandlerUnitTests*'

Spring 없이 실행되는 단위 테스트가 위 규칙표의 각 줄을 고정합니다. 일부러 규칙을 깨 보세요. 예를 들어 price를 Integer로 바꾸면 “기본형 키가 없으면 실패” 규칙이 “null이 됨”으로 바뀌는지 직접 확인해 볼 수 있습니다(변경 후 되돌리세요).

확인 문제

  1. 기본형 키가 빠졌을 때 0이 되지 않고 실패하는 이유는 무엇인가요?
  2. 이런 규칙을 테스트로 고정해 두는 이유는 무엇인가요?

답: 1) Jackson 3가 기본형에 null을 넣지 못하게 막기 때문입니다. 2) 라이브러리 업그레이드 등으로 동작이 바뀌었을 때 바로 알아채기 위해서입니다.

직접 해 보기

  1. int price를 Integer price로 바꾸고 기본형 누락 테스트가 어떻게 달라져야 할지 예측한 뒤 확인하세요.
  2. {"brand":"acme","unknown":1}을 읽어 보세요. 모르는 키가 무시되는지 관찰합니다.
  3. 규칙표에 “빈 객체 {}” 행을 추가한다면 결과가 무엇일지 적고, 테스트로 확인하세요.

시행착오와 오류: H2 JSON 타입, CI 충돌

이 Chapter의 마지막 절입니다. 직접 부딪힌 시행착오 두 가지와, 일부러 만들어 본 오류들을 정리합니다. 오류는 대개 “연결되지 않았다”와 “변환이 실패했다” 두 갈래입니다.

시행착오 1: H2의 JSON 타입

H2 스키마에서는 attributes를 JSON 타입이 아니라 CLOB으로 만들었습니다.

-- H2는 JSON 타입에 문자열 파라미터를 넣으면 따옴표로 감싼 JSON 문자열로 저장하는 함정이 있어 CLOB을 쓴다.
CREATE TABLE product_catalog (
    id         BIGINT GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY,
    name       VARCHAR(100) NOT NULL,
    attributes CLOB
);

H2의 JSON 컬럼에 setString으로 {"a":1}을 넣고 읽었더니 "{\"a\":1}", 즉 따옴표로 감싸고 이스케이프한 문자열이 돌아왔습니다. TypeHandler가 문자열로 쓰고 읽는 구조와 맞지 않아 H2에서는 CLOB을 썼습니다. 이는 H2 2.4.240 단독 실행으로 확인한 것입니다. Oracle의 JSON 타입은 앞의 “JSON을 저장하는 두 방법: JSON 타입과 CLOB” 절에서 본 대로 문자열을 JSON으로 받아들였습니다.

시행착오 2: CI에서 난 충돌

Oracle 테스트를 Gradle이 여러 모듈 병렬로 실행하는데, 처음에는 ch14와 ch15가 같은 products 테이블을 썼습니다. 한쪽이 DROP하고 CREATE하는 사이 다른 쪽이 접근해서 6건이 실패했습니다.

ORA-00955: name is already used by an existing object
ORA-00942: table or view "CURRICULUM"."PRODUCTS" does not exist

로컬에서는 모듈을 하나씩 돌려서 드러나지 않았던 문제입니다. ch15의 테이블을 product_catalog로 바꿔 이름을 겹치지 않게 하고, CI의 Oracle 잡에는 --no-parallel도 붙였습니다. 이후 CI의 oracle 잡에서 Oracle 테스트 38건(여러 Chapter 합계)이 모두 통과하고 실패는 0건이었습니다. 혼자서 돌릴 때 안 보이는 문제가 공유 자원(같은 DB, 같은 테이블)에서 나온다는 교훈입니다.

오류 1: Error setting non null for parameter … with JdbcType null

TypeHandler 클래스의 @Component를 지우면 핸들러가 등록되지 않아 MyBatis가 ProductAttributes를 어떻게 DB에 넣을지 모릅니다. 17건 중 6건이 실패했습니다.

TypeException: Could not set parameters for mapping: ParameterMapping{property='attributes', mode=IN, javaType=class java.lang.Object, jdbcType=null, ...}.
Cause: TypeException: Error setting non null for parameter #2 with JdbcType null . Try setting a different JdbcType for this parameter or a different configuration property.

메시지는 “다른 JdbcType을 써 보라”고 하지만 실제 원인은 JdbcType이 아니라 핸들러가 등록되지 않은 것입니다. 단서는 DB별로 다른 아래쪽 원인입니다.

Oracle: java.sql.SQLException: ORA-17004: Invalid column type
H2:     JdbcSQLDataException: Serialization failed, cause: "java.io.NotSerializableException: com.jqdom.curriculum.ch15.ProductAttributes"

H2는 객체 자체를 직렬화하려다 실패했고, Oracle은 타입을 알 수 없다고 했습니다. 객체를 그대로 DB에 넣으려는 시도가 보이면 핸들러 등록(@Component, 스캔 범위)을 확인합니다. Oracle 쪽 메시지는 앞의 “null을 넣을 때만 ORA-17004” 절과 같은 ORA-17004지만 원인은 다릅니다. 같은 번호라도 앞뒤 맥락으로 구분해야 합니다. 읽기 쪽에서는 NPE가 났습니다.

오류 2: 컬럼 값을 ProductAttributes로 읽을 수 없습니다

변환기가 실제로 JSON을 파싱하다 실패하면 정해 둔 메시지가 나옵니다. 저장 값을 깨진 JSON({broken)으로 바꿔 보았습니다.

ResultMapException: Error attempting to get column 'ATTRIBUTES' from result set.
Cause: java.lang.IllegalStateException: 컬럼 값을 ProductAttributes로 읽을 수 없습니다: {broken

Oracle의 JSON 컬럼에는 저장 단계부터 막혔습니다.

SQLException: ORA-40441: JSON syntax error

JSON 타입 컬럼은 넣는 순간 거절하고, 문자열 컬럼은 읽을 때 변환기에서 실패합니다. 메시지에 JSON 원문이 있어 원인을 찾기 쉽습니다.

오류가 나지 않은 실험

@MappedTypes(ProductAttributes.class)를 지워도 17건이 모두 통과했습니다. 그래도 명시가 의도를 드러냅니다. 필드 이름을 바꾸는 실험(brand -> brandName)은 테스트 코드가 컴파일되지 않아 JSON 매핑까지 가지 못했습니다. 컴파일러가 먼저 알려 주는 것이 record의 장점입니다.

증상 가장 먼저 볼 것
Error setting non null for parameter 핸들러 @Component, 스캔 범위
ORA-17004 / NotSerializableException 객체를 그대로 넘기고 있는지
컬럼 값을 ...로 읽을 수 없습니다 컬럼의 JSON 원문
ORA-40441 저장하려는 JSON 문법

지금의 한계

Windows 실행은 검증하지 못했습니다. Oracle은 23ai Free 컨테이너에서만 실행했고, 19c 같은 이전 버전은 확인하지 않았습니다. Jackson 3 단독 기본 설정에서 모르는 키를 어떻게 다루는지도 확인하지 않았습니다. JSON 인덱스와 실행 계획도 다루지 않았습니다.

시행착오에서 얻은 원칙

겪은 일 원칙
H2 JSON 컬럼에 setString으로 넣었더니 따옴표로 감싼 문자열이 돌아옴 DB 타입이 편해 보여도 쓰고 읽은 값을 직접 비교해 확인
ch14와 ch15가 같은 products 테이블을 써서 병렬 실행 때 6건 실패 혼자 돌릴 때 안 보이는 문제는 공유 자원에서 나옴
메시지는 JdbcType을 말하지만 실제 원인은 핸들러 미등록 메시지 아래쪽의 DB별 원인(ORA-17004, NotSerializableException)을 확인

직접 해 보기

  1. TypeHandler의 @Component를 잠시 지우고 어떤 메시지가 나오는지 H2에서 확인한 뒤 되돌리세요.
  2. 병렬 테스트가 같은 DB 자원을 건드릴 때 어떤 일이 생기는지, 자신의 프로젝트에서 위험한 곳을 찾아보세요.
  3. 오류 표에서 다음 Chapter에서도 쓸 수 있는 진단 습관을 한 줄로 적어 보세요.

자주 하는 실수와 점검 순서

Chapter 전체에서 만날 수 있는 실수를 증상이 드러나는 시점 순서로 모았습니다. 서버나 컨테이너가 뜨지 않으면 “기동” 행부터, 오류 없이 값만 이상하면 “실행 결과” 행부터 봅니다. ORA 번호별 원인은 앞의 “Oracle 연결 오류 읽기” 절의 “증상별 점검표”에 있습니다.

시점 증상 원인 해결
빌드 Boot 4의 JsonMapper와 맞지 않아 컴파일·동작 문제 Jackson 2 패키지(com.fasterxml)로 가져옴 Jackson 3(tools.jackson) 사용
기동 ${ORACLE_URL}을 해석하지 못해 기동 실패 환경 변수를 정하지 않고 oracle Profile 실행 환경 변수 세 개를 모두 지정
기동 다른 Profile에서 드라이버를 찾지 못함 드라이버를 하나만 의존성에 둠 runtimeOnly로 둘 다 추가
기동 ${ORACLE_SYS_PASSWORD:?...} 메시지와 함께 시작 거부 환경 변수 없이 docker compose up 비밀번호 환경 변수 지정
기동 접속 오류 컨테이너가 준비되기 전에 앱 실행 healthy 확인 후 실행
기동 포트 바인딩 오류 localhost:1521이 이미 사용 중 기존 프로세스 정리 또는 포트 변경
기동 ORA-00955 두 번째 기동에서 CREATE TABLE이 다시 실행됨 자동 실행을 끄고 스크립트는 별도로 관리
실행 결과 설정이 비어 있어 Oracle에서만 ORA-17004 jdbc-type-for-null: NULL(따옴표 없음) "NULL"
실행 결과 H2에서는 통과, Oracle에서는 null 비교 실패 빈 문자열과 null을 다르게 취급하는 코드 한 가지로 통일
실행 결과 공백이 정리되어 equals 비교 실패 JSON 타입 컬럼에 입력한 문자열과 읽은 문자열이 같다고 가정 비교는 문자열이 아니라 파싱한 객체로
실행 결과 타입 이름과 문법이 달라 실패 이 Chapter의 SQL을 다른 DB에 그대로 사용 DB별 문서 확인
실행 결과 NULL이 나올 수 있음 JSON_VALUE로 객체를 꺼내려 함 객체·배열은 JSON_QUERY
실행 결과 값이 NULL 경로의 대소문자 불일치 JSON 키의 대소문자까지 일치
실행 결과 긴 값이 잘리거나 오류 JSON_TABLE의 COLUMNS 길이를 짧게 지정 예상 길이에 맞게 지정
실행 결과 사전순 비교로 일부 행이 빠짐 숫자 비교에 RETURNING NUMBER를 빠뜨림 반환 타입 명시
실행 결과 값에 따옴표가 있으면 JSON이 깨짐 응답을 문자열 이어 붙여 만들기 JSON 라이브러리로 직렬화
실행 결과 Error setting non null for parameter ... with JdbcType null TypeHandler에 @Component를 빠뜨림 Bean으로 등록
실행 결과 읽기 실패 기본형 필드가 JSON에서 빠질 수 있는데 int로 선언 빠질 수 있으면 Integer
실행 결과 필드 추가 시 변환 실패 외부 시스템 JSON이 항상 같은 구조라고 가정 모르는 키는 무시하는지 규칙 확인
테스트 실제로는 실행되지 않은 경로 SKIPPED를 통과로 보고 “검증 완료”라고 보고 건너뛴 테스트 건수를 함께 보고
테스트 의도와 다르게 조건이 항상 참 또는 거짓 matches = ".+" 대신 matches = "" 한 글자 이상을 뜻하는 .+ 사용
테스트 태그별 실행이 불가능 @Tag("oracle") 없이 CI 잡을 나누려 함 태그를 붙이고 Gradle에서 태그로 필터
테스트 규칙 변경을 놓침 변환기를 통합 테스트로만 검증 규칙별 단위 테스트
설계·운영 저장소에 비밀 값이 남음 비밀번호를 application-oracle.yml에 직접 적음 환경 변수로만 주입(설정 우선순위)
설계·운영 타입 이름 차이로 SQL이 복잡해짐 같은 SQL 파일 하나로 두 DB를 지원하려 함 DB별 스크립트 분리
설계·운영 비밀 값 노출 비밀번호를 셸 기록에 남김 환경 변수를 파일에서 읽는 방식 사용(이 Chapter에서는 다루지 않음)
설계·운영 다른 경로로 들어온 데이터가 오염 잘못된 JSON 거절을 애플리케이션 검증으로만 처리 DB 제약(JSON 타입, IS JSON)도 함께 사용
설계·운영 SQL 주입 위험 검색어를 SQL 문자열에 이어 붙임 PASSING #{tag} AS "tag"로 바인딩
설계·운영 원인 파악이 어려움 변환 실패 시 원문 없이 예외 메시지에 JSON 원문 포함
설계·운영 중복과 불일치 타입마다 변환 로직을 복사 공통 부모에 두고 구체 클래스는 얇게

용어와 참고 자료

이 절은 이 Chapter에 나온 용어와 참고한 사이트를 모았습니다. 앞 Chapter에서 이미 설명한 용어(Profile, #{}, ResponseEntity 등)는 Chapter 02와 Chapter 08의 용어 정리를 참고하세요.

참고한 자료

Oracle과 연결

용어 설명
ojdbc Oracle의 JDBC 드라이버입니다. ojdbc11은 Java 11 이상용입니다.
DUAL Oracle에서 FROM이 필요한 SELECT를 위한 한 행짜리 가상 테이블입니다.
서비스 이름 JDBC URL 끝에 적는 접속 대상 이름입니다. 이 컨테이너의 기본은 FREEPDB1입니다.
ORA- 번호 Oracle 오류 번호입니다. Caused by에서 원인을 구분하는 열쇠입니다.
jdbc-type-for-null 값이 null일 때 드라이버에 알려 줄 JDBC 타입을 정하는 MyBatis 설정입니다.
식별 컬럼 GENERATED ... AS IDENTITY로 값이 자동 증가하는 컬럼입니다.
@EnabledIfEnvironmentVariable 지정한 환경 변수가 있을 때만 테스트를 실행하는 JUnit 조건입니다.
SKIPPED 조건이 맞지 않아 실행하지 않은 테스트 상태입니다. 통과가 아닙니다.

JSON

용어 설명
JSON 타입 Oracle 21c 이상의 컬럼 타입입니다. 문법을 검사하고 내부 이진 형식으로 저장합니다.
IS JSON 값이 올바른 JSON인지 검사하는 조건입니다. CLOB 컬럼의 CHECK 제약에 씁니다.
JSON_VALUE JSON에서 스칼라 값 하나를 꺼냅니다. 기본 반환 타입은 문자열입니다.
JSON_QUERY JSON에서 객체나 배열을 JSON 텍스트로 꺼냅니다.
JSON_EXISTS JSON 안에 조건에 맞는 값이 있는지 검사합니다.
JSON_TABLE JSON 배열을 관계형 행과 열로 펼칩니다.
JSON_SERIALIZE JSON 타입 값을 텍스트로 바꿉니다.
RETURNING NUMBER JSON_VALUE의 결과를 숫자로 받는 절입니다. 숫자 비교에 필요합니다.
PASSING JSON 경로의 변수($tag)에 바인딩 값을 넘기는 절입니다.
JSON 경로 $.brand, $.tags[*]처럼 JSON 안의 위치를 가리키는 식입니다.

변환

용어 설명
TypeHandler MyBatis에서 자바 타입과 JDBC 값 사이를 변환하는 장치입니다.
BaseTypeHandler TypeHandler의 뼈대 클래스입니다. null 처리를 대신해 줍니다.
@MappedTypes TypeHandler가 담당하는 자바 타입을 밝히는 애노테이션입니다.
Jackson 3 (tools.jackson) Boot 4가 쓰는 JSON 라이브러리입니다. 예외가 모두 런타임 예외입니다.
FAIL_ON_NULL_FOR_PRIMITIVES 기본형에 null이 들어가면 실패하게 하는 Jackson 설정입니다. 기본값은 켜짐입니다.

이 Chapter의 코드

대상 링크
Oracle 연결 ch13-oracle-connection/
Oracle JSON ch14-oracle-json/
JSON TypeHandler ch15-json-typehandler/

예제 코드 파일

본문에서 다룬 파일은 예제 저장소의 다음 위치에 있습니다.

대상 링크
기본 설정 application.yml
oracle Profile 설정 application-oracle.yml
Oracle 스키마 schema-oracle.sql
컨테이너 설정 compose.yml
Oracle 테스트 OracleConnectionTests.java
H2 테스트 H2ProfileTests.java
Oracle 스키마 schema-oracle.sql
Oracle JSON 테스트 OracleJsonTests.java
Mapper XML ProductMapper.xml
Mapper 인터페이스 ProductMapper.java
컨트롤러 ProductController.java
H2에서 CLOB을 쓰는 스키마 schema-h2.sql
공통 변환기 JsonTypeHandler.java
타입별 변환기 ProductAttributesTypeHandler.java
record ProductAttributes.java
Mapper XML ProductMapper.xml
단위 테스트 JsonTypeHandlerUnitTests.java
Mapper 테스트 ProductMapperTests.java
Oracle 테스트 OracleJsonColumnTests.java

직접 해보기

  1. Profile 없이 ./gradlew :examples:ch13-oracle-connection:bootRun으로 띄우고 curl http://localhost:8080/db/info의 product가 H2, activeProfiles가 []인지 확인하세요.
  2. Oracle 환경 변수 없이 ./gradlew :examples:ch13-oracle-connection:test를 실행해 H2 테스트는 PASSED, Oracle 테스트는 SKIPPED로 나오는지 보고, 이 결과를 Oracle 검증으로 볼 수 없는 이유를 한 문장으로 적어 보세요.
  3. Docker가 있다면 ORACLE_SYS_PASSWORD='<정한 값>' ORACLE_APP_PASSWORD='<정한 값>' docker compose up -d로 컨테이너를 띄우고 환경 변수 세 개를 정해 oracle Profile로 실행한 뒤 /db/info의 product가 Oracle인지 확인하세요. 비밀번호를 일부러 틀려 ORA-01017도 확인합니다.
  4. ./gradlew :examples:ch15-json-typehandler:bootRun으로 띄우고 본문의 curl -i -X POST http://localhost:8080/products ... 요청을 보낸 뒤 curl http://localhost:8080/products/1의 attributes가 중첩된 JSON 객체로 나오는지 확인하세요.
  5. ./gradlew :examples:ch15-json-typehandler:test --tests '*JsonTypeHandlerUnitTests*'를 실행한 뒤 ProductAttributes의 int price를 Integer price로 바꾸면 “기본형 키가 없으면 실패” 규칙이 어떻게 달라지는지 확인하고 되돌리세요.

이번 장의 정리

이 Chapter에서는 H2에서 Oracle로 연결을 넓히고, 컬럼 하나에 담은 JSON을 질의하고 자바 record로 변환했습니다.

  • 기본은 H2, oracle Profile일 때만 Oracle에 붙도록 설정을 나누고, 접속 정보는 환경 변수로만 넘깁니다. 스키마 스크립트도 DB별로 나눕니다.
  • Oracle 전용 테스트는 @EnabledIfEnvironmentVariable로 환경이 있을 때만 실행합니다. SKIPPED는 검증이 아닙니다.
  • Oracle에서는 null 바인딩에 jdbc-type-for-null: "NULL"(따옴표 필수)이 필요하고, 빈 문자열이 NULL로 저장되며, 접속 오류는 Caused by의 ORA 번호로 원인을 좁힙니다.
  • JSON은 JSON 타입 또는 CLOB + IS JSON으로 저장하고, JSON_VALUE, JSON_QUERY, JSON_EXISTS, JSON_TABLE로 꺼냅니다. 숫자 비교에는 RETURNING NUMBER, 검색어에는 PASSING 바인딩이 필요합니다.
  • JSON 질의 문법은 DB마다 달라 그대로 옮길 수 없고, H2에는 이 함수들이 없습니다.
  • TypeHandler를 Bean으로 등록하면 Mapper XML에 변환 코드 없이 JSON 컬럼과 record가 오갑니다. 기본형 키가 빠지면 읽기가 실패하므로 없을 수 있는 값은 Integer 같은 객체 타입으로 선언합니다.
  • Oracle 쪽 결과는 예제를 작성할 때 23ai Free 컨테이너에서 실행한 기록이고, PostgreSQL과 MariaDB는 문서 수준으로만 비교했습니다. 결과를 말할 때는 어디서 실제로 실행했는지를 함께 밝힙니다.

다음 Chapter 12 MapStruct와 OpenAPI 계약에서는 DTO와 Domain 사이의 변환 코드를 줄이는 MapStruct와 API 명세를 다룹니다.

FAQ

자주 묻는 질문

로컬에 Oracle이 없으면 이 Chapter를 학습할 수 없나요?

Profile 분리와 TypeHandler 실습은 기본 H2 환경에서 진행할 수 있습니다. Oracle 전용 함수 테스트는 환경이 없으면 SKIPPED되며 통과로 해석하면 안 됩니다.

Oracle 접속 비밀번호를 설정 파일에 적어도 되나요?

저장소에 비밀이 남으므로 환경 변수로 주입합니다. 예제의 application-oracle.yml도 변수 참조만 둡니다.

JSON 숫자를 문자열로 비교하면 어떤 문제가 생기나요?

사전순으로 비교되어 100이 20보다 작다고 판단될 수 있습니다. JSON_VALUE에 RETURNING NUMBER를 지정해 숫자로 비교합니다.

TypeHandler는 어디에서 등록하나요?

예제는 구체 TypeHandler를 스프링 Bean으로 등록해 MyBatis가 찾게 합니다. 등록이 빠지면 객체를 JDBC 값으로 바꾸지 못합니다.

작성·편집 ToolPado

콘텐츠 유형 Spring Boot 학습 가이드

기술 기준 Spring Boot 4.1.1 · JDK 21

마지막 검토