JDBC 드라이버

​

환경 요구 사항

• OpenJDK 버전 >= 8

​

Setup

{/* https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc */}
<dependency>
    <groupId>com.clickhouse</groupId>
    <artifactId>clickhouse-jdbc</artifactId>
    <version>0.9.8</version>
    <classifier>all</classifier>
</dependency>

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
implementation("com.clickhouse:clickhouse-jdbc:0.9.8:all")

// https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc
implementation 'com.clickhouse:clickhouse-jdbc:0.9.8:all'

• Maven Central에서 가져와 classpath에 추가합니다
  • 0.9.4 버전부터는 https://mvnrepository.com/artifact/com.clickhouse/clickhouse-jdbc-all 아티팩트를 사용할 수 있습니다.
  • 모든 shaded 종속성이 포함된 jar를 받으려면 한정자 all을 사용하십시오.
• 또는 공식 리포지토리의 여기에서 확인할 수 있습니다

​

구성

• jdbc:clickhouse:http://localhost:8123
• jdbc:clickhouse:https://localhost:8443?ssl=true

• URL에는 단 하나의 엔드포인트만 허용됩니다
• 프로토콜은 기본값인 ‘HTTP’가 아닌 경우에만 지정해야 합니다
• 포트가 기본값인 ‘8123’이 아닌 경우 포트를 지정해야 합니다
• 드라이버는 포트 번호만 보고 프로토콜을 추측하지 않으므로, 프로토콜을 명시적으로 지정해야 합니다
• protocol이 지정된 경우 ssl 매개변수는 필요하지 않습니다.

​

연결(Connection) 속성

Properties config = new Properties();
config.setProperty("user", "default");
config.setProperty("password", getPassword());

// 서버 설정 지정
config.put(ClientConfigProperties.serverSetting("allow_experimental_time_time64_type"), "1");

Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", config);

Properties properties = new Properties();
properties.setProperty("user", "default");
properties.setProperty("password", getPassword());
properties.setProperty("client_name", "my-app-01"); // HTTP protocol 사용 시 쿼리 로그에 `client_name`이 아닌 `http_user_agent`로 기록됩니다.

Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", properties);

jdbc:ch:http://localhost:8123/?user=default&password=password&client_name=my-app-01 
// 자격 증명은 `Properties`를 통해 전달해야 합니다. 여기서는 예시 목적으로만 사용합니다.

​

클라이언트 식별

Properties properties = new Properties();
properties.setProperty(ClientConfigProperties.CLIENT_NAME.getKey(), "my-app-01");
Connection conn = Driver.connect("jdbc:ch:http://localhost:8123/", properties);

conn.setClientInfo(com.clickhouse.jdbc.ClientInfoProperties.APPLICATION_NAME.getKey(), "my-app-01");

my-app-01/1.0 jdbc-v2/0.9.7 clickhouse-java-v2/0.9.6 (Linux; jvm:17.0.17) Apache-HttpClient/5.4.4

​

작업 식별

StatementImpl stmt = (StatementImpl) conn.createStatement();
stmt.getLocalSettings().logComment("some-comment");

​

지원되는 데이터 타입

​

JDBC 유형 매핑

• ResultSet#getObject(columnIndex) - 메서드는 해당 Java 클래스에 대응하는 객체를 반환합니다. (Int8 -> java.lang.Byte, Int16 -> java.lang.Short 등)
• ResultSetMetaData#getColumnType(columnIndex) - 메서드는 해당 JDBC 타입을 반환합니다. (Int8 -> java.lang.Byte, Int16 -> java.lang.Short 등)

• ResultSet#getObject(columnIndex, class) - 메서드는 값을 class 타입으로 변환합니다. 일부 변환에는 제한 사항이 있습니다. 자세한 내용은 각 섹션을 참조하십시오.

• 숫자 타입은 서로 변환할 수 있습니다. 따라서 Int8은 Float64로 읽을 수 있으며, 그 반대도 가능합니다.:
  • rs.getObject(1, Float64.class)는 Int8 컬럼의 Float64 값을 반환합니다.
  • rs.getLong(1)는 Int8 컬럼의 Long 값을 반환합니다.
  • rs.getByte(1)는 값이 Byte 범위에 맞으면 Int16 컬럼의 Byte 값을 반환할 수 있습니다.
• 더 넓은 범위의 자료형에서 더 좁은 범위의 자료형으로 변환하는 것은 데이터 손상 위험이 있어 권장되지 않습니다.
• Bool 유형은 숫자 역할도 합니다.
• 모든 숫자 타입은 java.lang.String으로 읽을 수 있습니다.
• Java Float.MAX_VALUE를 Float로 저장하면 문제가 발생합니다(https://github.com/ClickHouse/clickhouse-java/issues/809). 동일한 값을 Double로 저장하면 문제가 해결됩니다.

• String은 java.lang.String 또는 byte[] 형식으로만 읽을 수 있습니다.
• FixedString은 있는 그대로 읽히며, 컬럼 길이에 맞게 0으로 채워집니다. (예를 들어 'John'에 대한 FixedString(10)은 'John\0\0\0\0\0\0\0\0\0'으로 읽힙니다.)

• Enum8 및 Enum16은 기본적으로 java.lang.String으로 매핑됩니다.
• Enum 값은 지정된 getter 메서드나 getObject(columnIndex, Integer.class) 메서드를 사용해 숫자 값으로 읽을 수 있습니다.
• Enum16은 내부적으로 short로 매핑되고 Enum8은 byte로 매핑됩니다. 데이터 손상 위험이 있으므로 Enum16을 byte로 읽지 않아야 합니다.
• PreparedStatement에서는 Enum 값을 문자열이나 숫자 값으로 설정할 수 있습니다.

• Date / Time 타입은 JDBC와의 호환성을 높이기 위해 java.sql 타입에 매핑됩니다. 하지만 두 번째 인수로 해당 클래스를 지정해 ResultSet#getObject(columnIndex, Class<T>)를 사용하면 java.time.LocalDate, java.time.LocalDateTime, java.time.LocalTime도 가져올 수 있습니다.
  • rs.getObject(1, java.time.LocalDate.class)는 Date 컬럼 값을 java.time.LocalDate로 반환합니다.
  • rs.getObject(1, java.time.LocalDateTime.class)는 DateTime 컬럼 값을 java.time.LocalDateTime으로 반환합니다.
  • rs.getObject(1, java.time.LocalTime.class)는 Time 컬럼 값을 java.time.LocalTime으로 반환합니다.
• Date, Date32, Time, Time64는 서버 시간대의 영향을 받지 않습니다.
• DateTime, DateTime64는 서버의 시간대 또는 세션 시간대의 영향을 받습니다.
• DateTime 및 DateTime64는 getObject(colIndex, ZonedDateTime.class)를 사용해 ZonedDateTime으로 가져올 수 있습니다.

• 기본적으로 Array는 JDBC와의 호환성을 위해 java.sql.Array에 매핑됩니다. 이는 반환되는 배열 값에 관한 더 많은 정보를 제공하기 위한 것이기도 합니다. 유형 추론에 유용합니다.
• Array는 원래 배열과 동일한 내용을 담은 java.sql.ResultSet을 반환하도록 getResultSet() 메서드를 구현합니다.
• 컬렉션 타입은 데이터를 올바르게 표현하는 방식이 아니므로 java.lang.String으로 읽어서는 안 됩니다(예: 배열의 문자열 값에는 따옴표가 없습니다).
• Map의 값은 getObject(columnIndex, Class<T>) 메서드로만 읽을 수 있으므로 JAVA_OBJECT에 매핑됩니다.
  • Map은 이름이 있는 컬럼이 없으므로 java.sql.Struct가 아닙니다.
• Tuple은 서로 다른 타입을 포함할 수 있으며 List는 사용할 수 없기 때문에 Object[]로 매핑됩니다.
• Tuple은 getObject(columnIndex, Array.class) 메서드를 사용해 Array로 읽을 수 있습니다. 이 경우 Array#baseTypeName은 Tuple 컬럼의 정의를 반환합니다.

• typeName - 배열 요소의 타입 이름입니다. 예를 들어 Array(Int32) -> "Int32"입니다.
• elements - 실제 배열 요소입니다. 예를 들어 [[1, 2, 3], [4, 5, 6]]는 new Integer[][] {{1, 2, 3}, {4, 5, 6}}입니다.

try (Connection conn = ...) {
    Array array = conn.createArrayOf("Int32", new Integer[][] {{1, 2, 3}, {4, 5, 6}});
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (arr) VALUES (?)")) {
        ps.setArray(1, array);
        ps.executeUpdate();
    }
}

try (Connection conn = ...) {
    try (PreparedStatement ps = conn.prepareStatement("SELECT ?::Array(Int32)")) {
        ps.setArray(1, array);
        try (ResultSet rs = ps.executeQuery()) {
            while (rs.next()) {
                Array array = rs.getArray(1);

                Object[] arr = (Object[]) array;
                Arrays.stream(arr).forEach(this::handleArrayElement);

                // 또는 `ResultSet` 사용
                ResultSet resultSet = array.getResultSet();
                while (resultSet.next()) {
                    // ...
                }
            }
        }
    } 
}

try (Connection conn = ...) {
    Tuple tuple = new Tuple(1, "test", LocalDate.parse("2026-03-02"));
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (tuple) VALUES (?)")) {
        ps.setObject(1, tuple);
        ps.executeUpdate();
    }
}

try (Connection conn = ...) {
    Struct struct = conn.createStruct("Tuple(Int32, String, Date)", new Object[] {1, "test", LocalDate.parse("2026-03-02")});
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (tuple) VALUES (?)")) {
        ps.setStruct(1, struct);
        ps.executeUpdate();
    }
}

try (Connection conn = ...) {
    try (PreparedStatement stmt = conn.prepareStatement("SELECT ?::Tuple(String, Int32, Date)")) {
        Array tuple = conn.createArrayOf("Tuple(String, Int32, Date)",  new Object[]{"test", 123, LocalDate.parse("2026-03-02")});
        stmt.setObject(1, tuple);
        try (ResultSet rs = stmt.executeQuery()) {
            rs.next();
            Array dbTuple = rs.getArray(1);
            Assert.assertEquals(dbTuple, tuple);
            Object arr = rs.getObject(1);
            Assert.assertEquals(arr, tuple.getArray());
        }
    }
}

try (Connection conn = ...) {
    Map<String, Integer> map = new HashMap<>();
    map.put("key1", 1);
    map.put("key2", 2);
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (map) VALUES (?)")) {
        ps.setObject(1, map);
        ps.executeUpdate();
    }
}

try (Connection conn = ...) {
    try (PreparedStatement ps = conn.prepareStatement("SELECT ?::Map(String, Int32)")) {
        ps.setStruct(1, struct);
        try (ResultSet rs = ps.executeQuery()) {
            while (rs.next()) {
                Map<String, Integer> map = rs.getObject(1, Map.class);
                // ...
            }
        }
    }
}

• typeName - 중첩된 요소의 유형 이름입니다. 예를 들어 Nested(Tuple(Int32, String)) -> "Nested(Tuple(Int32, String))"입니다.
• elements - 실제 중첩된 요소입니다. 예를 들어 [1, 'test'] -> new Object[] {1, 'test'}입니다.

try (Connection conn = ...) {
    Struct struct = conn.createStruct("Nested(Tuple(Int32, String))", new Object[] {1, 'test'});
    try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable (nested) VALUES (?)")) {
        ps.setStruct(1, struct);
        ps.executeUpdate();
    }
}

try (Connection conn = ...) {
    try (PreparedStatement ps = conn.prepareStatement("SELECT ?::Nested(Tuple(Int32, String))")) {
        ps.setStruct(1, struct);
        try (ResultSet rs = ps.executeQuery()) {
            while (rs.next()) {
                Struct struct = rs.getStruct(1);
                Object[] tuple = (Object[]) struct;
                Arrays.stream(tuple).forEach(this::handleTupleElement);

                // 또는 `ResultSet`을 사용하는 방법
                ResultSet resultSet = struct.getResultSet();
                while (resultSet.next()) {
                    // ...
                }
            }
        }
    }
}

• Nullable 및 LowCardinality는 다른 타입을 감싸는 특수 타입입니다.
• Nullable는 ResultSetMetaData에서 타입 이름이 반환되는 방식에 영향을 미칩니다

• UUID는 JDBC 표준 유형이 아닙니다. 하지만 JDK에 포함되어 있습니다. 기본적으로 getObject() 메서드는 java.util.UUID를 반환합니다.
• UUID는 getObject(columnIndex, String.class) 메서드로 String으로 읽고 쓸 수 있습니다.
• IPv4 및 IPv6는 JDBC 표준 타입이 아닙니다. 하지만 JDK에는 포함되어 있습니다. 기본적으로 getObject() 메서드는 java.net.Inet4Address와 java.net.Inet6Address를 반환합니다.
• getObject(columnIndex, String.class) 메서드를 사용하면 IPv4와 IPv6를 String으로 읽고 쓸 수 있습니다.

​

날짜, 시간 및 시간대 처리

​

연결(Connection) 생성

String url = "jdbc:ch://my-server:8123/system";

Properties properties = new Properties();
DataSource dataSource = new DataSource(url, properties);//DataSource 또는 DriverManager가 주요 진입점입니다
try (Connection conn = dataSource.getConnection()) {
... // 연결을 사용하여 작업 수행

​

자격 증명 및 설정 제공

String url = "jdbc:ch://localhost:8123?jdbc_ignore_unsupported_values=true&socket_timeout=10";

Properties info = new Properties();
info.put("user", "default");
info.put("password", "password");
info.put("database", "some_db");

//DataSource를 사용하여 연결 생성
DataSource dataSource = new DataSource(url, info);
try (Connection conn = dataSource.getConnection()) {
... // 연결을 사용하여 작업 수행
}

//DriverManager를 사용하는 대체 방식
try (Connection conn = DriverManager.getConnection(url, info)) {
... // 연결을 사용하여 작업 수행
}

​

간단한 구문(Statement)

try (Connection conn = dataSource.getConnection(...);
    Statement stmt = conn.createStatement()) {
    ResultSet rs = stmt.executeQuery("select * from numbers(50000)");
    while(rs.next()) {
        // ...
    }
}

​

삽입

try (PreparedStatement ps = conn.prepareStatement("INSERT INTO mytable VALUES (?, ?)")) {
    ps.setString(1, "test"); // 아이디
    ps.setObject(2, LocalDateTime.now()); // 타임스탬프
    ps.addBatch();
    ...
    ps.executeBatch(); // 보유한 모든 데이터를 ClickHouse로 스트리밍
}

​

HikariCP

// 연결 풀링은 성능 면에서 큰 도움이 되지 않습니다.
// 내부 구현에 자체 풀이 있기 때문입니다.
// 예시: HttpURLConnection은 소켓용 풀을 보유합니다.
HikariConfig poolConfig = new HikariConfig();
poolConfig.setConnectionTimeout(5000L);
poolConfig.setMaximumPoolSize(20);
poolConfig.setMaxLifetime(300_000L);
poolConfig.setDataSource(new ClickHouseDataSource(url, properties));

try (HikariDataSource ds = new HikariDataSource(poolConfig);
     Connection conn = ds.getConnection();
     Statement s = conn.createStatement();
     ResultSet rs = s.executeQuery("SELECT * FROM system.numbers LIMIT 3")) {
    while (rs.next()) {
        // 행 처리
        log.info("Integer: {}, String: {}", rs.getInt(1), rs.getString(1));//동일한 컬럼이지만 타입이 다름
    }
}

​

추가 정보

​

문제 해결

​

로깅

​

대용량 삽입 시 JDBC 타임아웃 해결

Caused by: java.sql.SQLException: Read timed out, server myHostname [uri=https://hostname.aws.clickhouse.cloud:8443]

​

Mac OS

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1

​

Linux

1. 다음 Linux 커널 매개변수를 /etc/sysctl.conf 또는 관련 설정 파일에서 조정하세요:

• net.inet.tcp.keepidle: 60000
• net.inet.tcp.keepintvl: 45000
• net.inet.tcp.keepinit: 45000
• net.inet.tcp.keepcnt: 8
• net.inet.tcp.always_keepalive: 1
• net.ipv4.tcp_keepalive_intvl: 75
• net.ipv4.tcp_keepalive_probes: 9
• net.ipv4.tcp_keepalive_time: 60 (기본값인 300초에서 이 값을 더 낮추는 것을 고려할 수 있습니다)

2. 커널 매개변수를 수정한 후 다음 명령을 실행하여 변경 사항을 적용하십시오:

sudo sysctl -p

properties.setProperty("socket_keepalive", "true");

​

마이그레이션 가이드

​

주요 변경 사항

• JDBC V2는 더 경량화되도록 구현되었으며, 일부 기능은 제거되었습니다.
  • 스트리밍 데이터는 JDBC 사양 및 Java 자체에 포함되지 않으므로 JDBC V2에서는 지원되지 않습니다.
• JDBC V2는 명시적인 구성이 필요합니다. failover 기본값은 없습니다.
  • URL에 protocol을 명시해야 합니다. 포트 번호를 이용한 암묵적 protocol 감지는 지원하지 않습니다.

​

구성 변경 사항

• com.clickhouse.jdbc.DriverProperties - 드라이버 고유의 구성 속성입니다.
• com.clickhouse.client.api.ClientConfigProperties - 클라이언트 구성 속성입니다. 클라이언트 구성 변경 사항은 Java 클라이언트 문서에 설명되어 있습니다.

• 먼저 URL에서 속성을 파싱합니다. 이렇게 파싱된 속성은 다른 모든 속성을 재정의합니다.
• 드라이버 속성은 클라이언트로 전달되지 않습니다.
• 엔드포인트(host, port, protocol)는 URL에서 파싱됩니다.

String url = "jdbc:ch://my-server:8443/default?" +
            "jdbc_ignore_unsupported_values=true&" +
            "socket_rcvbuf=800000";

Properties properties = new Properties();
properties.setProperty("socket_rcvbuf", "900000");
try (Connection conn = DriverManager.getConnection(url, properties)) {
    // 연결은 socket_rcvbuf=800000 및 jdbc_ignore_unsupported_values=true를 사용합니다
    // Endpoints: my-server:8443 protocol: http (보안 없음)
    // 데이터베이스: default
}

​

데이터 타입 변경 사항

• 가장 큰 차이점은 이식성을 높이기 위해 부호 없는 타입이 Java 타입으로 매핑된다는 점입니다.

• 두 버전 모두에서 FixedString은 그대로 읽습니다. 예를 들어 'John'의 FixedString(10)은 'John\0\0\0\0\0\0\0\0\0'으로 읽습니다.
• PreparedStatement#setBytes를 사용하면 unhex('<hex_string>')로 변환된 후 String으로 읽습니다.
• 문자열은 UTF-8 인코딩으로 저장됩니다.

• Time 및 Time64는 V2에서만 새 타입으로 지원됩니다.
• DateTime 및 DateTime64는 JDBC와의 호환성을 높이기 위해 java.sql.Timestamp로 매핑됩니다.

• V2에서는 JDBC와의 호환성을 위해 기본적으로 Array를 java.sql.Array에 매핑합니다. 이렇게 하면 반환되는 배열 값에 대한 정보를 더 많이 제공할 수 있습니다. 유형 추론에 유용합니다.
• V2에서는 Array가 getResultSet() 메서드를 구현하여 원본 배열과 동일한 내용을 담은 java.sql.ResultSet을 반환합니다.
• V1은 Map에 STRUCT를 사용하지만, 항상 java.util.Map 객체를 반환합니다. V2는 Map을 JAVA_OBJECT로 매핑해 이 문제를 해결합니다.
• V1에서는 Tuple에 STRUCT를 사용하지만, 항상 List<Object> 객체를 반환합니다. V2에서는 Tuple을 OTHER로 매핑하며, 기본적으로 Object[]를 반환합니다.
• V2에서는 튜플을 기록하기 위해 com.clickhouse.data.Tuple#Tuple를 도입합니다. 값이 튜플인지 배열인지 판별하는 작업을 단순화합니다.
• PreparedStatement#setBytes 및 ResultSet#getBytes는 컬렉션 타입에는 사용할 수 없습니다. 이 메서드들은 바이너리 문자열에서 작동하도록 설계되었습니다.
• 일반적으로 배열(Array) 타입을 읽고 쓸 때는 java.sql.Array를 사용합니다. JDBC 드라이버는 이를 완벽하게 지원합니다.
• V2 Nested는 Array로 매핑되며, 튜플 배열로 표시됩니다.
• V2는 java.sql.Struct가 배열과 매우 유사하고 key-value 쌍을 지원하지 않으므로 부분적으로만 지원합니다. Struct는 Tuple 값을 쓰는 데 사용할 수 있습니다.

• Nullable와 LowCardinality는 다른 타입을 감싸는 특수 타입입니다.
• V2에서는 이러한 타입에 변경이 없습니다.

• V1은 UUID에 VARCHAR를 사용하지만, 항상 java.util.UUID 객체를 반환합니다. V2는 UUID를 OTHER로 매핑해 이 문제를 해결하고, java.util.UUID 객체를 반환합니다.
• V1은 IPv4 및 IPv6에 VARCHAR를 사용하지만, 반환값은 항상 java.net.Inet4Address 및 java.net.Inet6Address 객체입니다. V2는 IPv4 및 IPv6를 OTHER로 매핑해 이 문제를 해결했으며, java.net.Inet4Address 및 java.net.Inet6Address 객체를 반환합니다.
• Dynamic 및 Variant는 V2에서 새로 도입된 타입입니다. V1에서는 지원되지 않습니다.
• JSON은 Dynamic 타입을 기반으로 합니다. 따라서 V2에서만 지원됩니다.
• IPv4 및 IPv6 값은 getBytes(columnIndex) 메서드를 사용해 byte[]로 읽을 수 있습니다. 그러나 이러한 타입에는 전용 클래스를 사용하는 것이 좋습니다.
• V2는 IP 주소를 숫자 값으로 읽는 기능을 지원하지 않습니다. 변환은 InetAddress 클래스에서 처리하는 편이 더 적절하기 때문입니다.

​

데이터베이스 메타데이터 변경 사항

• V2에서는 데이터베이스를 지칭하는 용어로 Schema만 사용합니다. Catalog는 향후 사용을 위해 예약되어 있습니다.
• V2는 DatabaseMetaData.supportsTransactions() 및 DatabaseMetaData.supportsSavepoints()에 대해 false를 반환합니다. 이 동작은 향후 개발 과정에서 변경될 예정입니다.