これは dbt での開発時(Pull Request 作成時)に SQL の Lint を行う GitHub Actions を構築するためのサンプルです。 SQL の Lint には sqlfluff を採用しています。
- dbt Core / dbt Cloud
- GitHub Actions
- sqlfluff が対応している DWH
本システムはダミー環境を用意する必要があります。今後対応ダミー環境を増やしていく予定ですが、コントリビュートも歓迎です。
- BigQuery
- Snowflake
- Amazon Redshift
- Azure Synapse Analytics
システムの構築図は以下のようになります。
sqlfluff で dbt のテンプレートを使用するため、dbt を CI 環境にインストールします。 また、dbt で SQL のコンパイルを行うためには BigQuery に接続する必要があります。
SQL のコンパイルにはテーブルへのアクセスは行いませんが、CI 環境から本番環境の GCP プロジェクトに接続できない様にしました。 そのため、プロジェクト単位でダミー環境を作成してください。
OSS 名 | ライセンス |
---|---|
dbt-bigquery | Apache-2.0 |
sqlfluff | MIT |
reviewdog | MIT |
以下の手順で CI 環境を構築します。
CIの認証を通すためのダミー環境を作成します。 この環境は認証以外では使いません。
自由に作成してください。 ここでは公式ドキュメントの手順をご紹介します。
Google Cloud 公式ドキュメントの ホーム > Apigee > ドキュメント > ガイド の手順でプロジェクトの作成を行います。
Bigquery の Cloud Console を利用できない場合は ホーム > BigQuery > ドキュメント > ガイド の手順で BigQuery API を有効にしてください。
google-GitHub-actions/auth を利用して行います。
発行したサービスアカウントキーを Google Cloud 外部で利用することは、鍵の漏洩リスクがあります。今回は、そのリスクを回避しつつ GCP の認証を行うことができる Workload Identity 連携を利用します。
google-github-actions/auth の README にある Setting up Workload Identity Federation の手順で設定を行います。
Actions secrets に WORKLOAD_IDENTITY_PROVIDER と SERVICE_ACCOUNT を登録することで動作するようにしたのでこれらを設定します。
GitHub Docs の GitHub Actions > Security guides > Encrypted secrets の手順で Actions secrets の登録をしてください。
WORKLOAD_IDENTITY_PROVIDER には projects/123456789/locations/global/workloadIdentityPools/my-pool/providers/my-provider
のような値を設定します。
SERVICE_ACCOUNT には my-service-account@my-project.iam.gserviceaccount.com
のような値を設定します。
Reviewdog は Linter の結果に修正箇所があった場合、Pull Request の該当する箇所に違反や修正内容をコメントしてくれます。 Reviewdog にコメントさせるため、GitHub の Personal access token を利用します。
GitHub Docs の Authentication > Account security > Create a PAT の手順で Personal access token を作成してください。
その後、Personal access token を Actions secrets で REVIEWDOG_GITHUB_API_TOKEN として登録をしてください。
dbt プロジェクトを作成する dbt init コマンドを実行し、そこにリント設定を行ったものがこのレポジトリです。後ほど紹介するファイルを dbt プロジェクト内に配置することで動作させることができます。
本番環境で利用している DWH に合わせて設定をします。 sqlfluff 公式ドキュメントの Dialects Reference で対応環境の確認ができます。
Actions secrets で本番環境を DIALECT として登録をしてください。 BigQuery の場合は bigquery のように小文字で登録します。
$ git clone git@github.com:kazaneya/sqlfluff-dbt-starterkit.git new_repo
以下を dbt プロジェクトにコピーしてください。
.dbt/
.github/
.sqlfluff
.sqlfluffignore
.github/workflows/actions.yml の3行目をコメントアウトの指示に従って変更します。
変更前
on: [workflow_dispatch] # workflow_dispatch から pull_request に変更する
変更後
on: [pull_request]
.sql ファイルの変更がある Pull Request を作成すると自動的に動作します。 Reviewdog から Linter のエラー内容のコメントがあるとこの様になります。
下図では「L050」「L010」のルールについて指摘しています。 ルールの詳細はガイドラインを参照してください。
GitHub Actions で利用しているパッケージのバージョンは .github/requirements.txt で指定しています。パッケージを最新バージョンに保つために Dependabot を導入し、パッケージのアップデートがある場合に自動的に Pull Request が作成される仕様にしました。 Dependabot で作成された Pull Request で CI を動作させるために Actions secrets と同様の値を Dependabot secrets にも設定してください。
作成された Pull Request の CI の動作結果に応じて以下のような対応をしてください。
- CI が正常に動作した場合(または、エラーの解消ができた場合)
- デフォルトブランチにマージする
- CI がエラーになった場合
- マージはせずに原因を調査する(パッケージのバージョンによる依存関係でエラーになっている可能性が高いです)