TROCCO dbt連携編

こんにちは、エクチュアの照沼です。

前回のブログでTROCCO入門編としてデータの転送・データマートの定義・ワークフローの作成の方法について触ってみました。今回はその続きとしてTROCCOのdbt連携について触っていきたいと思います。

前回のブログが気になる方は下のURLから確認してみてください。
https://ex-ture.com/blog/2025/05/01/trocco_for_beginner

目次

0. dbtとは
1. GitHubリポジトリの作成
2. dbt Gitリポジトリの作成
3. dbtジョブの設定
4. GitHub Actionsを用いたTROCCOでのdbtドキュメント生成




０．dbtとは

まずdbtって何？という人もいると思うのでdbtについて解説していこうと思います。
dbtはELTツールの中のT（変換）を担うツールです。
dbtはデータカタログの生成、テスト・検証機能の組み込み、安全性の高い管理が可能なツールです。拡張SQLを用いることで、ソフトウェアエンジニアリングのベストプラクティスを取り入れた開発が行えます。
dbtにはdbt Coreとdbt Cloudの二種類があります。
dbt Coreとdbt Cloudの機能の違いは以下の表になります。

項目	dbt Core	dbt Cloud
提供形態	オープンソース（無料）	SaaS（有料プランあり）
実行環境	ローカル環境（CLI）	クラウド上で実行
セットアップ	手動（Python環境＆CLIセットアップが必要)	Web UIから簡単セットアップ
スケジューリング	Airflow, Prefect, dbt Cloud APIなど外部ツールが必要	内蔵のスケジューリング機能あり
コラボレーション	Gitベースの管理 (個別に設定）	Web UIでチーム管理、変更履歴トラッキング
認証・権限管理	手動で設定	シングルサインオン (SSO) 連携対応
ログ管理	ローカルログのみ	実行履歴やログをWeb UIで確認可能
CI/CDの統合	GitHub Actions, GitLab CI/CD などを設定する必要あり	内蔵のCI/CD機能で簡単に統合可能
サポート	コミュニティベース	公式サポートあり（有料プラン）


dbt Coreは無料である反面、Web UIがないため使いづらく、スケジューリング機能も備わっていないなどの弱点があります。
そこで、TROCCOの出番です。TROCCOにはdbt Coreを使う機能が備わっています。
TROCCOを通じてdbt Coreを使えば、Web UIで操作できたり、スケジューリングができたりと、dbt Coreの弱点をカバーできます
そんな親和性の高いありがたい機能を触っていきたいと思います！！



１．GitHubリポジトリの作成

dbt coreはGitHubを用いて管理をするのでまずGitHubのリポジトリを作成していきます！
GitHubにログインし、Homeを開くと下の画像になるので「New」をクリック！



クリックしたら下の画像になるのでRepository nameを入力し、「Create repository」をクリックすれば完成！



２．dbt Gitリポジトリの作成

次に、TROCCOに先ほど作成したリポジトリを用いて、dbt Gitリポジトリを作成していきます。
dbt Gitリポジトリの新規作成をクリックすると下の画像になるので必須情報を入力します。また、今回は前回のブログで作成したテーブルに対して作業を行うのでアダプタとしてはSnowflakeを用います。





記入項目	説明
名前	自由
リポジトリURL	設定したいリポジトリのSSHをコピーして貼り付け
ブランチ名	リポジトリ内のブランチを入力

入力が完了し、保存を押すと入力画面の上に、下の画像のようなDeploy keyが表示されるのでコピーしておきます。



次にGitHubのSettings> Deploy keysにコピーしたDeploy keyを登録します。



ここまでできればdbt Gitリポジトリの登録が完了しました。



３．dbtジョブの設定

dbtジョブ設定の新規追加をクリックすると下の画像になるので必須情報を入力します。



記入項目	説明
名前	自由
dbt Gitリポジトリ	クリックすると候補が表示されるので１で作成した名前を選択 ※候補が表示されない場合は下のdbt Gitリポジトリをクリックしてからもう一度 　行うと表示される。
実行コマンド	今回はdbt deps⇒dbt buildを行うように設定 ※TROCCOで実行できるdbtコマンド一覧 　dbt deps：packages.ymlファイルに記述されている依存関係をダウンロード 　dbt run：モデルの処理実行 　dbt test：テストコードを実行 　dbt snapshot：dbt_project.ymlファイルで定義された 　　　　　　　　snapshots-pathsにあるスナップショットを実行 　dbt seed：dbt_project.ymlファイルで定義された 　　　　　　seed-pathsで見つかったCSVファイルをロード 　dbt build：dbt run + dbt test + dbt snapshot + dbt seedをDAG順に実行 　dbt run-operation：dbtで定義したマクロ（SQLスクリプト）を実行する

これで実行をすれば、TROCCOによるdbtの実行は完了です！
次にせっかくdbt使うならドキュメントを作成したい！ところですがTROCCOの実行コマンドにはdbt docs generate・dbt docs serveコマンドはないのでGitHub ActionsとTROCCOのワークフローを用いてドキュメント生成ができるようにしていきたいと思います。




４．GitHub Actionsを用いたTROCCOでのdbtドキュメント生成

全体の流れとしてはdbt docs generateを実行するGitHub Actionsを作成し、TROCCOのワークフローにあるHTTPリクエストを用いてGitHub Actionsを実行する流れになります。

まず、GitHub Actionsを作成します。
以下のようにコードを書くことでdbt docs generateを実行することができます。

name: Generate dbt docs after trocco run

on:
  repository_dispatch:
    types: [trocco]


jobs:
  generate_docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install dbt and dependencies
        run: |
          pip install dbt-core dbt-snowflake

      - name: Set up profiles.yml
        run: |
          mkdir -p ~/.dbt
          cp ./profiles.yml ~/.dbt/profiles.yml

      - name: dbt deps
        run: |
          dbt deps

      - name: Generate dbt docs
        run: |
          dbt docs generate

※重要なのがrepository_dispatchの部分です。
　ここのtypesにはこの後設定するHTTPリクエストボディに設定する値が入ります。

しかし、このままではワークフローが終了すると、GitHub Actionsの仮想環境が削除されるため、生成したドキュメントは見れません。そのため、ドキュメントはS3などに保存する必要があります。
保存する場所はご自身の環境に合わせて設定してみてください！

ちなみに…
S3に保存するの場合は以下のようなコードになります。

      - name: Upload docs to S3
        env:
          AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
          AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        run: |
          pip install awscli
          aws s3 sync target/ s3://my-dbt-docs-bucket/ --delete

※このコードを使用する際は二点作業をしてから使ってください！
１．「s3://my-dbt-docs-bucket/」はご自身のS3のURLに変更してください。
２．secrets.AWS_ACCESS_KEY_IDとsecrets.AWS_SECRET_ACCESS_KEY関しては以下の手順でAWSの情報を登録してください。

🔧 シークレットの登録手順：

1. GitHubリポジトリのページへ移動
2. Settings → Secrets and variables → Actions を選択
3. New repository secret をクリック
4. Name に AWS_ACCESS_KEY_ID を入力
5. Secret にキーの実際の値（AWS IAMのアクセスキー）を入力
6. 保存


次に、TROCCOワークフローの設定になります。
TROCCOワークフローを開いたらHTTPリクエストをクリックします。
すると下の画像になります。ここでは、名前・URL・HTTPメソッド・HTTPリクエストボディ・HTTPヘッダを入力していきます




記入項目	説明
名前	自由
URL	https://api.github.com/repos/<アカウント名>/<リポジトリ名>/dispatches の形で入力 <>の部分は自分の環境に合うように設定
HTTPメソッド	POSTを選択
HTTPリクエストボディ	{“event_type”: “trocco”} の形で入力 troccoの部分はGitHub Actionsのtypeで設定した値を入力
HTTPヘッダ	この中には二種類のキーと値を入力 １．キー：Accept　 　　値：application/vnd.github.everest-preview+json ２．キー：Authorization　 　　値：Bearer <GitHubのPAC(personal access tokens)> acceptの値に関してはそのまま入力すればok Authorizationの値はBearer の後にGitHub上で生成したトークンの値 を入力する必要がある（下の画像：トークン取得画面） ※トークンに必要な権限としてrepoの項目を選択しておく必要があるので注意 　また、トークン生成の画面がわかりにくいところにあるので注意 　（右上のアイコン > Setting > Developer setting > Tokens (classic)からいけます）

ここまで入力出来たらワークフローに配置していきます。
このワークフローでは３で作成したdbtジョブを実行した後に、dbtドキュメントを生成する流れで作っていきます。作成したのが下の画像のワークフローになります。



このワークフローを実行した上で、S3に出力されたドキュメントファイルを何らかのサーバー（例：静的Webホスティング環境など）でホストすることで、下の画像のようなドキュメントをWeb上で閲覧できるようになります。



今回の内容は以上です。


dbtのドキュメントを生成するには少し工夫が必要ですが、dbt buildなどなら少ない設定ででき、とても便利でした。
TROCCOとdbtはとても親和性が高いツールだと思うのでぜひ使ってみてください！！