스프링 부트 ORA-17059 에러 완벽 해결!

스프링부트 ORA-17059 에러 해결방법

 

필자는 스프링부트를 이용하여 풀캘린더를 적용하고 있었습니다. 그러던 중, 오라클 데이터베이스 내 'Schedule'테이블의 저장된 일정 목록 데이터를 조회해서 가져오던 중에 500 에러가 발생하였습니다. 에러 메시지는 'ORA-17059' 에러였습니다. 정확하게는 'ORA-17059: 내부 형식으로의 변환을 실패했습니다.' 라는 메시지였습니다. 데이터를 받아오는 과정에서 에러가 발생했기 때문에, 가장 확실하게 의심 가는 부분은 '테이블 내 조회된 데이터를 바인딩하는데 에러가 발생했구나.'였고, 역시나 쿼리가 작성된 mapper.xml의 'resultType' 속성에 명시된 클래스 타입으로 조회된 데이터를 바인딩하는 과정에서 발생한 에러였습니다. 구체적으로 설명하자면 조회된 데이터는 테이블의 컬럼 타입이 'VARCHAR'인데 VO의 클래스 필드 타입이 int로 구성되어 있어서 데이터가 바인딩되는 과정에서 발생했습니다.

 

ORA-17059: 내부 형식으로의 변환을 실패했습니다.

 

에러가 발생한 필자의 상황

위에서 상황 설명했듯이 조회를 해서 가져오려고 작성했던 쿼리는 아래와 같습니다. 일반적인 테이블을 이용해 조회하고자 하는 컬럼을 SELECT 구문에 작성 후 조회하였습니다.

 

조회하려는 테이블의 각 컬럼별 정보는 아래 이미지와 같습니다. 'SCH_NO'부터 'SCH_ALLDAY' 컬럼까지 각 컬럼마다의 타입이 크기와 함께 다르게 설정되어 있습니다. 이 중, 'SCH_NO'를 제외하고는 모두 'VARCHAR2' 타입으로 문자열을 담을 수 있는 타입이 설정되어 있습니다.

 

 

테이블의 정보는 'SCH_NO'를 제외하고 나머지 컬럼의 타입이 'VARCHAR'인데 데이터를 받을 VO 클래스 내 id의 필드가 문자열을 받기 위한 타입인 String이 아니라 int로 설정되어 있습니다. 그렇기 때문에 데이터를 받기 위한 타입이 일치하지 않아서 'ORA-17059' 에러가 발생하였습니다.

 

 

이렇듯, 'ORA-17059'와 관련된 에러는 필자가 진행중에 발생했던 에러 이외에 현상에서도 발생할 수 있습니다. 해당 에러가 발생하는 여러 원인과 해결방법에 대해서 알아보겠습니다.

 

 

 

 

 

'ORA-17059' 주요 발생 상황 및 해결 방법

 

1. 데이터 타입 불일치

 

발생 상황

가장 흔한 원인 중 하나로 데이터베이스 컬럼의 데이터 타입과 애플리케이션에서 해당 데이터를 받으려고 하는 Java 타입이 호환되지 않는 경우 발생합니다. 예를 들어, 데이터베이스의 NUMBER 타입 컬럼 값을 애플리케이션에서 String으로 받으려고 하거나, DATE 타입 컬럼 값을 INTEGER로 받으려고 할 때 발생할 수 있습니다. 

 

해결 방법

• 데이터베이스 스키마 확인
  먼저해당 컬럼의 타입을 정확히 확인해야 합니다. SQL Developer나 DBeaver 같은 툴을 사용하거나, 'DESCRIBE 테이블명;'과 같은 SQL 구문을 실행해서 컬럼 정보를 확인합니다.
• Java 코드 수정
  데이터베이스 컬럼 타입에 맞춰 Java 변수의 타입을 변경해야 합니다. 예를 들어, NUMBER 타입은 int, long, BigDecimal 등으로, VARCHAR2 타입은 String으로, DATE 또는 TIMESTAMP 타입은 Date, TimeStamp 등으로 매핑해야 합니다.
• ResultSet의 getXXX() 메서드 확인
  ResultSet에서 데이터를 가져올 때 사용하는 getInt(), getString(), getDate() 등의 메서드가 컬럼 타입과 일치하는지 확인합니다. 예를 들어, NUMBER 타입 컬럼의 값을 가져올 때는 getInt()나 getLong()을 사용해야 합니다.
• 명시적인 타입 변환
  필요한 경우, Java 코드 내에서 명시적인 타입 변환을 수행할 수 있습니다. 예를 들어, BigDecimal 값을 String으로 반환해야 한다면 bigDecimalValue.toString() 메서드를 사용해야 합니다.

 

 

2. 데이터 형식 불일치

 

발생 상황

데이터베이스 컬럼의 데이터 타입은 맞지만, 저장된 데이터의 형식이 애플리케이션에서 기대하는 형식과 다를 때 발생할 수 있습니다. 특히 날짜(DATE, TIMESTAMP) 타입의 경우, 데이터베이스에 저장된 형식과 JDBC 드라이버의 기본 형식 또는 애플리케이션에서 지정한 형식이 다르면 변환에 실패할 수 있습니다. 

 

해결 방법

• 날짜 형식 확인
  데이터베이스에 저장된 날짜 형식을 확인합니다. TO_CHAR 함수를 사용하여 특정 형식으로 조회해 보면 알 수 있습니다. (SELECT TO_CHAR(date_column, 'YYYY-MM-DD HH24:MI:SS') FROM TABLENAME; SQL 구문으로 조회)
• JDBC URL 파라미터 설정
  JDBC 연결 URL에 날짜 형식 관련 파라미터를 추가하여 JDBC 드라이버가 특정 형식으로 날짜 데이터를 처리하도록 지정할 수 있습니다.
  (jdbc:oracle:thin:@localhost:1521:XE?oracle.jdbc.formatMapping=true&oracle.jdbc.timestampTZinGmt=false 와 같은 파라미터를 설정해 볼 수 있습니다.)
• SimpleDateFormat 사용
  Java 코드에서 SimpleDateFormat 클래스를 사용하여 데이터베이스에서 가져온 날짜 데이터를 원하는 형식으로 파싱하거나, 애플리케이션의 날짜 데이터를 데이터베이스에 저장할 형식으로 포맷팅 할 수 있습니다.

 

 

3. NLS 설정 문제

 

발생 상황

오라클 데이터베이스의 NLS(National Language Support) 설정이 애플리케이션의 로케일 설정과 충돌하는 경우에도 데이터 변환 오류가 발생할 수 있습니다. 특히 숫자나 날자 형식에 영향을 미칠 수 있습니다. 마치 한국식 날자 표기 방식과 미국식 날짜 표기 방식을 혼용해서 사용하는 것과 같은 혼란이 발생할 수 있습니다.

 

** NLS란?
'National Language Support'의 약자로, 오라클 데이터베이스에서 다국어 환경을 지원하는 기능을 의미합니다. NLS 파라미터는 데이터베이스, 인스턴스, 세션 레벨에서 설정하여 언어, 지역, 문자 집합과 관련된 동작 방식을 제어합니다.

 

해결 방법

• 데이터베이스 NLS 설정 확인
  데이터베이스의 NLS 설정을 확인합니다. 'SELECT * FROM NLS_DATABASE_PARAMETERS;' SQL 구문을 실행하여 확인할 수 있습니다. 특히 NLS_DATE_FORMAT, NLS_TIMESTAMP_FORMAT, NLS_NUMERIC_CHARACTERS 등의 파라미터를 확인합니다.
• 세션 NLS 설정 변경
  필요한 경우, 특정 세션에 대해서만 NLS 설정을 변경할 수 있습니다.
  예를 들어 'ALTER' SESSION SET NLS_DATE_FORMAT = 'YYYY-MM-DD HH24:MI:SS;'와 같이 SQL 구문을 실행할 수 있습니다.
• JDBC URL 파라미터 설정
  JDBC 연결 URL에 NLS 관련 파라미터를 추가하여 JDBC 드라이버의 동작 방식을 제어 할 수 있습니다.

 

 

4. BLOB / CLOB 데이터 처리 오류

 

발생 상황

BLOB (Binary Large Object) 또는 CLOB (Character Large Object) 타입의 데이터를 처리하는 과정에서 인코딩 쿤제나 데이터 길이 문제 등으로 변환에 실패할 수 있습니다.

 

해결 방법

• 인코딩 확인
  CLOB 데이터를 처리할 때는 데이터베이스와 애플리케이션의 문자 인코딩이 일치하는지 확인해야 합니다. 일반적으로 UTF-8 인코딩을 사용하는 것이 좋습니다.
• 스트리밍 방식 처리
  BLOB 또는 매우 큰 CLOB 데이터는 한 번에 메모리에 로드하지 않고 스트리밍 방식으로 처리하는 것이 좋습니다. JDBC에서 제공하는 BLOB 및 CLOB 인터페이스의 메서드를 활용합니다.
• 데이터 길이 확인
  삽입하거나 조회하려는 데이터의 길이가 컬럼의 최대 길이를 초과하지 않는지 확인합니다.

 

 

5. JDBC 드라이버 버전 문제

 

발생 상황

사용하고 있는 JDBC 드라이버 버전이 오라클 데이터베이스 서버 버전과 호환되지 않거나, 특정 버전에서 알려진 버그로 인해 데이터 변환 오류가 발생할 수 있습니다. 

 

해결 방법

• JDBC 드라이버 버전 확인
  사용하고 있는 JDBC 드라이버의 버전을 확인합니다. Maven 또는 Gradle과 같은 빌드 도구를 사용하는 경우, 해당 의존성 정보를 확인합니다.
• 드라이버 버전 업그레이드 또는 다운그레이드
  오라클 데이터베이스 서버 버전에 맞는 최신 JDBC 드라이버로 업그레이드하거나, 안정적인 이전 버전으로 다운그레이드를 해봅니다. 오라클 공식 문서를 참고하여 호환되는 드라이버 버전을 확인하는 것이 중요합니다.

 

 

 

ORA-17059 에러는 다양한 원인으로 발생할 수 있지만, 대부분 데이터 타입이나 형식 불일치와 관련된 문제입니다. 위에 제시된 해결 방법들을 차근차근 확인해 보면 문제 해결에 도움이 될 것입니다.

 

 

 

 

 

@Junesker

---