📌 Spring 커넥션 풀 유효성 검사 쿼리 설정 방법 (HikariCP, DBCP, Tomcat JDBC 완벽 정리)

 스프링(Spring)에서 커넥션 풀을 사용할 때 유효성 검사 쿼리(Validation Query)를 설정하지 않으면, 오래된 DB 연결로 인해 SQL Error, Connection reset, HikariPool connection timeout과 같은 오류가 발생할 수 있습니다. 이 포스팅에서는 HikariCP, Apache DBCP2, Tomcat JDBC 등에서 커넥션 풀 유효성 검사 쿼리를 설정하는 방법을 코드와 함께 정리했습니다.

🔍 커넥션 풀과 유효성 검사 쿼리가 중요한 이유

✔ 커넥션 풀(Connection Pool)이란?

커넥션 풀은 애플리케이션에서 데이터베이스와의 연결을 반복 생성하지 않고 재사용하여 성능을 높이는 기술입니다. 대표적인 커넥션 풀 라이브러리로는 HikariCP, Apache Commons DBCP, Tomcat JDBC가 있습니다.

✔ 유효성 검사 쿼리(Validation Query)의 역할

DB 커넥션이 유효한지 검사하기 위해 실행하는 단순 쿼리로, 비정상적인 연결을 사전에 감지해 오류를 방지합니다. 다음과 같은 문제가 있을 때 매우 유용합니다

• DB 서버가 연결을 끊었는데 커넥션 풀은 인식하지 못한 경우
• 재시작이나 네트워크 이슈로 연결이 무효화된 경우
• "HikariPool-1 - Connection is not available" 에러 발생 시

✅ DB별 유효성 검사 쿼리 예시

DBMS	유효성 검사 쿼리
MySQL	SELECT 1
PostgreSQL	SELECT 1
Oracle	SELECT 1 FROM DUAL
H2	SELECT 1
MSSQL	SELECT 1 또는 SELECT 1 AS result

✅ Spring에서 커넥션 풀 유효성 쿼리 설정 방법

1️⃣ HikariCP 설정 (Spring Boot 기준)

Spring Boot에서 application.properties 또는 Java Config로 설정 가능하며, HikariCP는 기본 커넥션 풀입니다.

🔹 application.properties 사용 시

spring.datasource.hikari.validation-timeout=5000
spring.datasource.hikari.connection-test-query=SELECT 1

🔹 Java 코드로 설정 시

@Bean
public DataSource dataSource() {
    HikariConfig config = new HikariConfig();
    config.setJdbcUrl("jdbc:mysql://localhost:3306/mydb");
    config.setUsername("user");
    config.setPassword("password");

    // 유효성 검사 쿼리 설정
    config.setConnectionTestQuery("SELECT 1");
    config.setValidationTimeout(5000);

    return new HikariDataSource(config);
}

💡 Hikari는 connectionTestQuery 없이도 isValid()를 사용하지만, 명시적으로 쿼리를 지정하면 안정성이 더 높습니다.

2️⃣ Apache Commons DBCP2 설정 (XML 또는 Java Config)

🔹 XML 설정 예시

<bean id="dataSource" class="org.apache.commons.dbcp2.BasicDataSource">
    <property name="driverClassName" value="com.mysql.cj.jdbc.Driver"/>
    <property name="url" value="jdbc:mysql://localhost:3306/mydb"/>
    <property name="username" value="user"/>
    <property name="password" value="password"/>
    
    <!-- 유효성 검사 -->
    <property name="validationQuery" value="SELECT 1"/>
    <property name="testOnBorrow" value="true"/>
</bean>

🔹 Java 설정 예시

BasicDataSource dataSource = new BasicDataSource();
dataSource.setUrl("jdbc:mysql://localhost:3306/mydb");
dataSource.setUsername("user");
dataSource.setPassword("password");
dataSource.setValidationQuery("SELECT 1");
dataSource.setTestOnBorrow(true);

3️⃣ Tomcat JDBC 설정

spring.datasource.tomcat.validation-query=SELECT 1
spring.datasource.tomcat.test-on-borrow=true

또는 XML에서는 다음과 같이 설정할 수 있습니다

<property name="validationQuery" value="SELECT 1"/>
<property name="testOnBorrow" value="true"/>

🚨 유의 사항

• 너무 자주 유효성 검사를 하면 성능에 영향을 줄 수 있습니다. 적절한 validation interval 설정이 필요합니다.
• 쿼리는 최대한 빠르게 실행 가능한 단순 쿼리로 작성해야 합니다.
• 사용하는 DBMS에 따라 쿼리 문법이 다르니 반드시 확인하세요.

✅ 마무리

Spring에서 커넥션 풀 설정 시 유효성 검사 쿼리를 추가하면, 무효 커넥션으로 인한 장애나 예외를 효과적으로 방지할 수 있습니다. 특히 장시간 유지되는 서비스나 배치 처리, AWS RDS 환경에서는 필수적인 설정입니다.