Go to Qiita Advent Calendar Top
LoginSignup
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

Day 24

dbt Advent Calendar 2025

@uatsuki

dbt × BigQuery を macOSでセットアップ

Posted at

はじめに

普段 BI エンジニアとして BigQuery をよく触っています。
データマート作成では Dataform を利用することが多いのですが、dbt を使うケースも増えているようなので、勉強も兼ねてローカル環境にセットアップしました。

この記事では、macOS（arm64）環境で dbt-bigquery をインストールし、サービスアカウント認証で dbt run まで実行する ところまでをまとめています。
後半に、実際に詰まったポイントと対処も備忘録として残しています。

対象

  • macOS（arm64）で環境構築する方
  • BigQuery は触ったことがあるが、dbt はこれから触る方
  • まずは dbt debug を通して dbt run まで動かしたい方

前提環境

この記事は以下の環境を前提にしています。差分がある場合は読み替えてください。

  • OS: macOS（arm64）

  • シェル: zsh

  • インストール方針: Homebrew + pipx（dbt は pipx で管理）

  • dbt: dbt Core 1.11系 + dbt-bigquery 1.11系（pipx の仮想環境で実行）

  • Python:

    • ローカルの python3 は 3.8.x でも OK
    • dbt が実際に使う Python は pipx venv 側
    • dbt debug の python version / python path を正として確認する

  • 認証方式: BigQuery は Service Account（JSON key）

※「なぜ pipx なのか」「なぜ Service Account なのか」は、後半の FAQ にまとめています。

マスキング方針

この記事では以下をプレースホルダで表現します。

  • <HOME>: ホームディレクトリ（例：/Users/xxxxx）
  • <PROJECT_ID>: GCP プロジェクト ID（例：my-project-123456）
  • <PROJECT_DISPLAY>: プロジェクト表示名（例：my-project ※IDと別物）
  • <DATASET>: BigQuery dataset 名（例：dbt_practice）
  • <LOCATION>: dataset のロケーション（例：asia-northeast1）
  • <USER_EMAIL>: ユーザーアカウント（例：user@example.com）
  • <SA_EMAIL>: サービスアカウント（例：dbt-runner@<PROJECT_ID>.iam.gserviceaccount.com）
  • <KEYFILE>: 鍵ファイルパス（例：<HOME>/.gcp/dbt-key.json）

ゴール

ローカル（macOS）から dbt を実行し、BigQuery 上にモデルが作成されるところまでを確認する。

セットアップ手順

0. Homebrew（未導入の場合のみ）

0-1) インストール

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

0-2) brew に PATH を通す

インストールの最後に「Next steps」として PATH を通すコマンドが表示されます。それをそのまま実行してください。
（例：Apple Silicon の場合は eval "$(/opt/homebrew/bin/brew shellenv)" 系が表示されることが多いです）

0-3) 動作確認

brew --version
brew doctor

1. pipx をインストール

brew install pipx
pipx --version

確認：

which pipx

2. dbt-bigquery を pipx でインストール

pipx install dbt-bigquery --include-deps

確認：

pipx list

※ --include-deps の理由は FAQ にまとめています（dbt コマンドが PATH に出ない問題の対策）。

3. PATH を通して dbt コマンドを使えるようにする

pipx の実行ファイルは多くの場合 <HOME>/.local/bin に作られます。
ここが PATH に入っていないと dbt: command not found になります。

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

確認：

which dbt
dbt --version

4. サービスアカウントの作成〜権限付与〜JSONキー作成（GCPコンソール手順）

ここは GCP コンソール上の操作です。
※ 画面の文言は多少変わることがありますが、流れは同じです。

4-1) サービスアカウントを作成

GCP コンソール → IAM と管理 → サービス アカウント
→ 「サービス アカウントを作成」

  • サービス アカウント名：例）dbt-runner
  • 作成後のメール例：dbt-runner@<PROJECT_ID>.iam.gserviceaccount.com

このメールアドレスを <SA_EMAIL> として以降で使います。

4-2) プロジェクト IAM でロール付与（プロジェクト直下）

GCP コンソール → IAM と管理 → IAM
→ 「アクセスを許可」（または「メンバーを追加」）で <SA_EMAIL> を指定し、ロールを付与します。

付与するロール（例）：

  • BigQuery Job User（roles/bigquery.jobUser）
  • BigQuery User（roles/bigquery.user）※運用方針で省略可
  • Service Usage Consumer（roles/serviceusage.serviceUsageConsumer）※環境により必要

4-3) dataset IAM でロール付与（dataset 単位）

BigQuery → 対象のデータセット → 「権限」 タブ
→ 「プリンシパルを追加」（または「共有」「アクセス権を管理」など）で <SA_EMAIL> を追加します。

付与するロール（例）：

  • BigQuery Data Editor（roles/bigquery.dataEditor）

※ dbt run でテーブル/ビュー作成が必要なので、dataset 側の権限が無いとここで詰まります。

4-4) JSON キーを作成（ダウンロード）

IAM と管理 → サービス アカウント → 対象の <SA_EMAIL>
→ 「キー」 タブ → 「キーを追加」 → 「新しいキーを作成」 → JSON

5. JSON key をローカルに配置（保存と権限制御）

ダウンロードした JSON は機密情報なので、保存場所と権限を絞ります。

mkdir -p <HOME>/.gcp
mv <DOWNLOADED_JSON> <KEYFILE>
chmod 600 <KEYFILE>

注意：

  • JSON キーは Git に入れない（.gitignore 推奨）
  • 共有ストレージに置かない
  • 不要になったらキー削除/ローテーションする

6. dbt プロジェクト作成

dbt init dbt_test
cd dbt_test

dbt-test のようなハイフン入りは弾かれることがあるため、dbt_test のように _ を使うのが無難です。

7. ~/.dbt/profiles.yml を設定

接続設定は ~/.dbt/profiles.yml に書きます。

重要：project は プロジェクト表示名ではなくプロジェクト ID を指定します。

dbt_test:
  target: dev
  outputs:
    dev:
      type: bigquery
      method: service-account
      project: <PROJECT_ID>
      dataset: <DATASET>
      location: <LOCATION>
      keyfile: <KEYFILE>
      threads: 4

8. 接続確認

dbt debug

成功すると以下が表示されます。

All checks passed!

9. 最小モデルで dbt run を通す

echo "select 1 as id" > models/first_model.sql
dbt run

BigQuery 側のデータセットに first_model が作成されれば完了です。

FAQ

Q. なぜ Homebrew ではなく pipx でインストールするの？

A. dbt は Python 製の CLI ツールなので、環境によっては Homebrew での導入がうまくいかないことがあります（例：dbt-bigquery の formula が見つからないなど）。
pipx を使うと CLI ツールを “ツールごとに仮想環境へ隔離” できるため、依存関係の混線が起きにくく、導入と削除もシンプルになります。

Q. なぜ pip install 直ではなく pipx なの？

A. pip install 直だと、system python / pyenv / venv などが混ざって依存関係を崩しやすく、後から状態が追いにくくなりがちです。
pipx は CLI ツール専用に隔離する前提なので、dbt と相性が良いです。

Q. pipx install dbt-bigquery --include-deps の --include-deps はなぜ必要？

A. dbt-bigquery は BigQuery 向けの “アダプタ” で、dbt コマンド本体は依存パッケージ（主に dbt-core）側で提供されます。
pipx は通常「インストールしたパッケージの実行ファイル」だけを公開するため、環境によっては pipx install dbt-bigquery だけだと dbt コマンドが PATH に出てこない ことがあります。

その対策として、依存パッケージ側の実行ファイルも公開する --include-deps を付けています。

確認方法：

pipx list

apps に dbt が出ていない場合は入れ直すのが早いです。

pipx uninstall dbt-bigquery
pipx install dbt-bigquery --include-deps

Q. なぜ Service Account 認証にしたの？

A. ローカル検証でも 認証情報が固定されて再現性が上がる ためです。
ユーザー認証（ADC）は端末の状態に影響されやすく、複数アカウントや quota project 設定などで切り分けが難しくなることがあります。

また将来的に CI/CD に移行する場合も、Service Account のほうが設定を持っていきやすいです。

Q. JSON キーはどこに置くのがいい？

A. ローカルの安全な場所に置き、権限を絞ります（例：<HOME>/.gcp/）。

chmod 600 <KEYFILE>

備忘録（詰まったところと対処）

詰まりA：brew install dbt-bigquery が通らない

症状

brew install dbt-bigquery
# Warning: No available formula with the name "dbt-bigquery".
# Error: No formulae or casks found for dbt-bigquery.

対応

brew install pipx
pipx install dbt-bigquery --include-deps

詰まりB：pipx list が空になる

切り分け

which pipx
pipx --version

対応

pipx install dbt-bigquery --include-deps
pipx list

詰まりC：dbt が見つからない（command not found）

原因候補

  • <HOME>/.local/bin が PATH に入っていない
  • --include-deps を付けていない

対応

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
pipx uninstall dbt-bigquery
pipx install dbt-bigquery --include-deps

詰まりD：dbt --version が Python の例外で落ちる

切り分け（dbt が使っている Python を確認）

dbt debug
# python version / python path を確認

対応（再現性が低いので現実的な手段）

pipx の venv を作り直す（再インストール）と解消することがあります。

pipx uninstall dbt-bigquery
pipx install dbt-bigquery --include-deps

詰まりE：dbt debug で dbt_project.yml not found

対応

cd <YOUR_DBT_PROJECT_DIR>
ls
dbt debug

詰まりF：bigquery.jobs.create が出続ける

まず確認

  • profiles.yml が method: service-account になっているか
  • keyfile: が正しいパスを指しているか
  • project: が プロジェクト ID になっているか（表示名ではない）

よくある原因

project: に表示名（<PROJECT_DISPLAY>）を入れている。

最終チェックリスト

コマンド・実行環境

  • which dbt が <HOME>/.local/bin/dbt
  • dbt --version が落ちない
  • dbt debug の python path が .../.local/pipx/venvs/dbt-bigquery/bin/python

dbt プロジェクト

  • dbt_project.yml がプロジェクト直下にある
  • dbt_project.yml の profile: が profiles.yml と一致

BigQuery（Service Account）

  • project は プロジェクト ID
  • dataset / location が一致
  • <SA_EMAIL> に必要な IAM（プロジェクト/データセット）が付与されている
  • dbt debug が All checks passed!
  • dbt run で <DATASET> にモデルが作成できる

おわりに

セットアップでだいぶ時間を使ってしまいました…
少しニッチな領域にはなりますが、参考になれば幸いでございます。

0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?