dbt profiles.yml と接続管理：環境別のベストプラクティス

profiles.yml は dbt の実行時接続を定義する中核ファイルです。環境ごとに安全かつ再現性高く切り替えられる設計にしておくことは、開発効率と事故防止の両方に直結します。

この記事では、Analytics Engineer 試験で問われやすいポイント（プロファイル探索順序、ターゲット解決の優先度、アダプタ別の主要キー、env_var の使い方）を、実務に落ちる具体例とともに解説します。

profiles.yml の基礎と探索順序

dbt は dbt_project.yml の profile 名と一致するエントリを profiles.yml から読み込み、選択された target の outputs を用いて接続します。profiles.yml の標準パスはユーザディレクトリ配下で、DBT_PROFILES_DIR を指定すると別の場所を参照できます。これは CI でリポジトリ直下に置きたい場合などに有効です。

構造は profile 名の下に target（既定の実行環境名）と outputs（環境ごとの接続定義）が並びます。outputs にはアダプタ固有のキー（例: Snowflake の account, warehouse、Databricks の host, http_path など）を記述します。安定仕様として profiles.yml では Jinja と env_var が利用でき、秘密情報の直接記載は避けます。

• 探索順序の要点: DBT_PROFILES_DIR があればその配下の profiles.yml、なければ ~/.dbt/profiles.yml
• OS の既定パス: macOS/Linux は ~/.dbt/profiles.yml、Windows は %USERPROFILE%\.dbt\profiles.yml
• プロファイル名の一致: dbt_project.yml の profile: 値と profiles.yml のトップレベルキーが一致している必要がある
• target は省略時に使用される既定環境名。--target または DBT_TARGET で上書き可能

最小の profiles.yml スケルトン（Snowflake 例）

ja_lab:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: {{ env_var('SF_ACCOUNT') }}
      user: {{ env_var('SF_USER') }}
      password: {{ env_var('SF_PASSWORD') }}
      role: ANALYST
      database: ANALYTICS
      warehouse: WH_XS
      schema: dev
      threads: 4
    stg:
      type: snowflake
      account: {{ env_var('SF_ACCOUNT') }}
      user: {{ env_var('SF_USER') }}
      password: {{ env_var('SF_PASSWORD') }}
      role: ANALYST
      database: ANALYTICS
      warehouse: WH_S
      schema: stg
      threads: 6
    prod:
      type: snowflake
      account: {{ env_var('SF_ACCOUNT') }}
      user: {{ env_var('SF_USER') }}
      password: {{ env_var('SF_PASSWORD') }}
      role: PROD_ROLE
      database: ANALYTICS
      warehouse: WH_M
      schema: prod
      threads: 8

環境別ターゲットの切替戦略

ターゲットの解決は優先度があり、CLI の --target が最も強く、その次に環境変数 DBT_TARGET、最後に profiles.yml の target が使われます。CI では明示的に --target を指定し、ローカルの開発では DBT_TARGET を一時的に設定する運用が扱いやすいです。

環境名は dev/stg/prod など短く衝突しない命名を推奨します。--profiles-dir と組み合わせることで、モノレポでもプロジェクト単位の profiles.yml を安全に参照できます。

• 優先度: --target > DBT_TARGET > profiles.yml の target
• 一時切替は DBT_TARGET=... で、確定的な実行は --target ... を明示
• ターゲット未定義エラーは profiles.yml の outputs に該当名がない場合に発生

ターゲット解決の流れ

切替コマンド例

# 一時的に stg で実行
export DBT_TARGET=stg
 dbt run

# CI では明示的に指定
 dbt build --target prod --profiles-dir .

# 確認（接続検証）
 dbt debug --target dev

認証情報を安全に注入する

profiles.yml はバージョン管理に含める前提で設計し、秘密情報はすべて env_var で参照します。dbt は Jinja を解釈し、env_var('KEY') の値を実行時に埋め込みます。これによりパスワードやトークンをコードに残さず、安全に環境差分を表現できます。

CI/CD では各ランナーのシークレット機能で環境変数を注入します。Databricks は個人アクセストークン、Snowflake はパスワードに加えキーペア認証や OAuth なども利用可能です。運用要件に応じて選択し、最低権限ロールを環境別に割り当てます。

• profiles.yml に秘密情報を直書きしない。env_var を用いる
• .env を使う場合はリポジトリにコミットしない（.gitignore に追加）
• CI ではランナーのシークレットストアを利用し export せずとも注入させる
• Snowflake はキー/トークン/パスワード等の方式、Databricks は token を利用する構成が一般的

env_var を使った安全なプロファイル記述（抜粋）と環境変数設定例

# profiles.yml（抜粋）
ja_lab:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: {{ env_var('SF_ACCOUNT') }}
      user: {{ env_var('SF_USER') }}
      password: {{ env_var('SF_PASSWORD') }}
      role: {{ env_var('SF_ROLE', 'ANALYST') }}
      database: ANALYTICS
      warehouse: {{ env_var('SF_WAREHOUSE', 'WH_XS') }}
      schema: dev

# Databricks 例（token 認証）
    dev_dw:
      type: databricks
      catalog: hive_metastore
      schema: dev
      host: {{ env_var('DB_HOST') }}
      http_path: {{ env_var('DB_HTTP_PATH') }}
      token: {{ env_var('DB_TOKEN') }}
      threads: 4

# ローカル環境変数設定（例）
export SF_ACCOUNT="xy12345.ap-southeast-1"
export SF_USER="analyst"
export SF_PASSWORD="..."
export DB_HOST="adb-123456789.11.azuredatabricks.net"
export DB_HTTP_PATH="/sql/1.0/warehouses/xxxx"
export DB_TOKEN="dapi..."

アダプタ別の接続パラメータ比較

アダプタごとに必須キーや推奨の認証方式が異なります。環境差分をどこで持つべきか（例: Snowflake は warehouse/role、Databricks は http_path や catalog/schema、Postgres はホストやデータベース）を決めておくと、profiles.yml が簡潔になります。

試験では、各アダプタの type 名、代表的な必須キー、そして環境切替のポイントを把握しているかが問われやすいです。

• 共通: type, schema, threads は多くのアダプタで共通的に登場
• Snowflake は role と warehouse、Databricks は token と http_path、Postgres は user/password/port の整合性に注意
• 環境差分は実行コストや権限に直結する項目で管理する（例: warehouse サイズ、ロール、接続先 DB）

Databricks SQL Warehouse の最小設定例

ja_lab:
  target: dev_dw
  outputs:
    dev_dw:
      type: databricks
      schema: dev
      host: {{ env_var('DB_HOST') }}
      http_path: {{ env_var('DB_HTTP_PATH') }}
      token: {{ env_var('DB_TOKEN') }}
      threads: 4

再利用できる profiles.yml パターン

YAML アンカーと Jinja を併用すると、環境差分を最小限に保てます。ベース定義を &base でまとめ、dev/stg/prod では差分のみ上書きします。schema や role、warehouse は target.name や環境変数で動的に決めると管理が容易です。

threads やリトライ設定などの実行系パラメータも環境変数で制御すると、CI とローカルで同一の profiles.yml を共有しやすくなります。

• ベース出力を &base として定義し、<<: *base で継承
• schema を analytics_{{ target.name }} のように動的にする
• 高機密ロジックはアプリ側に寄せ、profiles.yml では最小限の式に留める

アンカーと Jinja で環境差分を最小化

ja_lab:
  target: dev
  outputs:
    base: &base
      type: snowflake
      account: {{ env_var('SF_ACCOUNT') }}
      user: {{ env_var('SF_USER') }}
      password: {{ env_var('SF_PASSWORD') }}
      database: ANALYTICS
      role: {{ env_var('SF_ROLE', 'ANALYST') }}
      warehouse: {{ env_var('SF_WH', 'WH_S') }}
      schema: analytics_{{ target.name }}
      threads: {{ env_var('DBT_THREADS', 4) | int }}
    dev:
      <<: *base
    stg:
      <<: *base
      warehouse: {{ env_var('SF_WH_STG', 'WH_M') }}
    prod:
      <<: *base
      role: PROD_ROLE
      warehouse: {{ env_var('SF_WH_PROD', 'WH_L') }}
      threads: {{ env_var('DBT_THREADS_PROD', 8) | int }}

トラブルシュートと試験観点

profiles.yml 周りのエラーは原因が特定しやすい反面、設定ミスが多発します。dbt debug をまず実行し、プロファイル検出、資格情報、権限の順に切り分けます。試験では、プロファイル探索、ターゲット解決、権限設計の知識が問われやすいです。

代表的な症状と対処は次の通りです。

• profile 'xxx' does not exist: dbt_project.yml の profile 名と profiles.yml のキー不一致、または DBT_PROFILES_DIR の参照先誤り
• target 'stg' is not defined: outputs に stg が存在しない
• permission denied: 接続は成功しても role/schema 権限不足。環境別ロール割当を見直す
• 接続検証は dbt debug、接続先の確認は dbt debug -t <target> で行う

チェックリスト用コマンド

# プロファイル探索と接続検証
 dbt debug --profiles-dir . --target dev

# 実行ターゲットの明示
 dbt run --target stg

# テストまで一括
 dbt build --target prod

問題で確認

よくある質問