[Oracle JDBC 에러] 지원되지 않는 문자 집합 KO16MSWIN949 해결 과정

ORA-17056: KO16MSWIN949 문자 집합 오류 해결 과정

자바 버전 1.5 인 프로젝트를 자바 버전 1.8로 올리던 도중 톰캣 로컬 서버는 띄워지지만 DB 요청시에 Exception이 발생하는것을 확인하였습니다. 

Error attempting to get column 'MCOD' from result set.  
Cause: java.sql.SQLException: ORA-17056: 지원되지 않는 문자 집합(클래스 경로에 orai18n.jar 추가): KO16MSWIN949

이 에러는 JDBC 드라이버가 데이터베이스에서 사용하는 문자 집합을 지원하지 않아 발생합니다. 해당 문제를 해결하기 위해 제가 겪었던 과정과 해결책을 공유합니다.

반응형

---

1. 문제 상황

에러가 발생한 환경은 다음과 같았습니다:

• 개발 환경: Spring Framework 기반 웹 애플리케이션
• 톰캣 버전: 8.5
• JDK 버전: Java 8
• JDBC 드라이버: ojdbc8.jar
• 문자 인코딩: x-windows-949 (KO16MSWIN949)

특정 SQL 쿼리를 실행하는 과정에서 KO16MSWIN949 문자 집합이 지원되지 않는다는 에러가 발생했다는 점에서 힌트를 보았고. 프로젝트는 오래된 x-windows-949 인코딩을 사용하고 있었으며, 이는 호환성 문제로 이어졌던 것입니다.

반응형

---

2. 에러의 원인

이 에러는 Oracle 데이터베이스가 사용하는 문자 집합 x-windows-949 이 JDBC 드라이버에서 지원되지 않을 때 발생합니다. 에러 메시지에서 제안한 대로, 이 문제를 해결하려면 orai18n.jar 파일을 추가해야 합니다. orai18n.jar는 Oracle에서 제공하는 국제화(i18n)를 지원하는 라이브러리로, 추가적인 문자 집합을 처리할 수 있도록 도와줍니다.

반응형

---

3. 해결 과정

3.1. orai18n.jar 다운로드

1. Oracle 공식 웹사이트에서 orai18n.jar를 다운로드합니다.
   • Oracle JDBC Downloads 페이지를 방문합니다.
   • 사용 중인 JDBC 드라이버 버전에 맞는 ojdbc8-full.tar.gz 파일을 다운로드합니다. 압축을 해제하면 orai18n.jar 파일을 포함한 여러 라이브러리를 확인할 수 있습니다. 

3.2. 프로젝트에 orai18n.jar 추가

다운로드한 orai18n.jar 파일을 프로젝트의 클래스패스에 포함시킵니다.

• 클래스패스 직접 설정: WEB-INF/lib 디렉터리에 orai18n.jar를 복사한 후, 빌드 경로에 포함합니다.

3.3. JDBC URL 설정

jdbc:oracle:thin:@//host:port/service?useUnicode=true&characterEncoding=MS949

3.4. 서버 재배포

1. 변경 사항을 적용하기 위해 서버를 다시 빌드하고 재시작합니다.
2. 애플리케이션이 orai18n.jar 파일을 로드하여 추가 문자 집합을 처리할 수 있도록 합니다.

반응형

---

4. 결과

위 과정을 거친 후, 동일한 SQL 쿼리를 실행했을 때 더 이상 ORA-17056 오류가 발생하지 않았습니다. 애플리케이션에서 정상적으로 데이터가 출력되었으며, 데이터베이스와 애플리케이션 간의 문자 집합 호환 문제가 해결되었습니다.

ojdbc8.jar, orai18n.jar 파일 둘다 src/main/webapp/WEB-INF/lib 에 위치해야 합니다.

반응형

---

5. 교훈

이 경험을 통해 다음과 같은 점을 배울 수 있었습니다:

• 데이터베이스와 애플리케이션 간의 문자 집합 호환성 문제는 JDBC 드라이버만으로 해결되지 않는 경우가 있습니다.
• Oracle에서 제공하는 추가 라이브러리인 orai18n.jar는 문자 집합 처리 문제를 해결하는 데 유용합니다.
• x-windows-949 인코딩과 같은 오래된 문자 집합은 현대 시스템과의 호환성 문제를 초래할 수 있으므로, 가능한 경우 UTF-8과 같은 표준 문자 집합으로 전환하는 것이 좋습니다.
• 에러 메시지를 꼼꼼히 읽고 제안된 해결책을 적용하는 것이 중요합니다.

혹시 유사한 문제가 발생한다면, 위 과정을 참고하여 문제를 해결하시기 바랍니다. 여러분도 꼭 성공적인 디버깅 하시길 바랍니다! 😊

반응형