[Java] PostgreSQL의 timestamptz를 Java MyBatis에서 Instant로 받는 방법

PostgreSQL에서 timestamptz는 시간대(time zone) 정보를 포함한 타임스탬프를 의미합니다. 이를 Java에서 MyBatis를 통해 받아올 때, 어떤 자료형을 사용해야 할지 고민이 생길 수 있습니다.

이번 글에서는 Instant로 매핑하는 방법을 중심으로 정리하였습니다.

1. timestamptz란?

timestamp with time zone의 약자로, UTC 기준으로 저장되며 클라이언트의 타임존에 맞춰 자동으로 변환되는 타입입니다.

예를 들어 다음과 같이 저장된 값이 있다면:

2025-07-28 15:00:00+00

한국 시간대(KST)에서는 2025-07-28 24:00:00으로 변환되어 표시됩니다.

2. Java에서 매핑 가능한 자료형

PostgreSQL의 timestamptz는 Java에서 다음 자료형들로 매핑할 수 있습니다:

• OffsetDateTime (권장)
• ZonedDateTime
• Instant ← 이번 글의 중심
• LocalDateTime (타임존 정보 손실)

이 중 Instant는 UTC 기준의 절대 시각을 표현하는 객체로, 타임존을 고려하지 않고 고정된 시점을 다룰 때 유용합니다.

3. MyBatis에서 Instant로 받는 방법

3-1. Java 클래스

import java.time.Instant;

public class LogEntry {
    private Instant createdAt;

    public Instant getCreatedAt() {
        return createdAt;
    }

    public void setCreatedAt(Instant createdAt) {
        this.createdAt = createdAt;
    }
}

3-2. MyBatis XML 매핑

<resultMap id="LogEntryMap" type="com.example.LogEntry">
    <result column="created_at" property="createdAt" javaType="java.time.Instant"/>
</resultMap>

자동 매핑이 동작할 경우 javaType은 생략해도 됩니다.

4. 적용을 위한 환경 조건

• JDBC 드라이버 버전: PostgreSQL JDBC 42.2 이상
• Java 버전: Java 8 이상 (java.time 패키지 사용 가능)
• 연결 설정 (선택):

spring.datasource.url=jdbc:postgresql://localhost:5432/mydb?serverTimezone=UTC

서버와 클라이언트 간 시간대 차이를 방지하고자 UTC를 명시해두면 변환의 일관성을 유지할 수 있습니다.

5. 주의할 점

• Instant는 시간대를 포함하지 않으므로, 지역 시간이 필요한 경우 ZoneId를 지정해 LocalDateTime 또는 ZonedDateTime으로 변환해야 합니다.

LocalDateTime localTime = createdAt.atZone(ZoneId.of("Asia/Seoul")).toLocalDateTime();

• LocalDateTime으로 매핑할 경우 타임존 정보가 손실되어 의도치 않은 시각의 오차가 발생할 수 있으므로 주의가 필요합니다.

6. 마무리

Instant는 UTC 기준의 시각을 그대로 유지하면서 PostgreSQL의 timestamptz를 정확히 받아올 수 있어, 로그 기록이나 절대 시간 기준 비교 등에 적합합니다. 애플리케이션에서 로컬 시각으로의 변환만 잘 처리한다면, Instant는 매우 안정적이고 효율적인 선택이 될 수 있습니다.