Menggunakan SQLAlchemy dengan Azure Databricks

Azure Databricks menyediakan dialek SQLAlchemy (sistem yang digunakan SQLAlchemy untuk berkomunikasi dengan berbagai jenis implementasi dan API database) untuk Azure Databricks. SQLAlchemy adalah toolkit Python SQL dan Object Relational Mapper (ORM). SQLAlchemy menyediakan serangkaian pola persistensi tingkat perusahaan terkenal, yang dirancang untuk akses database yang efisien dan berkinerja tinggi, disesuaikan ke dalam bahasa domain sederhana dan Pythonic. Lihat Fitur dan Filsafat.

Dialek SQLAlchemy untuk Azure Databricks perlu diinstal untuk menggunakan fitur SQLAlchemy dengan Azure Databricks. Artikel ini membahas dialek SQLAlchemy untuk Azure Databricks versi 1.0 dan 2.0, yang akan didasarkan pada Databricks SQL Connector untuk Python versi 4.0.0 atau lebih tinggi.

Persyaratan

  • Mesin pengembangan yang menjalankan Python >=3.8 dan <=3.11.
  • Databricks merekomendasikan agar Anda menggunakan lingkungan virtual Python, seperti yang disediakan oleh venv yang disertakan dengan Python. Lingkungan virtual membantu memastikan bahwa Anda menggunakan versi Python yang benar dan Konektor SQL Databricks untuk Python bersama-sama. Menyiapkan dan menggunakan lingkungan virtual berada di luar cakupan artikel ini. Untuk informasi selengkapnya, lihat Membuat lingkungan virtual.
  • Kluster atau Gudang SQL yang sudah ada.

Mulai Sekarang

  • Instal databricks-sqlalchemy untuk SQLAlchemy v1 menggunakan pip install databricks-sqlalchemy~=1.0 atau untuk SQLAlchemy v2 menggunakan pip install databricks-sqlalchemy. Untuk informasi versi, lihat riwayat rilis databricks-sqlalchemy.

  • Kumpulkan informasi berikut ini untuk kluster atau gudang SQL yang ingin digunakan:

    Kluster

    Gudang SQL

    • Nama host server gudang SQL. Anda dapat memperoleh nama ini dari nilai Nama Host Server pada tab Detail Sambungan untuk gudang SQL Anda.
    • Path HTTP untuk gudang data SQL. Anda dapat memperoleh jalur ini dari nilai Jalur HTTP pada tab Detail Sambungan gudang SQL Anda.

Autentikasi

Dialek SQLAlchemy untuk Azure Databricks menggunakan Databricks SQL Connector untuk Python untuk terhubung, dan meneruskan nilai dalam connect_args ke konektor. Mendukung jenis otentikasi berikut:

Otentikasi token akses pribadi

Untuk membuat token akses pribadi Azure Databricks, ikuti langkah-langkah dalam Membuat token akses pribadi untuk pengguna ruang kerja.

Untuk mengautentikasi dialek SQLAlchemy, gunakan cuplikan kode berikut. Cuplikan ini mengasumsikan bahwa Anda telah mengatur variabel lingkungan berikut:

  • DATABRICKS_TOKEN, atur ke token akses pribadi Azure Databricks.
  • DATABRICKS_SERVER_HOSTNAMEdiatur ke nilai Server Hostname untuk kluster atau gudang SQL Anda.
  • DATABRICKS_HTTP_PATH, tetapkan ke nilai Jalur HTTP untuk kluster atau gudang SQL Anda.
  • DATABRICKS_CATALOG, ditentukan untuk katalog target di Unity Catalog.
  • DATABRICKS_SCHEMA, atur ke skema target (juga dikenal sebagai database) di Unity Catalog.

Untuk mengatur variabel lingkungan, lihat dokumentasi sistem operasi Anda.

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}"
)

# ...

Anda menggunakan variabel engine sebelumnya untuk terhubung dengan katalog dan skema yang Anda tentukan melalui sumber daya komputasi Azure Databricks Anda.

Autentikasi pengguna ke mesin (U2M) OAuth

Autentikasi OAuth U2M menggunakan login manusia secara real-time dan persetujuan untuk mengautentikasi akun pengguna Azure Databricks target. Untuk versi Databricks SQL Connector untuk Python yang mendukungnya di setiap cloud, lihat autentikasi OAuth pengguna-ke-komputer (U2M).

Untuk mengautentikasi dialek SQLAlchemy dengan OAuth U2M, gunakan potongan kode berikut. Cuplikan ini mengasumsikan bahwa Anda telah mengatur DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG, dan DATABRICKS_SCHEMA variabel lingkungan, seperti yang dijelaskan dalam autentikasi token akses Personal.

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"}
)

# ...

Autentikasi OAuth untuk mesin-ke-mesin (M2M)

Autentikasi OAuth M2M mengautentikasi sebagai prinsipal layanan Azure Databricks. Anda juga harus menginstal Databricks SDK untuk Python (misalnya, dengan menjalankan pip install databricks-sdk). Untuk versi Databricks SQL Connector untuk Python dan SDK yang mendukungnya di setiap cloud, lihat OAuth machine-to-machine (M2M) authentication.

Untuk menggunakan autentikasi OAuth M2M, lakukan hal berikut:

  1. Buat perwakilan layanan Azure Databricks di ruang kerja Azure Databricks Anda, dan buat rahasia OAuth untuk perwakilan layanan tersebut. Lihat Otorisasi akses prinsipal layanan ke Azure Databricks dengan OAuth.
  2. Berikan akses ke cluster atau gudang SQL Anda pada service principal tersebut. Lihat Izin komputasi atau Mengelola gudang SQL.

Untuk mengautentikasi dialek SQLAlchemy dengan OAuth M2M, gunakan potongan kode berikut. Selain variabel lingkungan DATABRICKS_SERVER_HOSTNAME, DATABRICKS_HTTP_PATH, DATABRICKS_CATALOG, dan DATABRICKS_SCHEMA, cuplikan ini mengasumsikan bahwa Anda telah menetapkan variabel lingkungan berikut:

  • DATABRICKS_CLIENT_ID, atur ke nilai UUID atau ID Aplikasi perwakilan layanan.
  • DATABRICKS_CLIENT_SECRET, tetapkan ke nilai Rahasia untuk kunci rahasia OAuth dari perwakilan layanan.
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

Untuk contoh koneksi, lihat example.py ini

SQLAlchemy v2

Untuk contoh koneksi, lihat bagian berikut dan file sqlalchemy_example.py di GitHub.

Referensi DBAPI

Sumber Daya Tambahan:

  • Terakhir diperbarui pada