Spring Boot 콘솔 애플리케이션에서 H2 인메모리 데이터베이스를 TCP 서버 모드로 설정하는 방법

✅ Spring Boot 콘솔 프로젝트에서 H2 DB를 TCP 서버 모드로 설정하는 이유

Spring 웹 애플리케이션에서 H2 인메모리 DB를 사용하는것과 마찬가지로 Spring Boot로 콘솔 기반 프로젝트에서도 H2 DB를 이용할 수 있는데요.

그런데 Spring 웹 애플리케이션에서 H2를 사용할 때처럼 콘솔 프로젝트에도 동일한 방식으로 사용할 수 있다라고 생각하기 쉬운데 웹 애플리케이션과 콘솔 애플리케이션은 구조적으로 동작 방식이 다릅니다.

 

🔍 웹 애플리케이션 vs 콘솔 애플리케이션의 차이점

구분	Spring 웹 애플리케이션	Spring 콘솔 애플리케이션
실행 방식	서버로 실행됨 (8080 등에서 계속 대기)	메인 메서드 실행 후 바로 종료
H2 DB 유지	실행 중엔 메모리 DB 유지 가능	애플리케이션 종료 시 H2 DB도 즉시 종료
외부 도구 접근	결과 확인을 위해 브라우저나 툴에서 접근하기 쉬움	브라우저나 툴에서 접근하기 어려움

그래서 저는 콘솔 애플리케이션에서 H2 DB를 TCP 서버 모드로 띄워서 외부 툴(IntelliJ 등)에서도 접근 가능하도록 구성하는 방식을 적용했고, 잘 동작하는걸 확인을 했는데 지금부터 그 구성 방식을 설명 드리도록 하겠습니다.

 

🛠 H2 TCP 서버 모드 설정 방법

1. Spring Boot 기본 H2 설정

spring:
  datasource:
    url: jdbc:h2:mem:testdb
    driver-class-name: org.h2.Driver
    username: sa
    password:

이 설정은 Spring Boot의 프로퍼티 설정 파일인 application.yml의 설정 내용인데 H2를 메모리 DB로 사용하기 위한 설정이기 때문에 애플리케이션이 종료되면 DB도 함께 종료되어서 메모리에 저장된 데이터가 사라집니다.

⚠️주의: Spring Boot는 Embedded 방식으로 DB를 연결해야 하며, TCP URL 사용 시 Spring Boot 애플리케이션에서 Embedded 방식의 DB에 연결하는 것이 아니라 Spring Boot 애플리케이션 외부의 H2 DB에 연결하려하기 때문에 tcp:// 형식으로 설정하면 Database not found 오류가 발생할 수 있으므로 주의해야합니다.

 

2. H2 TCP 서버를 코드로 실행하기

@Slf4j
@Configuration
public class H2ServerConfig {

    @Bean
    public CommandLineRunner startH2Server() {
        log.info("# h2 server started");
        return args -> {
            Server.createTcpServer("-tcp", "-tcpAllowOthers", "-tcpPort", "9092").start();
        };
    }
}

콘솔 애플리케이션 종료 시, H2 DB가 함께 종료되지 않도록 Spring Boot에서는 @Bean 애너테이션으로 H2를 TCP 서버 모드로 띄울 수 있도록합니다.

 

🧪 IntelliJ에서 연결하기

이제 IntelliJ에서 H2에 접속할 수 있도록 아래와 같은 순서로 설정하도록 합니다.

• Database 탭 → Data Source → H2 선택
• JDBC URL: jdbc:h2:tcp://localhost:9092/mem:testdb
• User: sa, Password: 비워도 OK
• 이렇게 설정하면 콘솔 애플리케이션이 즉시 종료되지 않고 애플리케이션이 실행 중일 때 H2에 접속할 수 있게 됩니다.
  

 

💥 흔히 발생하는 오류와 해결 방법

잘못된 설정 예시

예를 들어서 application.yml에서의 H2 설정을 클래스 레벨에서도 구성할 수 있는데 아래와 같이 tcp://로 시작하는 URL과 같이 설정하면 어떻게 될까요?

System.setProperty("spring.datasource.url", "jdbc:h2:tcp://localhost:9092/mem:testdb"); // ❌ 오류 발생

위에서 설명했던 것 처럼 마찬가지로 Spring 애플리케이션이 외부 TCP 서버로 접속을 시도하게 되어, Database not found 또는 Connection refused와 같은 오류가 발생할 수 있습니다.

 

정상 설정 예시

System.setProperty("spring.datasource.url", "jdbc:h2:mem:testdb"); // ✅ 올바른 방식

application.yml이 아닌 클래스 레벨에서 H2를 설정할 경우에는 꼭 tcp://localhost:9092를 제외하고 지정해야 한다는 사실을 기억하세요.

 

📌 H2 관련 포트 정리

모드	기본 포트	설명
H2 TCP 서버	9092	외부 툴(JDBC 클라이언트) 접속용
H2 Web Console	8082	브라우저에서 사용하는 Web UI
Spring Boot	8080	Spring 애플리케이션 기본 포트

 

📎 마무리 요약

• 콘솔 기반 Spring Boot 앱에서는 H2를 TCP 서버 모드로 띄워야 실시간 DB 확인이 가능하다는 사실을 기억해 주세요.
• Spring 내부는 mem:testdb로 접근, 외부 툴은 tcp://localhost:9092로 연결해야 한다는 사실을 잊지 마세요.

 

이 포스트가 Spring Boot 기반의 콘솔 애플리케이션에서 H2를 효율적으로 사용하는 데 도움이 되었길 바랍니다.

감사합니다!