Python 및 pyodbc를 Azure Databricks에 연결

  • 아티클

ODBC를 통해 로컬 Python 코드에서 Azure Databricks 클러스터 또는 SQL 웨어하우스의 데이터에 연결할 수 있습니다. 이를 위해 오픈 소스 Python 코드 모듈 pyodbc를 사용할 수 있습니다.

다음 지침에 따라 pyodbc를 설치, 구성 및 사용합니다.

pyodbc에 대한 자세한 내용은 pyodbc Wiki를 참조하세요.

참고 항목

Databricks는 pyodbc의 대안으로 Python용 Databricks SQL 커넥터를 제공합니다. Python용 Databricks SQL 커넥터는 설정 및 사용이 더 쉬우며 pyodbc보다 강력한 코딩 구성 집합이 있습니다. 그러나 10MB를 초과하는 쿼리 결과를 가져올 때 pyodbc의 성능이 더 좋을 수 있습니다.

이러한 지침은 Databricks ODBC 드라이버 2.7.5, pyodbc 5.0.1 및 unixODBC 2.3.12로 테스트되었습니다.

요구 사항

  • 다음 중 하나를 실행하는 로컬 개발 머신:
    • macOS
    • Windows
    • .rpm 또는 .deb 파일을 지원하는 Unix 또는 Linux 배포판
  • pip.
  • Unix, Linux 또는 macOS의 경우 Homebrew.
  • Azure Databricks 클러스터, Databricks SQL 웨어하우스 또는 둘 다. 자세한 내용은 컴퓨팅 구성 참조 및 SQL 웨어하우스 만들기를 참조하세요.

1단계: 소프트웨어 다운로드, 설치 및 구성

이 단계에서는 Databricks ODBC 드라이버, unixodbc 패키지 및 pyodbc 모듈을 다운로드하고 설치합니다. (모듈에는 pyodbc Unix, Linux 및 macOS의 패키지가 필요합니다 unixodbc .) 또한 클러스터 또는 SQL 웨어하우스에서 인증하고 연결하도록 ODBC DSN(데이터 원본 이름)을 구성합니다.

  1. Databricks ODBC 드라이버를 다운로드하여 설치하고 운영 체제에 대한 ODBC DSN 을 구성합니다.
  2. Unix, Linux 및 macOS의 unixodbc 경우 패키지를 설치합니다. 터미널에서 Homebrew를 사용하여 명령을 brew install unixodbc실행합니다. 자세한 내용은 Homebrew 웹 사이트에서 unixodbc를 참조하세요.
  3. 모듈을 pyodbc 설치합니다. 터미널 또는 명령 프롬프트에서 명령을 pip install pyodbc실행하는 데 사용합니다pip. 자세한 내용은 PyPI 웹 사이트의 pyodbc 및 pyodbc Wiki의 설치를 참조하세요.

2단계: 구성 테스트

이 단계에서는 Python 코드를 작성하고 실행하여 Azure Databricks 클러스터 또는 Databricks SQL Warehouse를 사용하여 카탈로그 스키마의 nyctrips 테이블을 samples 쿼리 trips 하고 결과를 표시합니다.

  1. 다음과 같은 내용으로 pyodbc-demo.py라는 파일을 만듭니다. <dsn-name> 앞에서 만든 ODBC DSN의 이름으로 바꾸고 파일을 저장한 다음 Python 인터프리터를 사용하여 파일을 실행합니다.

    import pyodbc

# Connect to the Databricks cluster by using the
# Data Source Name (DSN) that you created earlier.
conn = pyodbc.connect("DSN=<dsn-name>", autocommit=True)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute(f"SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

  2. 코드 실행 속도를 향상하려면 DSN의 설정에 해당하는 클러스터 를 HTTPPath 시작합니다.

  3. Python 인터프리터로 pyodbc-demo.py 파일을 실행합니다. 테이블의 행에 대한 정보가 표시됩니다.

다음 단계

  • 다른 클러스터 또는 SQL 웨어하우스에 대해 Python 테스트 코드를 실행하려면 다른 DSN을 만들고 DSN의 이름으로 변경 <dsn-name> 합니다.
  • 다른 SQL 쿼리로 Python 테스트 코드를 실행하려면 execute 명령 문자열을 변경합니다.

DSN이 없는 연결 사용

DSN 이름을 사용하는 대신 인라인으로 연결 설정을 지정할 수 있습니다. 다음 예제에서는 Azure Databricks 개인용 액세스 토큰 인증에 DSN이 없는 연결 문자열 사용하는 방법을 보여 줍니다. 이 예제에서는 다음과 같은 환경 변수가 있다고 가정합니다.

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

import pyodbc
import os

conn = pyodbc.connect(
  "Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
  f"Host={os.getenv('DATABRICKS_HOST')};" +
  "Port=443;" +
  f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
  "SSL=1;" +
  "ThriftTransport=2;" +
  "AuthMech=3;" +
  "UID=token;" +
  f"PWD={os.getenv('DATABRICKS_TOKEN')}",
  autocommit = True
)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

다음 예제에서는 Azure Databricks 개인용 액세스 토큰 대신 OAuth U2M(사용자-컴퓨터) 또는 OAuth 2.0 브라우저 기반 인증을 사용합니다. 이 예제에서는 이전 및 DATABRICKS_HTTP_PATH 환경 변수를 DATABRICKS_SERVER_HOSTNAME 이미 설정한다고 가정합니다.

import pyodbc
import os

conn = pyodbc.connect(
  "Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
  f"Host={os.getenv('DATABRICKS_HOST')};" +
  "Port=443;" +
  f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
  "SSL=1;" +
  "ThriftTransport=2;" +
  "AuthMech=11;" +
  "Auth_Flow=2;" +
  "PWD=1234567",
  autocommit = True
)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

다음 예제에서는 OAuth M2M(컴퓨터-컴퓨터) 또는 OAuth 2.0 클라이언트 자격 증명 인증을 사용합니다. 이 예제에서는 이전 DATABRICKS_SERVER_HOSTNAME 및 환경 변수와 DATABRICKS_HTTP_PATH 다음 환경 변수를 이미 설정한다고 가정합니다.

  • 서비스 주체의 애플리케이션(클라이언트) ID 값으로 설정합니다ARM_CLIENT_ID.
  • 서비스 주체의 OAuth 비밀 값으로 설정합니다DATABRICKS_OAUTH_SECRET. (Microsoft Entra ID(이전의 Azure Active Directory) 비밀은 Databricks ODBC 드라이버를 사용하여 OAuth M2M 또는 OAuth 2.0 클라이언트 자격 증명 인증에 대해 지원되지 않습니다.)

자세한 내용은 OAuth M2M(컴퓨터 대 컴퓨터) 인증을 참조하세요.

import pyodbc
import os

conn = pyodbc.connect(
  "Driver=/Library/simba/spark/lib/libsparkodbc_sb64-universal.dylib;" +
  f"Host={os.getenv('DATABRICKS_HOST')};" +
  "Port=443;" +
  f"HTTPPath={os.getenv('DATABRICKS_HTTP_PATH')};" +
  "SSL=1;" +
  "ThriftTransport=2;" +
  "AuthMech=11;" +
  "Auth_Flow=1;" +
  f"Auth_Client_ID={os.getenv('ARM_CLIENT_ID')};" +
  f"Auth_Client_Secret={os.getenv('DATABRICKS_OAUTH_SECRET')}",
  autocommit = True
)

# Run a SQL query by using the preceding connection.
cursor = conn.cursor()
cursor.execute("SELECT * FROM samples.nyctaxi.trips")

# Print the rows retrieved from the query.
for row in cursor.fetchall():
  print(row)

문제 해결

이 섹션에서는 Databricks와 함께 pyodbc를 사용할 때 발생하는 일반적인 문제를 다룹니다.

유니코드 디코딩 오류

문제: 다음과 유사한 오류 메시지가 나타납니다:

<class 'pyodbc.Error'> returned a result with an error set
Traceback (most recent call last):
File "/Users/user/.pyenv/versions/3.7.5/lib/python3.7/encodings/utf_16_le.py", line 16, in decode
return codecs.utf_16_le_decode(input, errors, True)
UnicodeDecodeError: 'utf-16-le' codec can't decode bytes in position 2112-2113: illegal UTF-16 surrogate

원인: pyodbc 버전 4.0.31 이하에 긴 이름이나 긴 오류 메시지가 있는 열을 반환하는 쿼리를 실행할 때 이러한 증상이 나타날 수 있는 문제가 있습니다. 이 문제는 최신 버전의 pyodbc에서 수정되었습니다.

해결 방법: pyodbc 설치를 버전 4.0.32 이상으로 업그레이드합니다.

일반적인 문제 해결

GitHub의 mkleehammer/pyodbc 리포지토리에서 문제를 참조하세요.