dbtプロジェクトをチームで運用していると、レビュー時に毎回指摘するパターンが出てきます。「このモデルに主キーが定義されていない」「テスト無しのモデルが追加されている」「descriptionが空のカラムがある」。これらをレビュアーが手動でチェックするのは消耗する。dbt-checkpointは、これらをpre-commit hookとして自動強制するOSSだ。
30以上のチェックが用意されており、組織のdbt品質ルールをコミット時に強制できます。基本構造と運用設計を整理します。
主要なチェック群
| カテゴリ | 代表的なチェック |
|---|---|
| schema.yml | check-model-has-properties-file, check-model-columns-have-desc |
| 主キー | check-model-has-tests-by-name（unique, not_null） |
| テスト | check-model-tags, check-script-has-no-table-name |
| ref/source | check-script-ref-and-source, check-source-has-meta |
| 命名規約 | check-model-name, check-column-name |
| materialization | check-model-has-materialization |
セットアップ
# .pre-commit-config.yaml
repos:
- repo: https://github.com/dbt-checkpoint/dbt-checkpoint
rev: v2.0.6
hooks:
- id: check-model-has-properties-file
name: Check that models have schema.yml entries
- id: check-model-columns-have-desc
name: Check that all columns have descriptions
- id: check-model-has-tests-by-name
name: Check that models have unique and not_null tests on PK
args: ["--tests", "unique", "not_null"]# インストールと初回実行
pip install pre-commit
pre-commit install
pre-commit run --all-filesこれで`git commit`時に自動的にチェックが走り、違反があるとコミットが拒否されます。組織として「ルールを守るのが当たり前」の状態を、ツールが強制する。
CIでの強制
pre-commit hookは開発者のローカル環境で動くので、人によっては無効化できます。確実に強制するには、CI（GitHub Actions、GitLab CI等）でも実行します。
# .github/workflows/dbt-quality.yml
name: dbt-checkpoint
on: [pull_request]
jobs:
checkpoint:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.11'
- run: pip install pre-commit
- run: pre-commit run --all-filesPRが上がるたびに自動チェックが走り、違反があるとマージできない状態にできます。これで「ルールが守られている」が組織の標準となる。
段階的な導入アプローチ
- ステップ1：チームで「最低限のルール」（主キー必須、description必須など）を合意
- ステップ2：既存プロジェクトの「現状の違反」を許容範囲に設定し、新規・変更分のみ強制
- ステップ3：既存違反を計画的に解消（warningで通知し続けて意識を高める）
- ステップ4：違反が解消されたら、フルチェック（既存も含めた強制）に移行
- ステップ5：必要に応じて追加ルール（命名規約、tag必須等）を加える
最初から全部強制すると、既存プロジェクトでは膨大な違反が出てチームが疲弊します。「新規分から始める」「既存は段階解消」の進め方が現実的だ。
dbt-osmosisとの併用
dbt-osmosis（自動整形）とdbt-checkpoint（強制）は組み合わせやすい構成です。CIで以下の順番で実行する運用が典型的です。
- 1. dbt-osmosisでschema.ymlを自動整形・description継承
- 2. dbt-checkpointで残った違反を検出
- 3. dbt run / test で機能テスト
osmosisで自動修正できるものは自動修正し、checkpointで人による対応が必要な違反だけ通知する、というレイヤー分けで運用負担を下げられる。dbt-osmosisの詳細はdbt-osmosis とはを参照してください。
運用上のハマりどころ
- 厳しすぎるルールで開発が止まる：全項目を「最初からエラー」にすると、開発スピードが落ちる。warning→error の段階運用。
- 既存違反の数：レガシープロジェクトに導入すると違反が膨大。–all-files ではなく差分だけチェックする運用も検討。
- dbt本体バージョンへの依存：dbt-checkpointはdbtの内部構造に依存。dbtメジャーバージョン更新時に挙動確認。
- カスタムルールの管理：プロジェクト独自ルールを追加すると保守コストが増える。30+の標準ルールでカバーできる範囲を優先。
向く・向かない場面
- 向く：dbtプロジェクトをチームで運用、レビューでの品質指摘が多発、組織としての品質基準を強制したい、CI/CD文化がある
- 向かない：個人開発・少人数（数名）の信頼関係で運用、品質ルールが流動的で固められない、CI環境を持っていない
まとめ
- dbt-checkpointはpre-commit hookとして動くdbt品質強制ツール。
- schema.yml整備、主キー必須、テスト必須など30+のチェックが用意されている。
- pre-commit hookに加えてCIでも強制すれば、組織として確実に守れる。
- dbt-osmosisとの併用で「自動修正＋強制」のレイヤー運用が組める。
- 段階導入（新規分から、既存違解解消、フル強制）が現実的。
全体像はdbt周辺ツール選定、隣接はdbt-osmosis とは・SQLMesh vs dbt。dbt周辺の運用設計の壁打ちは、DE-STKの初回相談（30分・無料）もご利用ください。
よくある質問（FAQ）
Q. SQLFluffとの違いは？
A. SQLFluffはSQLのリンター（フォーマット・構文チェック）で、dbt-checkpointはdbtプロジェクトの構造ルール（schema.yml有無、テスト有無等）をチェックします。役割が違うので、両者を併用するのが一般的です。SQLFluffで「SQLの書き方」を整え、dbt-checkpointで「dbt運用ルール」を強制する、というレイヤー分けです。
Q. 開発者がpre-commitを無効化したらどうする？
A. CIで同じチェックを動かすのが鉄則です。ローカルのpre-commitは「開発者の利便性」、CIは「組織の品質保証」。CIで違反があればマージできない、という運用なら、ローカル無効化されても最終的に違反は混入しません。
Q. 既存違反が大量にあるプロジェクトでも導入できる？
A. できます。「変更分だけチェック」モード（–from-ref、–to-ref）を使えば、PRで変更したファイルだけを対象にできます。既存違反は計画的に解消する別タスクとし、新規変更で違反を増やさない、という運用が現実的です。
Q. カスタムチェックは作れる？
A. Pythonで作れますが、組織独自のロジックを増やすと保守負担が増えます。「標準30+のチェックで何ができないのか」を明確にしてから、カスタムが本当に必要かを判断します。多くのケースは標準ルールの組み合わせと設定で対応できます。