Databricks JDBC 드라이버(OSS)

Important

이 드라이버는 공개 미리 보기 상태이며 아직 오픈 소스로 사용할 수 없습니다.

Databricks는 데이터베이스 관리 시스템에 액세스하기 위한 업계 표준 사양인 JDBC(Java Database Connectivity)를 통해 DataGrip, DBeaver, SQL Workbench/J 와 같은 도구를 Azure Databricks에 연결할 수 있는 OSS(오픈 소스 소프트웨어) JDBC 드라이버를 제공합니다.

이 드라이버는 JDBC API를 구현했으며 OAuth, Cloud Fetch 그리고 Unity 카탈로그 볼륨 수집과 같은 기능을 비롯한 핵심 기능을 제공합니다. 네이티브 쿼리 모드를 실행하고 네이티브 매개 변수가 있는 쿼리를 지원하며, 유익한 쿼리 결과 보존 기능 또는 Thrift를 제공하는 문 실행 API를 사용하여 실행할 수 있습니다.

이 문서에서는 Databricks JDBC 드라이버(OSS)를 설치하고 사용하는 방법에 대한 정보를 제공합니다. 비 OSS Databricks JDBC 드라이버에 대한 자세한 내용은 Databricks JDBC 드라이버를 참조하세요.

요구 사항

Databricks JDBC 드라이버(OSS)를 사용하려면 다음 요구 사항을 충족해야 합니다.

• Java Runtime Environment(JRE) 11.0 이상. CI 테스트는 JRE 11, 17 및 21에서 지원됩니다.

참고 항목

JDBC 드라이버에서 사용하는 Apache Arrow 라이브러리와의 호환성 문제를 발생시킨 JDK 16의 변경으로 인해 JDBC 드라이버를 JDK 16 이상에서 사용할 때 런타임 오류가 발생할 수 있습니다. 이러한 오류를 방지하려면 다음 JVM 명령 옵션을 사용하여 애플리케이션 또는 드라이버를 다시 시작합니다.

--add-opens=java.base/java.nio=org.apache.arrow.memory.core ALL-UNNAMED

드라이버 설치

Databricks JDBC 드라이버(OSS)는 Maven 리포지토리에 게시됩니다. 최신 버전은 0.9.6 oss입니다.

드라이버를 설치하려면 다음 중 원하는 작업을 수행할 수 있습니다.

• Maven 프로젝트의 경우 프로젝트의 pom.xml 파일에 다음 종속성을 추가하여 Maven에 지정된 버전으로 JDBC 드라이버를 자동으로 다운로드하도록 지시합니다.

  <dependency>
    <groupId>com.databricks</groupId>
    <artifactId>databricks-jdbc</artifactId>
    <version>0.9.6-oss</version>
    <scope>runtime</scope>
  </dependency>
  

• Gradle 프로젝트의 경우 프로젝트의 빌드 파일에 다음 종속성을 추가하여 Gradle에 지정된 버전으로 JDBC 드라이버를 자동으로 다운로드하도록 지시합니다.

  implementation 'com.databricks:databricks-jdbc:0.9.6-oss'
  

다른 프로젝트 형식에 대한 종속성 구문을 보고 최신 버전의 DATAbricks JDBC 드라이버(OSS)를 얻으려면 Maven 리포지토리를 참조하세요.

연결 URL 구성

JDBC 드라이버를 사용하여 Azure Databricks 작업 영역에 연결하려면 Azure Databricks 작업 영역의 서버 호스트 이름, 컴퓨팅 리소스 설정, 인증 자격 증명과 같은 다양한 연결 설정을 포함하는 JDBC 연결 URL을 지정하여 작업 영역에 연결해야 합니다.

JDBC 연결 URL에서 이러한 속성의 값을 설정하고 DriverManager.getConnection메서드 또는 둘 다의 조합으로 설정하고 전달할 수 있습니다. 특정 앱, 클라이언트, SDK, API 또는 SQL 도구를 사용하여 연결하는 가장 좋은 방법은 공급자의 설명서를 참조하세요.

JDBC 연결 URL의 형식은 다음과 같아야 합니다. 속성은 대/소문자를 구분하지 않습니다.

jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];...

또는 java.util.Properties 클래스 또는 조합을 사용하여 설정을 지정합니다.

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>";
Properties properties = new java.util.Properties();
properties.put("<property1>", "<value1");
properties.put("<property2>", "<value2");
// ...
Connection conn = DriverManager.getConnection(url, properties);

String url = "jdbc:databricks://<server-hostname>:<port>/<schema>;[property1]=[value];[property2]=[value];";
Connection conn = DriverManager.getConnection(url, "token", "12345678901234667890abcdabcd");

연결 URL 요소는 다음 표에 설명되어 있습니다. 인증 속성을 비롯한 추가 속성에 대한 자세한 내용은 아래 섹션을 참조하세요. URL 요소 및 속성은 대/소문자를 구분하지 않습니다.

URL 요소 또는 속성	설명
<server-hostname>	Azure Databricks 컴퓨팅 리소스의 서버 호스트 이름 값입니다.
<port>	Azure Databricks 컴퓨팅 리소스의 포트 값입니다. 기본값은 443입니다.
<schema>	스키마의 이름입니다. 또는 ConnSchema 속성을 설정할 수 있습니다. 연결 속성을 참조하세요.
httpPath	Azure Databricks 컴퓨팅 리소스의 HTTP 경로 값입니다. 커넥터는 연결 URL에 지정된 호스트 및 포트에 httpPath 값을 추가하여 연결할 HTTP 주소를 형성합니다. 예를 들어 HTTP 주소 http://localhost:10002/cliservice에 연결하려면 다음 연결 URL jdbc:databricks://localhost:10002;httpPath=cliservice을 사용합니다.

Azure Databricks 클러스터에 대한 JDBC 연결 URL을 얻으려면 다음을 수행합니다.

1. Azure Databricks 작업 영역으로 로그인합니다.
2. 사이드바에서 컴퓨팅을 클릭한 다음 대상 클러스터의 이름을 클릭합니다.
3. 구성 탭에서 고급 옵션을 확장합니다.
4. JDBC/ODBC 탭을 클릭합니다.
5. JDBC 연결 URL로 사용할 JDBC URL을 복사하거나 서버 호스트 이름, 포트 및 HTTP 경로 필드의 값에서 URL을 생성합니다.

Databricks SQL 웨어하우스에 대한 JDBC 연결 URL을 얻으려면 다음을 수행합니다.

1. Azure Databricks 작업 영역으로 로그인합니다.
2. 사이드바에서 SQL 웨어하우스를 클릭한 다음 대상 웨어하우스의 이름을 클릭합니다.
3. 연결 세부 정보 탭을 클릭합니다.
4. JDBC 연결 URL로 사용할 JDBC URL을 복사하거나 서버 호스트 이름, 포트 및 HTTP 경로 필드의 값에서 URL을 생성합니다.

드라이버 인증

다음 인증 메커니즘 중 하나를 사용하여 JDBC 드라이버 연결을 인증할 수 있습니다.

• OAuth 사용자 대 컴퓨터(U2M) 인증(권장)
• OAuth M2M(machine-to-machine) 인증
• Azure Databricks 개인용 액세스 토큰

OAuth 사용자 대 컴퓨터(U2M) 인증

JDBC 드라이버는 실시간 사용자 로그인 및 대상 Databricks 사용자 계정 인증에 동의하기 위한 OAuth U2M(사용자 대 컴퓨터) 인증을 지원합니다. 이를 브라우저 기반 OAuth 인증이라고도 합니다.

Azure Databricks는 고객을 위한 OAuth 클라이언트 ID databricks-sql-jdbc를 만들었습니다. JDBC 드라이버에서 사용되는 기본 OAuth 클라이언트 ID이기도 합니다. OAuth U2M 인증을 구성하려면 기존 JDBC 연결 URL 또는 java.util.Properties 개체에 다음 속성을 추가하면 됩니다.

속성	값
AuthMech	11
Auth_Flow	2

OAuth M2M(machine-to-machine) 인증

JDBC 드라이버는 Azure Databricks 서비스 주체를 사용하여 OAuth M2M(machine-to-machine) 인증을 지원합니다. 이를 OAuth 2.0 클라이언트 자격 증명 인증이라고도 합니다. OAuth(OAuth M2M)를 사용하여 서비스 주체로 Azure Databricks에 액세스 인증을 참조하세요.

OAuth M2M 또는 OAuth 2.0 클라이언트 자격 증명 인증을 구성하려면 다음을 수행합니다.

1. Microsoft Entra ID 관리 서비스 주체를 만든 다음 Azure Databricks 계정 및 작업 영역에 할당합니다. 자세한 내용은 서비스 주체 관리를 참조하세요.

   Important

   Databricks JDBC 드라이버(OSS)는 OAuth M2M 또는 OAuth 2.0 클라이언트 자격 증명 인증에 대한 Azure Databricks OAuth 비밀을 지원합니다. Microsoft Entra ID 비밀은 지원되지 않습니다.

2. 서비스 주체에 대한 Azure Databricks OAuth 비밀을 만듭니다. 이렇게 하려면 OAuth M2M 인증을 위한 액세스 토큰 수동 생성 및 사용을 참조하세요.

3. 서비스 주체에게 클러스터 또는 웨어하우스에 대한 액세스 권한을 부여합니다. 컴퓨팅 사용 권한 또는 SQL 웨어하우스 관리를 참조하세요.

기존 JDBC 연결 URL 또는 java.util.Properties 개체에 다음 속성을 추가합니다.

속성	값
AuthMech	11
Auth_Flow	1
OAuth2ClientID	서비스 주체의 애플리케이션(클라이언트) ID 값입니다.
OAuth2Secret	서비스 주체의 Azure Databricks OAuth 비밀입니다. (Microsoft Entra ID 비밀은 OAuth M2M 또는 OAuth 2.0 클라이언트 자격 증명 인증에 대해 지원되지 않습니다.)

Azure Databricks 개인용 액세스 토큰

Azure Databricks 개인용 액세스 토큰을 사용하여 JDBC 드라이버 연결을 인증하려면 JDBC 연결 URL 또는 java.util.Properties 개체에 다음 속성을 추가합니다.

속성	값
AuthMech	3
user	token 문자열 값입니다.
PWD 또는 password	Azure Databricks 개인용 액세스 토큰 문자열 값입니다.

연결 속성

JDBC 드라이버에서 지원하는 추가 연결 속성은 다음과 같습니다. 속성은 대/소문자를 구분하지 않습니다.

속성	기본값	설명
AuthMech	필수	인증 메커니즘에서 3은 메커니즘이 Azure Databricks 개인용 액세스 토큰이며 11은 메커니즘이 OAuth 2.0 토큰임을 지정합니다. 각 메커니즘에 추가 속성이 필요합니다. 드라이버 인증을 참조하세요.
Auth_Flow	0	드라이버 연결에 대한 OAuth2 인증 흐름입니다. AuthMech가 11인 경우 이 속성은 필수입니다.
SSL	1	커넥터가 SSL 사용 소켓을 통해 Spark 서버와 통신하는지 여부입니다.
ConnCatalog 또는 catalog	SPARK	사용할 기본 카탈로그의 이름입니다.
ConnSchema 또는 schema	default	사용할 기본 스키마의 이름입니다. URL의 <schema>를 사용할 스키마 이름으로 바꾸거나 ConnSchema 속성을 사용할 스키마 이름으로 설정하여 지정할 수 있습니다.
ProxyAuth	0	1로 설정하면 드라이버가 프록시 인증 사용자 및 암호(ProxyUID 및 ProxyPwd로 표시됨)를 사용합니다.
ProxyHost	null	UseProxy가 1로 설정된 경우 사용할 프록시 호스트의 이름을 나타내는 문자열입니다.
ProxyPort	null	UseProxy가 1로 설정된 경우 사용할 프록시 포트의 수를 나타내는 정수입니다.
ProxyUID	null	ProxyAuth 및 UseProxy가 1로 설정된 경우 프록시 인증에 사용할 사용자 이름을 나타내는 문자열입니다.
ProxyPwd	null	ProxyAuth 및 UseProxy가 1로 설정된 경우 프록시 인증에 사용할 비밀번호를 나타내는 문자열입니다.
UseProxy	0	1로 설정된 경우 드라이버는 제공된 프록시 설정(예: ProxyAuth, ProxyHost, ProxyPort, ProxyPwd, ProxyUID)을 사용합니다.
UseSystemProxy	0	1로 설정된 경우 드라이버는 시스템 수준에서 설정된 프록시 설정을 사용합니다. 연결 URL에 추가 프록시 속성이 설정된 경우 이러한 추가 프록시 속성은 시스템 수준에서 설정된 속성을 재정의합니다.
UseCFProxy	0	1로 설정된 드라이버는 제공된 경우 클라우드 페치 프록시 설정을 사용하며, 그렇지 않으면 일반 프록시를 사용합니다.
CFProxyAuth	0	1로 설정하면 드라이버가 프록시 인증 사용자 및 암호(CFProxyUID 및 CFProxyPwd로 표시됨)를 사용합니다.
CFProxyHost	null	UseCFProxy가 1로 설정된 경우 사용할 프록시 호스트의 이름을 나타내는 문자열입니다.
CFProxyPort	null	UseCFProxy가 1로 설정된 경우 사용할 프록시 포트의 수를 나타내는 정수입니다.
CFProxyUID	null	CFProxyAuth 및 UseCFProxy가 1로 설정된 경우 프록시 인증에 사용할 사용자 이름을 나타내는 문자열입니다.
CFProxyPwd	null	CFProxyAuth 및 UseCFProxy가 1로 설정된 경우 프록시 인증에 사용할 비밀번호를 나타내는 문자열입니다.
AsyncExecPollInterval	200	비동기 쿼리 실행 상태에 대한 각 폴링 사이의 시간(밀리초)입니다. 비동기는 Spark에 대해 쿼리를 실행하는 데 사용되는 RPC 호출이 비동기적이라는 사실을 나타냅니다. JDBC 비동기 작업이 지원된다는 의미는 아닙니다.
UserAgentEntry	browser	HTTP 요청에 포함할 사용자 에이전트 항목입니다. 이 값의 형식은 [ProductName]/[ProductVersion] [Comment]입니다.
UseThriftClient	0	JDBC 드라이버가 Thrift 클라이언트를 사용하여 다목적 클러스터에 연결해야 하는지 여부입니다. SQL 웨어하우스의 경우 기본값을 적용합니다.

SQL 구성 속성

JDBC 드라이버에서 지원하는 SQL 구성 속성은 다음과 같습니다. 구성 매개 변수에도 설명되어 있습니다. 속성은 대/소문자를 구분하지 않습니다.

속성	기본값	설명
ansi_mode	TRUE	특정 함수 및 캐스팅 규칙에 대해 엄격한 ANSI SQL 동작을 사용하도록 설정할지 여부입니다.
enable_photo	TRUE	Photon 벡터화된 쿼리 엔진을 사용하도록 설정할지 여부입니다.
legacy_time_parser_policy	EXCEPTION	날짜 및 타임스탬프를 구문 분석하고 서식을 지정하는 데 사용되는 메서드입니다. 유효한 값은 EXCEPTION, LEGACY 및 CORRECTED입니다.
max_file_partition_bytes	128m	파일 기반 원본에서 읽을 때 단일 파티션으로 압축할 최대 바이트 수입니다. 설정은 양수 정수일 수 있으며 선택적으로 b(바이트), k 또는 kb(1024바이트) 등과 같은 측정값을 포함할 수 있습니다.
read_only_external_metastore	false	외부 메타스토어가 읽기 전용으로 처리되는지 여부를 제어합니다.
statement_timeout	172800	SQL 문 시간 제한을 0에서 172800초 사이로 설정합니다.
timezone	UTC	로컬 표준 시간대를 선택합니다. area/city 형식의 지역 ID(America/Los_Angeles 또는 형식(+|-)HH, (+|-)HH:mm 또는 (+|-)HH:mm:ss(예: -08, +01:00 또는 -13:33:33)의 영역 오프셋 등) 또한 UTC는 +00:00에 대한 별칭으로 지원됩니다.
use_cached_result	true	가능한 모든 상황에서 Databricks SQL이 결과를 캐시하여 재사용하는지 여부입니다.

로깅 속성

JDBC 드라이버에서 지원되는 로깅 속성은 다음과 같습니다. 속성은 대/소문자를 구분하지 않습니다.

속성	기본값	설명
LogLevel	OFF	0에서 6까지의 값인 로깅 수준입니다. - 0: 모든 로깅을 사용하지 않도록 설정합니다. - 1: FATAL 수준에서 로깅을 사용하도록 설정하면 커넥터가 중단될 매우 심각한 오류 이벤트를 기록합니다. - 2: ERROR 수준에서 로깅을 사용하도록 설정하면 커넥터가 계속 실행될 수 있는 오류 이벤트를 기록합니다. - 3: WARNING 수준에서 로깅을 사용하도록 설정하면 작업이 수행되지 않을 경우 오류가 발생할 수 있는 이벤트를 기록합니다. - 4: INFO 수준에서 로깅을 사용하도록 설정하여 커넥터의 진행률을 설명하는 일반 정보를 기록합니다. - 5: DEBUG 수준에서 로깅을 사용하도록 설정하면 커넥터 디버깅에 유용한 자세한 정보를 기록합니다. - 6: TRACE 수준에서 로깅을 사용하도록 설정하면 모든 커넥터 작업을 기록합니다. 커넥터에서 로깅을 사용하거나 사용하지 않도록 설정하고 로그 파일에 포함된 세부 정보를 지정하려면 이 속성을 사용합니다.
LogPath	로그의 기본 경로를 확인하기 위해 드라이버는 다음 우선 순위 순서로 이러한 시스템 속성에 대해 설정된 값을 사용합니다. 1. user.dir 2. java.io.tmpdir 3. 현재 디렉터리, 즉 .	로깅을 사용할 때 커넥터가 로그 파일을 문자열로 저장하는 폴더의 전체 경로입니다. 연결 URL이 모든 JDBC 애플리케이션과 호환되도록 하려면 다른 백슬래시를 입력하여 파일 경로에서 백슬래시(\)를 이스케이프합니다. 값이 LogPath 잘못된 경우 커넥터는 기록된 정보를 표준 출력 스트림(System.out)으로 보냅니다.
LogFileSize	최대 금액 한도 없음	허용되는 최대 로그 파일 크기(MB)입니다.
LogFileCount	최대 금액 한도 없음	허용되는 최대 로그 파일 수

로깅 사용 및 구성

JDBC 드라이버는 SLF4J(Java용 단순 로깅 외관) 및 JUL(java.util.logging) 프레임워크를 지원합니다. 드라이버는 기본적으로 JUL 로깅 프레임워크를 사용합니다.

JDBC 드라이버에 대한 로깅을 사용하도록 설정하고 구성하려면 다음을 수행합니다.

1. 사용하려는 로깅 프레임워크를 사용하도록 설정합니다.

   • SLF4J 로깅의 경우 시스템 속성을 -Dcom.databricks.jdbc.loggerImpl=SLF4JLOGGER 설정하고 SLF4J 바인딩 구현(SLF4J 버전 2.0.13 이상과 호환됨) 및 해당 구성 파일을 클래스 경로에 제공합니다.
   • JUL 로깅의 경우 시스템 속성을 -Dcom.databricks.jdbc.loggerImpl=JDKLOGGER설정합니다. 기본값입니다.

2. LogLevel 연결 문자열 속성을 로그 파일에 포함할 원하는 정보 수준으로 설정합니다.

3. LogPath 연결 문자열 속성을 로그 파일을 저장할 폴더의 전체 경로로 설정합니다.

   예를 들어 다음 연결 URL은 로깅 수준 6을 사용하도록 설정하고 로그 파일을 C:temp 폴더에 저장합니다.

   jdbc: databricks://localhost:11000;LogLevel=6;LogPath=C:\\temp
   

4. JDBC 애플리케이션을 다시 시작하고 서버에 다시 연결하여 설정을 적용합니다.

예: JDBC 드라이버를 사용하여 쿼리 실행

다음 예제에서는 JDBC 드라이버를 사용하여 Azure Databricks 컴퓨팅 리소스에서 Databricks SQL 쿼리를 실행하는 방법을 보여줍니다.

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.ResultSet;
import java.sql.ResultSetMetaData;
import java.sql.Statement;
import java.util.Properties;

public class DatabricksJDBCExample {

    public static void main(String[] args) {

        Class.forName("com.databricks.client.jdbc.Driver");

        // Set JDBC URL properties
        String jdbcUrl = "jdbc:databricks://dbc-a1b2345c-d6e7.cloud.databricks.com:443";
        Properties connectionProperties = new Properties();
        connectionProperties.put("httpPath", "sql/protocolv1/o/123456780012345/0123-123450-z000pi22");
        connectionProperties.put("ssl", "1");

        // Set authentication properties (personal access token)
        connectionProperties.put("AuthMech", "3");
        connectionProperties.put("user", "token");
        connectionProperties.put("password", "12345678901234667890abcdabcd");

        // Set logging properties
        connectionProperties.put("logPath", "logs/myapplication.log");

        // Establish connection and execute query
        try (Connection connection = DriverManager.getConnection(jdbcUrl, connectionProperties);
             Statement statement = connection.createStatement();
             ResultSet resultSet = statement.executeQuery("SELECT * FROM samples.nyctaxi.trips")) {

            // Get metadata and column names
            ResultSetMetaData metaData = resultSet.getMetaData();
            String[] columns = new String[metaData.getColumnCount()];
            for (int i = 0; i < columns.length; i++) {
                columns[i] = metaData.getColumnName(i + 1);
            }

            // Process and print the result set
            while (resultSet.next()) {
                System.out.print("Row " + resultSet.getRow() + "=[");
                for (int i = 0; i < columns.length; i++) {
                    if (i != 0) {
                        System.out.print(", ");
                    }
                    System.out.print(columns[i] + "='" + resultSet.getObject(i + 1) + "'");
                }
                System.out.println("]");
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
    }
}

추가 리소스

• Azure Databricks와 DataGrip 통합

• Azure Databricks와 DBeaver 통합

• SQL Workbench/J에 연결

• Infoworks에 연결

• Qlik Replicate에 연결

• StreamSets에 연결

• Syncsort에 연결

• MicroStrategy에 연결