JDBC 연결

Azure Databricks는 JDBC를 사용하여 외부 데이터베이스에 연결할 수 있도록 지원합니다. JDBC Unity 카탈로그 연결을 사용하여 Spark 데이터 원본 API 또는 Azure Databricks 원격 쿼리 SQL API를 사용하여 데이터 원본을 읽고 쓸 수 있습니다. JDBC 연결은 외부 데이터베이스에 액세스하기 위한 JDBC 드라이버, URL 경로 및 자격 증명을 지정하는 Unity 카탈로그의 보안 개체입니다. JDBC 연결은 서버리스, 표준 클러스터, 전용 클러스터 및 Databricks SQL을 비롯한 Unity 카탈로그 컴퓨팅 유형에서 지원됩니다.

JDBC 연결 사용의 이점

• Spark 데이터 원본 API와 함께 JDBC를 사용하여 데이터 원본을 읽고 씁니다.
• 원격 쿼리 SQL API를 사용하여 JDBC를 사용하여 데이터 원본에서 읽습니다.
• Unity 카탈로그 연결을 사용하여 데이터 원본에 대한 액세스를 제어합니다.
• 연결을 한 번 만들고 모든 Unity 카탈로그 컴퓨팅에서 다시 사용합니다.
• Spark 및 컴퓨팅 업그레이드에 대해 안정적입니다.
• 연결 자격 증명은 쿼리 사용자로부터 숨겨집니다.

JDBC와 쿼리 페더레이션 비교

JDBC는 쿼리 페더레이션을 보완합니다. Databricks는 다음과 같은 이유로 쿼리 페더레이션을 선택하는 것이 좋습니다.

• 쿼리 페더레이션은 외세 카탈로그를 사용하여 테이블 수준에서 세분화된 액세스 제어 및 거버넌스를 제공합니다. JDBC Unity 카탈로그 연결은 연결 수준에서만 거버넌스를 제공합니다.
• 쿼리 페더레이션은 최적의 쿼리 성능을 위해 Spark 쿼리를 푸시다운합니다.

그러나 다음 시나리오에서 JDBC Unity 카탈로그 연결을 사용하도록 선택합니다.

• 데이터베이스는 쿼리 페더레이션에서 지원되지 않습니다.
• 특정 JDBC 드라이버를 사용하려고 합니다.
• Spark를 사용하여 데이터 원본에 작성해야 합니다(쿼리 페더레이션은 쓰기를 지원하지 않음).
• Spark 데이터 원본 API 옵션을 통해 더 많은 유연성, 성능 및 병렬 처리 제어가 필요합니다.
• Spark query 옵션을 사용하여 원본 SQL 쿼리를 푸시다운하려고 합니다.

JDBC와 PySpark 데이터 원본을 사용하는 이유는 무엇인가요?

PySpark 데이터 원본은 JDBC Spark 데이터 원본의 대안입니다.

JDBC 연결을 사용합니다.

• 기본 제공 Spark JDBC 지원을 사용하려는 경우
• 이미 있는 기본 JDBC 드라이버를 사용하려는 경우
• 연결 수준에서 Unity 카탈로그 거버넌스가 필요한 경우
• 모든 Unity 카탈로그 컴퓨팅 유형(서버리스, 표준, 전용, SQL API)에서 연결하려는 경우
• Python, Scala 및 SQL API와의 연결을 사용하려는 경우

PySpark 데이터 원본을 사용합니다.

• Python을 사용하여 Spark 데이터 원본 또는 데이터 싱크를 유연하게 개발하고 디자인하려는 경우
• 노트북이나 PySpark 워크로드에서만 사용하는 경우
• 사용자 지정 분할 논리를 구현하려는 경우

JDBC 또는 PySpark 데이터 원본은 작업 순서를 선택하는 데 도움이 되는 통계를 쿼리 최적화 도구에 노출하지 않습니다.

작동 방식

JDBC 연결을 사용하여 데이터 원본에 연결하려면 Spark 컴퓨팅에 JDBC 드라이버를 설치합니다. 이 연결을 통해 Spark 컴퓨팅에서 액세스할 수 있는 격리된 샌드박스에 JDBC 드라이버를 지정하고 설치하여 Spark 보안 및 Unity 카탈로그 거버넌스를 보장할 수 있습니다. 샌드박싱에 대한 자세한 내용은 Databricks에서 사용자 격리를 적용하는 방법을 참조하세요.

시작하기 전 주의 사항:

서버리스 및 표준 클러스터에서 Spark 데이터 원본 API와 JDBC 연결을 사용하려면 먼저 다음 요구 사항을 충족해야 합니다.

작업 영역 요구 사항:

• Unity 카탈로그에 사용하도록 설정된 Azure Databricks 작업 영역

컴퓨팅 요구 사항:

• 컴퓨팅 리소스에서 대상 데이터베이스 시스템으로의 네트워크 연결 네트워크 연결을 참조하세요.
• Azure Databricks 컴퓨팅은 표준 모드 또는 전용 액세스 모드에서 서버리스 또는 Databricks Runtime 17.3 LTS 이상을 사용해야 합니다.
• SQL 웨어하우스는 프로 또는 서버리스여야 하며 2025.35 이상을 사용해야 합니다.

권한 필요:

• 연결을 만들려면 작업 영역에 연결된 메타스토어에 대한 권한이 있어야 합니다 CREATE CONNECTION .
• CREATE 또는 MANAGE 연결 작성자가 Unity 카탈로그 볼륨에 액세스합니다.
• 연결을 쿼리하는 사용자에 의한 볼륨 액세스입니다.
• 추가 사용 권한은 다음 각 작업 기반 섹션에서 지정됩니다.

인증 방법

1단계: 볼륨 만들기 및 JDBC JAR 설치

JDBC 연결은 Unity 카탈로그 볼륨에서 JDBC 드라이버 JAR을 읽고 설치합니다.

1. 기존 볼륨에 대한 쓰기 및 읽기 권한이 없는 경우 새 볼륨을 만듭니다.

   CREATE VOLUME IF NOT EXISTS my_catalog.my_schema.my_volume_JARs
   

2. 볼륨에 JDBC 드라이버 JAR을 업로드 합니다.

3. 연결을 쿼리하는 사용자에게 볼륨에 대한 읽기 액세스 권한을 부여합니다.

   GRANT READ VOLUME ON VOLUME my_catalog.my_schema.my_volume_JARs TO `account users`
   

2단계: JDBC 연결 만들기

JDBC 연결은 Unity 카탈로그의 보안 개체입니다. JDBC 드라이버, URL 경로, 외부 데이터베이스 시스템에 액세스하기 위한 자격 증명 및 쿼리 사용자가 지정할 수 있는 허용 목록 옵션을 지정합니다. 연결을 만들려면 Azure Databricks Notebook 또는 CREATE CONNECTION Databricks SQL 쿼리 편집기에서 카탈로그 탐색기 또는 SQL 명령을 사용합니다. 지원되는 인증 방법에 대한 인증 방법을 참조하세요.

필요한 권한: 메타스토어 관리자 또는 CREATE CONNECTION 권한이 있는 사용자.

연결을 만들기 전에 다음 사항에 유의하세요.

• URL 및 자격 증명만 필요한 옵션입니다. 로그 또는 오류가 노출될 수 있으므로 URL에 자격 증명을 포함하지 마세요. 선택한 인증 방법에 전용 자격 증명 옵션을 사용합니다.
• 사용자가 쿼리 시 지정할 수 있는 Spark 데이터 원본 옵션을 제어하는 데 사용합니다 externalOptionsAllowList . 지정하지 않으면 기본값은 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'. 사용자를 연결에 정의된 옵션으로만 제한하려면 빈 문자열로 설정합니다. 사용자는 url 또는 host를 절대 지정할 수 없습니다.

카탈로그 탐색기

1. Azure Databricks 작업 영역에서 을 클릭합니다.카탈로그.

2. 을 클릭합니다.연결한 다음 연결을 클릭합니다.

3. 을 클릭하여 연결을 만듭니다.

4. 연결 설정 마법사의 연결 기본 페이지에서 사용자에게 친숙한 연결 이름를 입력합니다.

5. 연결 형식의 경우 JDBC를 선택합니다.

6. (선택 사항) 주석을 입력합니다.

7. 다음을 클릭합니다.

8. 연결 세부 정보 페이지에서 다음 연결 속성을 입력합니다.

   재산	Description
   Url	데이터베이스에 대한 JDBC URL 형식 jdbc:subprotocol:subname (예: jdbc:oracle:thin:@<host>:<port>:<SID>)입니다.
   Java 종속성	Unity 카탈로그 볼륨의 JDBC 드라이버 JAR 파일입니다. JAR 종속성 추가를 클릭하여 각 JAR(예: /Volumes/<catalog>/<schema>/<volume_name>/ojdbc11.jar)을 추가합니다.
   외부 옵션 허용 목록	쿼리할 때 사용자가 지정할 수 있는 Spark 데이터 원본 옵션 의 쉼표로 구분된 목록입니다. 기본값은 dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions입니다. 사용자를 연결에 정의된 옵션으로만 제한하려면 빈 값으로 설정합니다.
   추가 옵션	임의의 JDBC 드라이버 옵션이 키-값 쌍으로 드라이버에 전달됩니다. 이 섹션을 사용하여 데이터베이스 자격 증명(예: 키 user 및 키 password) 및 기타 드라이버 관련 속성을 설정할 수 있습니다. 필요에 따라 UI 와 JSON 입력 모드 간에 전환합니다.

9. 을 클릭하여 연결을 만듭니다.

SQL

CREATE CONNECTION SQL 명령을 노트북 또는 Databricks SQL 쿼리 편집기에서 사용하세요.

DROP CONNECTION IF EXISTS <JDBC-connection-name>;

CREATE CONNECTION <JDBC-connection-name> TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/<catalog>/<Schema>/<volume_name>/JDBC_DRIVER_JAR_NAME.jar"]'
)
OPTIONS (
  url 'jdbc:<database_URL_host_port>',
  user '<user>',
  password '<password>',
  externalOptionsAllowList 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'
);

DESCRIBE CONNECTION <JDBC-connection-name>;

CREATE CONNECTION oracle_connection TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/my_catalog/my_schema/my_volume_JARs/ojdbc11.jar"]'
)
OPTIONS (
  url 'jdbc:oracle:thin:@<host>:<port>:<SID>',
  user '<oracle_user>',
  password '<oracle_password>',
  externalOptionsAllowList 'dbtable,query'
);

CREATE CONNECTION <JDBC-connection-name> TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/<catalog>/<schema>/<volume_name>/JDBC_DRIVER_JAR_NAME.jar"]'
)
OPTIONS (
  url 'jdbc:<database_URL_host_port>',
  client_id '<client-id>',
  client_secret '<client-secret>',
  oauth_scope '<scope>',
  token_endpoint '<https://authorization-server.com/oauth/token>',
  oauth_credential_exchange_method 'header_and_body',
  jdbc_token_parameter_name '<driver-token-parameter-name>',
  externalOptionsAllowList 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'
);

CREATE CONNECTION postgres_oauth_connection TYPE JDBC
ENVIRONMENT (
  java_dependencies '["/Volumes/my_catalog/my_schema/my_volume_JARs/postgresql-42.7.3.jar"]'
)
OPTIONS (
  url 'jdbc:postgresql://<host>:<port>/<database>?sslmode=require',
  client_id '<client-id>',
  client_secret '<client-secret>',
  oauth_scope '<scope>',
  token_endpoint 'https://authorization-server.com/oauth/token',
  oauth_credential_exchange_method 'header_and_body',
  jdbc_token_parameter_name 'password',
  externalOptionsAllowList 'dbtable,query'
);

연결 소유자 또는 관리자는 JDBC 드라이버에서 지원하는 추가 옵션을 연결에 추가할 수 있습니다. 보안상의 이유로 연결에 정의된 옵션은 쿼리 시 재정의할 수 없습니다.

3단계: 권한 부여 USE

사용자에게 USE에 대한 연결 권한을 부여합니다.

GRANT USE CONNECTION ON CONNECTION <connection-name> TO <user-name>;

기존 연결을 관리하는 방법에 대한 자세한 내용은 Lakehouse Federation대한 연결 관리를 참조하세요.

4단계: 데이터 원본 쿼리

권한이 있는 USE CONNECTION 사용자는 Spark 또는 원격 쿼리 SQL API를 통해 JDBC 연결을 사용하여 데이터 원본을 쿼리할 수 있습니다. 사용자는 JDBC 드라이버에서 지원되고 JDBC 연결에 externalOptionsAllowList 지정된 Spark 데이터 원본 옵션을 추가할 수 있습니다(예: 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions'이 경우). 허용되는 옵션을 보려면 다음 쿼리를 실행합니다.

DESCRIBE CONNECTION <JDBC-connection-name>;

파이썬

df = (
  spark.read.format('jdbc')
  .option('databricks.connection', '<JDBC-connection-name>')
  .option('query', 'select * from <table_name>') # query in source SQL language - Option specified by querying user
  .load()
)

df.display()

SQL

SELECT * FROM
remote_query('<JDBC-connection-name>', query => 'SELECT * FROM <table>'); -- query in source SQL language - Option specified by querying user

Migration

기존 Spark 데이터 원본 API 워크로드에서 마이그레이션하려면 Databricks에서 다음을 수행하는 것이 좋습니다.

• Spark 데이터 원본 API의 옵션에서 URL 및 자격 증명을 제거합니다.
• databricks.connection Spark 데이터 원본 API의 옵션에 추가합니다.
• 해당 URL 및 자격 증명을 사용하여 JDBC 연결을 만듭니다.
• 연결에서 정적이어야 하며 사용자를 쿼리하여 지정해서는 안 되는 옵션을 지정합니다.
• 연결 externalOptionsAllowList에서 Spark 데이터 원본 API 코드(예 'dbtable,query,partitionColumn,lowerBound,upperBound,numPartitions': )의 쿼리 시간에 사용자가 조정하거나 수정해야 하는 데이터 원본 옵션을 지정합니다.

제한점

Spark 데이터 원본 API

• URL 및 호스트는 Spark 데이터 원본 API에 포함할 수 없습니다.
• .option("databricks.connection", "<Connection_name>")은 필수입니다.
• 연결에 정의된 옵션은 쿼리 시 코드의 데이터 원본 API에서 사용할 수 없습니다.
• externalOptionsAllowList에 지정된 옵션만 사용자 쿼리에 사용할 수 있습니다.
• JDBC 드라이버의 메모리 제한은 400MiB입니다. 제한에 도달하면 더 fetchSize 작은 값을 사용하는 것이 좋습니다.

Support

• Spark 데이터 원본은 지원되지 않습니다.
• Lakeflow Spark 선언적 파이프라인은 지원되지 않습니다.
• 생성 시 연결 종속성: java_dependencies JDBC 드라이버 JAR에 대한 볼륨 위치만 지원합니다.
• 쿼리 시 연결 종속성: 연결 사용자는 JDBC 드라이버 JAR이 있는 볼륨에 액세스해야 합니다 READ .
• 전용 액세스 모드(이전의 단일 사용자 액세스 모드)에서는 이를 사용하려면 연결의 소유자 또는 관리자여야 합니다.
• SSL 인증서는 지원되지 않습니다.
• 외부 카탈로그는 JDBC 연결에서 지원되지 않습니다.

Authentication

• 이 커넥터는 정적 자격 증명 및 OAuth 컴퓨터 간을 지원합니다. Unity 카탈로그 자격 증명 또는 서비스 자격 증명을 지원하지 않습니다.

Networking

• 대상 데이터베이스 시스템과 Azure Databricks 작업 영역은 동일한 VNet에 있을 수 없습니다.

네트워크 연결

컴퓨팅 리소스에서 대상 데이터베이스 시스템으로의 네트워크 연결이 필요합니다. Lakehouse 페더레이션에 대한 네트워킹 권장 사항을 참조하여 일반적인 네트워킹 지침을 확인하세요.

클래식 컴퓨팅: 표준 및 전용 클러스터

Azure Databricks VNet은 Spark 클러스터만 허용하도록 구성됩니다. 다른 인프라에 연결하려면 대상 데이터베이스 시스템을 다른 VNet에 배치하고 VNet 피어링을 사용합니다. VNet 피어링이 설정되면 클러스터 또는 웨어하우스에서 connectionTest UDF와의 연결을 확인합니다.

Azure Databricks 작업 영역 및 대상 데이터베이스 시스템이 동일한 VNet에 있는 경우 Databricks는 다음 중 하나를 권장합니다.

• 서버리스 컴퓨팅을 사용합니다.
• 포트 80 및 443을 통해 TCP 및 UDP 트래픽을 허용하도록 대상 데이터베이스를 구성하고 연결에서 이러한 포트를 지정합니다.

Serverless

서버리스 컴퓨팅에서 JDBC 연결을 사용하는 경우 안정적인 IP 에 대한 서버리스 컴퓨팅 액세스에 대한 방화벽을 구성 하거나 프라이빗 연결을 구성합니다.

연결 테스트

Azure Databricks 컴퓨팅과 데이터베이스 시스템 간의 연결을 테스트하려면 다음 UDF를 사용합니다.

CREATE OR REPLACE TEMPORARY FUNCTION connectionTest(host string, port string) RETURNS string LANGUAGE PYTHON AS $$
import subprocess
try:
    command = ['nc', '-zv', host, str(port)]
    result = subprocess.run(command, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
    return str(result.returncode) + "|" + result.stdout.decode() + result.stderr.decode()
except Exception as e:
    return str(e)
$$;

SELECT connectionTest('<database-host>', '<database-port>');

FAQ

다음은 JDBC 연결에 대한 조건자 푸시다운 동작에 대한 질문과 대답입니다.

JDBC는 조건자 푸시다운을 지원하나요?

예. 필터는 Spark 데이터 원본 API(format('jdbc')) 및 SQL 함수 모두에 대해 기본적으로 원격 데이터베이스로 remote_query푸시다운됩니다. 푸시할 수 있는 조건자는 JDBC 드라이버 및 방언에 따라 달라지므로, 쿼리에서 EXPLAIN를 실행하고 물리 실행 계획을 검사하여 어떤 필터가 원본 소스로 푸시되는지 확인하세요. remote_query SQL 함수의 경우 pushdown.filters.enabled와 같은 옵션으로 특정 푸시다운(필터, 제한값, 오프셋 및 집계)을 제어할 수 있으며, 이들 옵션은 모두 기본적으로 활성화되어 있습니다.

조건자 푸시다운은 테이블 통계를 쿼리 최적화 관리자에 노출하는 경우와 다릅니다. JDBC 및 PySpark 데이터 원본은 조건자가 푸시다운되는지 여부에 관계없이 작업 순서를 선택할 수 있도록 쿼리 최적화 프로그램에서 통계를 노출하지 않습니다.