오류 원인 분석
MySQL 데이터베이스에 이모지(Emoji)와 같은 특수 문자를 삽입하려 할 때 java.sql.SQLException: Incorrect string value 오류가 발생하는 경우가 있습니다. 이 오류는 주로 데이터베이스의 열(Column)이 해당 문자를 지원하지 않는 문자 집합(Character Set)을 사용하고 있을 때 발생합니다.
기본적인 MySQL의 utf8 문자 집합은 문자당 최대 3바이트만 할당합니다. 반면, 이모지와 같은 일부 유니코드 문자는 4바이트 공간을 필요로 합니다. 따라서 3바이트 제한이 있는 utf8 환경에서 4바이트 문자를 저장하려 시도하면 데이터베이스는 값을 처리할 수 없어 위와 같은 오류를 반환합니다. 이 문제를 해결하기 위해서는 utf8mb4 문자 집합을 사용해야 합니다.
1. 데이터베이스 및 테이블 문자 집합 확인
문제를 해결的第一 단계는 현재 스키마와 테이블이 올바른 문자 집합을 사용하고 있는지 확인하는 것입니다. 이모지 저장을 지원하기 위해서는 문자 집합이 utf8mb4로 설정되어 있어야 합니다.
먼저 MySQL 서버의 기본 문자 집합 변수를 확인합니다:
SHOW VARIABLES WHERE Variable_name LIKE 'character\_set\_%' OR Variable_name = 'collation%';
다음으로, 문제가 발생하는 테이블의 생성 스크립트를 확인하여 테이블과 열 수준의 문자 집합 설정을 검토합니다:
SHOW CREATE TABLE user_info;
만약 확인 결과 데이터베이스와 테이블의 문자 집합이 모두 utf8mb4로 설정되어 있음에도 불구하고 오류가 지속된다면, 문제의 원인은 데이터베이스 설정이 아닌 애플리케이션의 연결 설정에 있을 가능성이 높습니다.
2. JDBC 연결 문자열 점검
애플리케이션과 데이터베이스 간의 연결에서도 문자 인코딩을 명시해야 합니다. Spring Boot 등을 사용할 때 application.properties 또는 설정 파일의 데이터소스 URL을 확인하십시오. 연결 문자열에 useUnicode=true와 characterEncoding=utf8mb4가 포함되어 있는지 확인하고, 누락되었다면 추가해야 합니다.
spring.datasource.url=jdbc:mysql://localhost:3306/main_db?useUnicode=true&characterEncoding=utf8mb4
3. 연결 초기화 쿼리 실행 (SET NAMES utf8mb4)
문자 집합 설정과 JDBC URL 설정이 올바름에도 불구하고 문제가 해결되지 않는 경우, 연결이 생성된 직후 문자 집합을 강제로 지정하는 초기화 쿼리를 실행해야 합니다. 사용하는 커넥션 풀(Connection Pool)의 종류에 따라 설정 방법이 다릅니다.
커넥션 풀을 사용하지 않는 경우 (JDBC 직접 사용):
SQL 쿼리를 실행하기 전에 아래와 같이 Statement를 통해 명령을 실행합니다.
Connection dbConn = DriverManager.getConnection(dbUrl, dbUser, dbPass);
Statement initStmt = dbConn.createStatement();
initStmt.execute("SET NAMES utf8mb4");
// 이후 정상적인 쿼리 실행
initStmt.close();
Druid 커넥션 풀을 사용하는 경우:
설정 파일에 연결 초기화 SQL 속성을 추가합니다.
spring.datasource.druid.connection-init-sqls=SET NAMES utf8mb4
HikariCP 커넥션 풀을 사용하는 경우:
Druid와 유사하게 초기화 SQL 속성을 사용하여 설정합니다.
spring.datasource.hikari.connection-init-sql=SET NAMES utf8mb4
SET NAMES utf8mb4의 작동 원리
SET NAMES utf8mb4 명령은 클라이언트와 서버 간의 문자 집합 불일치 문제를 해결하는 핵심적인 역할을 합니다. 이 명령어를 실행하면 MySQL은 내부적으로 다음 세 가지 시스템 변수를 동시에 설정합니다:
- character_set_client: 클라이언트가 서버로 보내는 문장의 문자 집합을
utf8mb4로 설정합니다. 이를 통해 애플리케이션이 전송하는 이모지 데이터가 올바르게 해석됩니다. - character_set_connection: 클라이언트와 서버 간의 연결에서 사용할 문자 집합을 설정합니다.
- character_set_results: 서버가 클라이언트로 반환하는 결과값(예: SELECT 쿼리의 결과)의 문자 집합을
utf8mb4로 설정하여 데이터가 깨지지 않고 전달되도록 보장합니다.
이러한 설정을 통해 데이터 전송 과정 전반에서 문자 인코딩이 일관되게 유지되므로, 4바이트 문자인 이모지를 안전하게 저장하고 조회할 수 있게 됩니다.