Databricks JDBC 드라이버(OSS)

아티클
09/25/2024

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에서 지원됩니다.

드라이버 설치

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

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

Maven 프로젝트의 경우 프로젝트의 pom.xml 파일에 다음 종속성을 추가하여 Maven에 지정된 버전으로 JDBC 드라이버를 자동으로 다운로드하도록 지시합니다.
```
<dependency>
  <groupId>com.databricks</groupId>
  <artifactId>databricks-jdbc</artifactId>
  <version>0.9.1-oss</version>
  <scope>runtime</scope>
</dependency>
```
Gradle 프로젝트의 경우 프로젝트의 빌드 파일에 다음 종속성을 추가하여 Gradle에 지정된 버전으로 JDBC 드라이버를 자동으로 다운로드하도록 지시합니다.
```
implementation 'com.databricks:databricks-jdbc:0.9.1-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을 얻으려면 다음을 수행합니다.

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

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

Azure Databricks 작업 영역으로 로그인합니다.
사이드바에서 SQL 웨어하우스를 클릭한 다음 대상 웨어하우스의 이름을 클릭합니다.
연결 세부 정보 탭을 클릭합니다.
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 클라이언트 자격 증명 인증을 구성하려면 다음을 수행합니다.

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

Important

Databricks JDBC 드라이버(OSS)는 OAuth M2M 또는 OAuth 2.0 클라이언트 자격 증명 인증에 대한 Azure Databricks OAuth 비밀을 지원합니다. Microsoft Entra ID 비밀은 지원되지 않습니다.
서비스 주체에 대한 Azure Databricks OAuth 비밀을 만듭니다. 이렇게 하려면 OAuth M2M 인증을 위한 액세스 토큰 수동 생성 및 사용을 참조하세요.
서비스 주체에게 클러스터 또는 웨어하우스에 대한 액세스 권한을 부여합니다. 컴퓨팅 사용 권한 또는 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`	`4`	0에서 6까지의 값인 로깅 수준입니다. - 0: 모든 로깅을 사용하지 않도록 설정합니다. - 1: FATAL 수준에서 로깅을 사용하도록 설정하면 커넥터가 중단될 매우 심각한 오류 이벤트를 기록합니다. - 2: ERROR 수준에서 로깅을 사용하도록 설정하면 커넥터가 계속 실행될 수 있는 오류 이벤트를 기록합니다. - 3: WARNING 수준에서 로깅을 사용하도록 설정하면 작업이 수행되지 않을 경우 오류가 발생할 수 있는 이벤트를 기록합니다. - 4: INFO 수준에서 로깅을 사용하도록 설정하여 커넥터의 진행률을 설명하는 일반 정보를 기록합니다. - 5: DEBUG 수준에서 로깅을 사용하도록 설정하면 커넥터 디버깅에 유용한 자세한 정보를 기록합니다. - 6: TRACE 수준에서 로깅을 사용하도록 설정하면 모든 커넥터 작업을 기록합니다. 커넥터에서 로깅을 사용하거나 사용하지 않도록 설정하고 로그 파일에 포함된 세부 정보를 지정하려면 이 속성을 사용합니다.
`LogPath`	`logs/application.log`	로깅을 사용할 때 커넥터가 로그 파일을 문자열로 저장하는 폴더의 전체 경로입니다. `LogPath` 값이 잘못된 경우 커넥터는 기록된 정보를 표준 출력 스트림(System.out)으로 보냅니다.

예: 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();
        }
    }
}

다음을 통해 공유