dbt CoreとDatabricksを接続する

dbt CoreとDatabricksを接続する手順を解説します。

dbt Coreを使うと、好きなIDEでモデルを記述し、ローカル環境のコマンドラインからdbtを実行できます。今回は、Databricks Free EditionとPythonパッケージ管理ツールのuvを使って、接続確認まで進めます。

今回の構成

ローカルのdbtから、dbt-databricksアダプターを通じてDatabricksのSQLウェアハウスに接続します。モデルのSQLを実行する場所はDatabricks側です。

ローカルPC
  dbt Core（uv run dbt ...）
    │ dbt-databricks + 接続設定
    ▼
Databricks
  SQLウェアハウス（SQLの実行）
    │
    ▼
  カタログ → スキーマ → テーブル・ビュー

本記事の到達点は、dbt debugで接続が成功することです。データ変換処理を開発するために、まずはこの接続を整えます。

準備

Databricks Free Editionのアカウントと、ローカルPCで使うuvを用意します。dbt debugではGitの有無も確認されるため、Gitをインストールし、git --versionが実行できることも確認してください。

Databricks Free Editionの登録

Databricks Free Editionは、学習や検証に利用できる無料の環境です。利用量や機能には制限があるため、詳しくはFree Editionの制限事項を確認してください。

Databricks Free Editionの登録ページからサインアップします。

uvのインストール

筆者は最近、Pythonのパッケージ管理にuvを使うようになりました。uv runなら仮想環境を手動で有効化せずにコマンドを実行でき、Pythonのバージョン管理もできる点が便利です。

お使いのOSに合わせて、以下のいずれかの方法でインストールします。詳細はuvの公式インストール手順を参照してください。

macOS・Linuxの場合

curl -LsSf https://astral.sh/uv/install.sh | sh

macOSでは、Homebrewでもインストールできます。

brew install uv

Windowsの場合（PowerShell）

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

インストール後にターミナルを開き直し、確認します。

uv --version

dbt-databricksをインストールする

dbtのアダプターは、接続先に応じたSQLの実行やテーブルの作成などを担うパッケージです。今回はDatabricks用のdbt-databricksを使用します。

作業用フォルダを置きたい場所で、次のコマンドを実行します。

uv init my-project
cd my-project
uv add dbt-databricks
uv run dbt --version

uv initでPythonプロジェクトを作成し、uv addで依存パッケージと仮想環境を用意します。以降はuv run dbt ...で、この環境のdbtを実行します。必要なdbt Coreも依存関係としてインストールされます。

Pythonの互換性エラーが出た場合は、アダプターの対応条件を確認し、対応するPythonを指定してください。uvのプロジェクト管理については公式ガイドも参考になります。

Databricksの接続情報を用意する

dbt initを実行する前に、次の情報を確認しておきます。

ホスト名とHTTPパスを確認する

Databricksにログインし、「SQLウェアハウス」から接続先のウェアハウスを選んで、「接続の詳細」を開きます。筆者の環境では「Serverless Starter Warehouse」を使用しました。画面の配置やウェアハウス名は環境によって異なる場合があります。

アクセストークンを生成する

同じ画面で「dbt」を選び、用途が分かるコメントと有効期間を入力して「新規トークンを生成」をクリックします。生成された値を、後ほどtokenに入力します。

この記事では、筆者が接続に使ったPAT方式を紹介します。Databricksの公式手順ではOAuthが推奨されています。トークンはパスワードと同様に扱い、記事やGitリポジトリには含めないでください。

カタログとスキーマを確認する

Databricksのデータは、カタログ.スキーマ.テーブルという階層で管理されます。以下ではカタログ名をdbt_sample、スキーマ名をdbt_sample_schemaとしています。これらはサンプル名なので、自分の環境で利用できる名前に置き換えてください。

dbt initで名前を入力しても、カタログが作成されるわけではありません。あらかじめカタログ画面で作成先を確認し、スキーマやテーブルを作成できる権限があることを確認してください。

dbtプロジェクトを作成する

my-projectフォルダ内で、次のコマンドを実行します。

uv run dbt init dbt_sample_project

dbtのプロジェクト名にはハイフン（-）を使えないため、ここではアンダースコア（_）を使います。外側のuvプロジェクト名my-projectとは別の名前です。

対話形式で接続情報を入力します。以下は筆者の実行時の入力例を整理したものです。選択肢の番号や表示内容はバージョンによって変わるため、番号だけでなく項目名を確認してください。

Which database would you like to use?
[1] databricks
[2] spark
Enter a number: 1

host (yourorg.databricks.com): <サーバーのホスト名>
http_path (HTTP Path): <HTTPパス>

[1] use access token
Desired access token option (enter a number): 1
token (dapiXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX): <生成したアクセストークン>

[1] use Unity Catalog
[2] not use Unity Catalog
Desired unity catalog option (enter a number): 1

catalog (initial catalog): dbt_sample
schema (default schema that dbt will build objects in): dbt_sample_schema
threads (1 or more) [1]: 4

<...>の部分は、山括弧を含めずに自分の値を入力します。接続情報はprofiles.ymlに保存され、後から編集できます。

作業フォルダの主な構成は次のとおりです。

my-project/                 ← uvのプロジェクト
├── pyproject.toml          ← Pythonの依存関係
├── uv.lock                 ← 依存パッケージのバージョン
├── .venv/                  ← Pythonの仮想環境
└── dbt_sample_project/     ← dbtのプロジェクト
    ├── dbt_project.yml     ← dbtプロジェクトの設定
    └── models/             ← SQLモデルの配置先

接続を確認する

作成したdbtプロジェクトに移動し、dbt debugを実行します。Databricks側のSQLウェアハウスも起動できる状態にしておきます。

cd dbt_sample_project
uv run dbt debug

Connection test: [OK connection ok]は接続成功を示します。最後にAll checks passed!と表示されれば、設定ファイルや依存ツールを含めた確認も成功しています。

以下は筆者の実行ログの抜粋です。バージョン番号は実行当時のもので、インストール時期によって異なります。

09:03:31  Connection:
09:03:31    host: xxxxxxxxxxxxxx.cloud.databricks.com
09:03:31    http_path: /sql/1.0/warehouses/xxxxxxxxxxxxxxxxx
09:03:31    catalog: dbt_sample
09:03:31    schema: dbt_sample_schema
09:03:31  Registered adapter: databricks=1.12.5
09:03:46    Connection test: [OK connection ok]

09:03:46  All checks passed!

ここまでで接続確認は完了です。テーブルやビューの作成は、モデルを用意してdbt runなどを実行する段階で行います。

接続できないときの確認ポイント

まずはdbt debugのエラーメッセージを確認します。

profiles.ymlを確認・修正する

通常、接続設定は次の場所に保存されます。実際に参照される場所はdbt debugの出力でも確認できます。

• Windows：C:\Users\ユーザー名\.dbt\profiles.yml
• macOS・Linux：~/.dbt/profiles.yml

設定フォルダを調べるには、次のコマンドも使えます。

uv run dbt debug --config-dir

PAT認証の設定例です。既存の設定がある場合は、対象プロファイルの項目を修正してください。

dbt_sample_project:
  target: dev
  outputs:
    dev:
      type: databricks
      host: "<サーバーのホスト名>"
      http_path: "<HTTPパス>"
      token: "{{ env_var('DBT_ENV_SECRET_DATABRICKS_TOKEN') }}"
      catalog: dbt_sample
      schema: dbt_sample_schema
      threads: 4

先頭のdbt_sample_projectは、dbt_project.ymlのprofileの値と一致させます。この例はトークンを環境変数から読み込むため、実行するターミナルで設定が必要です。

Windows（PowerShell）の場合

$env:DBT_ENV_SECRET_DATABRICKS_TOKEN = '<生成したアクセストークン>'
uv run dbt debug

macOS・Linux（Bash・Zsh）の場合

export DBT_ENV_SECRET_DATABRICKS_TOKEN='<生成したアクセストークン>'
uv run dbt debug

値は自分のトークンに置き換えてください。これらの設定は現在のターミナルセッションで有効です。コマンド履歴にもトークンが残り得るため、共有しないようにします。環境変数の読み込み方はdbtのenv_varリファレンスを参照してください。

参考資料

• Databricks：dbt Coreへの接続
• dbt：Databricksの接続設定
• Databricks：Free Editionの制限事項
• uv：インストール手順
• uv：プロジェクト管理