Azure Databricks와 함께 SQLAlchemy 사용

Azure Databricks는 Azure Databricks에 대한 SQLAlchemy언어(SQLAlchemy가 다양한 유형의 데이터베이스 API 구현 및 데이터베이스와 통신하는 데 사용하는 시스템)를 제공합니다. SQLAlchemy는 Python SQL 도구 키트 및 ORM(개체 관계형 매퍼)입니다. SQLAlchemy는 간단하고 Pythonic 도메인 언어로 조정된 효율적이고 고성능의 데이터베이스 액세스를 위해 설계된 잘 알려진 엔터프라이즈 수준 지속성 패턴 제품군을 제공합니다. 기능 및 철학을 참조하세요.

Azure Databricks에서 SQLAlchemy 기능을 사용하려면 Azure Databricks에 대한 SQLAlchemy 언어를 설치해야 합니다. 이 문서에서는 Python용 Databricks SQL Connector 버전 4.0.0 이상을 기반으로 하는 Azure Databricks 버전 1.0 및 2.0에 대한 SQLAlchemy 방언에 대해 설명합니다.

요구 사항

Python >=3.8 및 <=3.11을 실행하는 개발 컴퓨터
Databricks는 Python에 포함된 venv에서 제공하는 환경과 같은 Python 가상 환경을 사용하는 것이 좋습니다. 가상 환경은 올바른 버전의 Python과 Python용 Databricks SQL 커넥터를 함께 사용하는 데 도움이 됩니다. 가상 환경 설정 및 사용은 이 문서의 범위를 벗어납니다. 자세한 내용은 가상 환경 만들기를 참조하세요.
기존 클러스터 또는 SQL 웨어하우스.

시작

SQLAlchemy v1용 databricks-sqlalchemy를 설치하려면 pip install databricks-sqlalchemy~=1.0을 사용하고, SQLAlchemy v2용은 pip install databricks-sqlalchemy을 사용하여 설치합니다. 버전 정보에 대해서는 databricks-sqlalchemy 릴리스 기록을 참조하세요.
사용하려는 클러스터 또는 SQL 웨어하우스에 대해 다음 정보를 수집합니다.

클러스터
- 클러스터의 서버 호스트 이름. 클러스터의 탭에서 > 값을 확인할 수 있습니다.
- 클러스터의 HTTP 경로. 클러스터에 대한 탭의 > 값에서 이를 얻을 수 있습니다.
SQL 웨어하우스
- SQL 웨어하우스의 서버 호스트 이름. 서버 호스트 이름 값은 SQL 웨어하우스의 연결 세부 정보 탭에서 얻을 수 있습니다.
- SQL 웨어하우스의 HTTP 경로. SQL 웨어하우스의 연결 세부 사항 탭에서 HTTP 경로 값을 얻을 수 있습니다.

인증

Azure Databricks용 SQLAlchemy 다이얼렉트는 Python용 Databricks SQL Connector를 사용해 연결하고, connect_args의 값을 커넥터에 전달합니다. 다음과 같은 인증 유형을 지원합니다:

개인 액세스 토큰 인증
OAuth 사용자-기계 간(U2M) 인증
OAuth M2M(컴퓨터 대 컴퓨터) 인증

개인 액세스 토큰 인증

Azure Databricks 개인용 액세스 토큰을 만들려면 작업 영역 사용자를 위한 개인용 액세스 토큰 만들기의 단계를 따릅니다.

SQLAlchemy 언어를 인증하려면 다음 코드 조각을 사용합니다. 이 코드 조각에서는 다음 환경 변수를 설정한다고 가정합니다.

DATABRICKS_TOKEN을 Azure Databricks 개인 액세스 토큰으로 설정합니다.
DATABRICKS_SERVER_HOSTNAME클러스터나 SQL 웨어하우스에 대한 서버 호스트 이름 값으로 설정됩니다.
DATABRICKS_HTTP_PATH을(를) 로 설정하여 클러스터 또는 SQL 웨어하우스의 HTTP 경로 값을 지정합니다.
DATABRICKS_CATALOG을/를 Unity 카탈로그의 대상 카탈로그로 설정합니다.
DATABRICKS_SCHEMA는 Unity 카탈로그에서 대상 스키마(데이터베이스라고도 함)로 설정됩니다.

환경 변수를 설정하려면 운영 체제 설명서를 참조하세요.

import os
from sqlalchemy import create_engine

access_token    = os.getenv("DATABRICKS_TOKEN")
server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")
http_path       = os.getenv("DATABRICKS_HTTP_PATH")
catalog         = os.getenv("DATABRICKS_CATALOG")
schema          = os.getenv("DATABRICKS_SCHEMA")

engine = create_engine(
  url = f"databricks://token:{access_token}@{server_hostname}?" +
        f"http_path={http_path}&catalog={catalog}&schema={schema}"
)

# ...

이전 engine 변수를 사용하여 Azure Databricks 컴퓨팅 리소스를 통해 지정된 카탈로그 및 스키마에 연결합니다.

OAuth 사용자와 기계 간(U2M) 인증

OAuth U2M 인증은 사용자의 실시간 로그인과 동의를 통해 대상 Azure Databricks 사용자 계정을 인증합니다. 각 클라우드에서 이를 지원하는 Databricks SQL Connector for Python 버전에 대해서는 OAuth 사용자 대 기계(U2M) 인증을 참조하세요.

OAuth U2M으로 SQLAlchemy dialect를 인증하려면 다음 코드 스니펫을 사용하세요. 이 스니펫은 DATABRICKS_SERVER_HOSTNAME에 설명된 대로 , DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG, DATABRICKS_SCHEMA 환경 변수를 설정했다고 가정합니다.

import os
from sqlalchemy import create_engine

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")
http_path       = os.getenv("DATABRICKS_HTTP_PATH")
catalog         = os.getenv("DATABRICKS_CATALOG")
schema          = os.getenv("DATABRICKS_SCHEMA")

engine = create_engine(
  url = f"databricks://{server_hostname}?" +
        f"http_path={http_path}&catalog={catalog}&schema={schema}",
  connect_args = {"auth_type": "databricks-oauth"}
)

# ...

OAuth M2M(컴퓨터 대 컴퓨터) 인증

OAuth M2M authentication은 Azure Databricks 서비스 주체로 인증합니다. 또한 Python용 Databricks SDK를 설치해야 합니다(예: 실행 pip install databricks-sdk등). 각 클라우드에서 이를 지원하는 Databricks SQL Connector for Python 및 SDK 버전에 대해서는 OAuth 머신 간(M2M) 인증을 참조하세요.

OAuth M2M 인증을 사용하려면 다음을 수행하세요:

Azure Databricks 작업 영역에서 Azure Databricks 서비스 주체를 만들고 해당 서비스 주체에 대한 OAuth 비밀을 만듭니다. OAuth를 사용하여 Azure Databricks에 대한 서비스 주체 액세스 권한 부여를 참조하세요.
그 서비스 주체에게 클러스터나 SQL 웨어하우스에 대한 접근 권한을 주세요. 컴퓨팅 사용 권한 또는 SQL 웨어하우스 관리를 참조하세요.

OAuth M2M으로 SQLAlchemy 방언을 인증하려면 다음 코드 스니펫을 사용하세요. DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG, DATABRICKS_SCHEMA 환경 변수 외에도, 이 스니펫은 다음 환경 변수들이 설정되어 있다고 가정합니다:

DATABRICKS_CLIENT_ID- 서비스 주체의 UUID 또는 애플리케이션 ID 값으로 설정합니다.
DATABRICKS_CLIENT_SECRET- 서비스 주체의 OAuth 비밀 에 대한 비밀 값으로 설정합니다.

import os
from databricks.sdk.core import Config, oauth_service_principal
from sqlalchemy import create_engine

server_hostname = os.getenv("DATABRICKS_SERVER_HOSTNAME")
http_path       = os.getenv("DATABRICKS_HTTP_PATH")
catalog         = os.getenv("DATABRICKS_CATALOG")
schema          = os.getenv("DATABRICKS_SCHEMA")

def credential_provider():
  config = Config(
    host          = f"https://{server_hostname}",
    client_id     = os.getenv("DATABRICKS_CLIENT_ID"),
    client_secret = os.getenv("DATABRICKS_CLIENT_SECRET"))
  return oauth_service_principal(config)

engine = create_engine(
  url = f"databricks://{server_hostname}?" +
        f"http_path={http_path}&catalog={catalog}&schema={schema}",
  connect_args = {"credentials_provider": credential_provider}
)

# ...

SQLAlchemy v1

연결 예제는 이 example.py 참조하세요.

SQLAlchemy v2

연결 예제는 GitHub의 다음 섹션 및 sqlalchemy_example.py 파일을 참조하세요.

Azure Databricks와 함께 SQLAlchemy 사용

요구 사항

시작

클러스터

SQL 웨어하우스

인증