Java

Java (JDBC) 클라이언트

DuckDB Java (JDBC) 클라이언트는 Java 애플리케이션이 표준 JDBC API를 통해 DuckDB를 쿼리할 수 있게 해줘요. 대량 로드, Apache Arrow 교환, 사용자 정의 함수, 프로파일링 같은 DuckDB 특화 기능도 확장으로 제공된답니다. 함께 살펴볼까요?

출처: 문서

본문

설치: DuckDB Java (JDBC) 클라이언트를 사용하려면 [Java 설치 페이지]({% link install/index.html %}?environment=java)를 방문하세요.

DuckDB Java (JDBC) 클라이언트의 최신 안정 버전은 {% if site.current_duckdb_java_short_version != "" %}{{ site.current_duckdb_java_short_version }}{% else %}{{ site.lts_duckdb_java_short_version }}{% endif %}이에요.

DuckDB Java (JDBC) 클라이언트는 Java 애플리케이션이 표준 JDBC API를 통해 DuckDB를 쿼리할 수 있게 해주며, 대량 로드, Apache Arrow 교환, 사용자 정의 함수, 프로파일링을 위한 DuckDB 특화 기능으로 확장되어 있어요. 또한 JDBC URL에서 직접 [DuckLake]({% link docs/current/core_extensions/ducklake.md %}) 카탈로그를 열 수 있고, 드라이버는 [GraalVM Native Image]({% link docs/current/clients/java/deploy_native_image.md %})로 ahead-of-time 컴파일도 지원해요.

이 페이지는 설치를 다루고, 이 섹션의 다른 페이지들은 연결과 각 기능을 자세히 다루고 있어요.

설치 (Installation)

DuckDB Java JDBC API는 Maven Central에서 설치할 수 있어요. 자세한 내용은 [설치 페이지]({% link install/index.html %}?environment=java)를 참고하세요.

팁 안정 릴리스에 도달하기 전에 기능을 시험해 보려면, JDBC 드라이버의 미리보기(야간) 빌드가 SNAPSHOT 버전으로 DuckDB의 스냅샷 저장소인 https://duckdb-staging.duckdb.org/duckdb/duckdb-java/maven에 게시돼요. 이는 탐색 가능한 웹 페이지가 없는 객체 스토리지 저장소로, Maven이 직접 소비해요. 저장소를 빌드에 추가하고 duckdb_jdbc SNAPSHOT 버전에 의존하세요. 전체 Maven 예시는 [preview builds 페이지]({% link install/preview.md %})를 참고하세요.

기본 API 사용법 (Basic API Usage)

DuckDB의 JDBC API는 표준 Java Database Connectivity (JDBC) API 버전 4.1의 주요 부분을 구현해요. JDBC 자체를 설명하는 것은 이 페이지의 범위를 벗어나므로, 자세한 내용은 공식 문서를 참고하세요. 아래에서는 DuckDB 특화 부분에 집중할게요.

JDBC 사양에 대한 우리의 확장에 대한 자세한 내용은 외부에서 호스팅되는 API Reference나 [Arrow 메서드]({% link docs/current/clients/java/result_handling.md %}#arrow-methods)를 참고하세요.

연결 열기 (Opening a Connection)

JDBC에서 데이터베이스 연결은 표준 java.sql.DriverManager 클래스로, jdbc:duckdb: JDBC URL 접두사를 사용해 만들어요:

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.Statement;

Connection conn = DriverManager.getConnection("jdbc:duckdb:");

jdbc:duckdb:만 사용하면 인메모리 데이터베이스를 열어요. 파일 이름을 붙이면, 예를 들어 jdbc:duckdb:/tmp/my_database, 대신 영속 데이터베이스를 열어요.

드라이버가 클래스패스에 있고 연결을 열 수 있는지 확인하려면 간단한 쿼리를 실행해 보세요:

try (Statement stmt = conn.createStatement();
     ResultSet rs = stmt.executeQuery("SELECT 42")) {
    rs.next();
    System.out.println(rs.getInt(1)); // prints 42
}

[Define Connections]({% link docs/current/clients/java/connecting.md %})는 연결 수명주기를 전체적으로 다뤄요: 드라이버가 받아들이는 URL 형식, DuckDB와 드라이버 구성 옵션, 읽기 전용 모드, 인스턴스 캐싱, 스레딩, 종료.

더 읽을거리 (Further Reading)

  • [Define Connections]({% link docs/current/clients/java/connecting.md %}) — JDBC URL 형식, 구성 옵션, 인스턴스 캐싱, 스레딩, 연결 종료.
  • [Connect to a DuckLake]({% link docs/current/clients/java/connecting.md %}#connect-to-a-ducklake) — JDBC에서 DuckLake 카탈로그 연결 또는 열기.
  • [Run Queries]({% link docs/current/clients/java/querying.md %}) — Statement와 PreparedStatement로 쿼리 보내고 DuckDB의 중첩 타입 읽기.
  • [Import Data]({% link docs/current/clients/java/data_import.md %}) — Appender와 JDBC batch writer로 데이터 대량 로드.
  • [Handle Results]({% link docs/current/clients/java/result_handling.md %}) — Apache Arrow 교환, 결과 스트리밍, 청크 결과.
  • [Deploy as Native Image]({% link docs/current/clients/java/deploy_native_image.md %}) — GraalVM Native Image로 독립 실행형 실행 파일 빌드.
  • [Clients Overview]({% link docs/current/clients/overview.md %}) — DuckDB가 JDBC와 함께 제공하는 다른 클라이언트 API.

더 알아보기 (Learn more)