---
title: "dbt Coreの使い方：インストールからprofiles.yml・dbt build・CIまでの手順【1.12対応】"
url: "https://www.issoh.co.jp/tech/details/19592/"
published: 2026-11-11
updated: 2026-11-11
categories: ["データベース"]
publisher: "株式会社一創"
---

# dbt Coreの使い方：インストールからprofiles.yml・dbt build・CIまでの手順【1.12対応】

dbt Coreの使い方は、2026年9月を境に入口が変わりました。`pip install dbt`で入るのはRustで作り直されたdbt v2で、従来のPython版を使うなら`dbt-core`を版指定で入れます。この記事では、2026年11月時点の公式ドキュメントとPyPIの実測をもとに、dbt-core 1.12系のインストール、`dbt init`とprofiles.ymlの設定、seedとrefによる最初のモデル、データテスト、`dbt build`と`--select`、変更分だけを回すCIまでを、コピーして動かせる形で整理しました。

## まとめ：dbt Coreは版を固定して入れ、dbt buildとCIで回すのが基本形

手元でdbt Coreを試すなら、Python 3.12前後のvenvに`dbt-core~=1.12.0`とアダプターを入れ、DuckDBで動かすのが最短です。DWHの契約もクラウドの権限も要りません。

版の固定は省けません。PyPIには2.0.0のリリース候補がすでに公開されており、正式版が出ると`pip install dbt-core`の中身がdbt OSS（v2系）に変わると公式ブログが予告しています。

日々の実行は`dbt run`ではなく`dbt build`を使い、テストに落ちたモデルの下流を止めます。プルリクエストでは`state:modified+`で変更分と下流だけを回すと、触っていないモデルの実行時間をCIから丸ごと省けます。

PostgreSQLを使っているなら当面は1.12系で続け、SnowflakeやBigQueryで新規に始めるならv2を検討する、という分け方が2026年11月時点の結論です。

## 2026年11月の3系統：dbt-core 1.12・dbt v2・dbt OSS

2026年11月時点のdbt Coreには、dbt-core 1.12・dbt v2・dbt OSSという3系統があります。

手順に入る前に、どのパッケージを入れるかを決めます。名前が似ているため、ここを曖昧にすると後で環境を作り直すことになります。

### pip install dbtで入るのはv2、dbt-core指定で入るのは1.12系

公式の[Install dbt](https://docs.getdbt.com/docs/local/install-dbt)は、dbtをインストールすると既定でdbt v2が入ると明記しています。2026年9月16日公開の[dbtとdbt OSSの違い](https://docs.getdbt.com/blog/comparing-dbt-and-dbt-oss)によれば、旧称Fusionエンジンが「dbt」、dbt Core v2が「dbt OSS」へ改称されました。PyPIで実測した3パッケージの違いは次のとおりです。

| パッケージ    | 最新版（2026-11-11時点）     | ライセンス         | アダプター      |
| -------- | --------------------- | ------------- | ---------- |
| dbt-core | 1.12.6（2.0.0rc10は候補版） | Apache 2.0    | 別途pipで導入   |
| dbt      | 2.0.11                | dbt独自の無償ライセンス | 実行時に自動取得   |
| dbt-oss  | 2.0.11                | Apache 2.0    | dbtリポジトリ参照 |

pipは既定で候補版を選ばないため、今日`pip install dbt-core`を実行すると1.12.6が入ります。正式版の2.0.0が出た時点でこの挙動は変わるので、手順書や`requirements.txt`には上限付きの版指定を書いておきます。旧Fusionエンジン（dbt v2）の仕組みとdbt-core 1.12系からの移行手順は[dbt Fusionとは：dbt v2になったRust製エンジンとCoreの違い・移行手順](https://www.issoh.co.jp/tech/details/19593/)で扱っています。

### 1.12系を選ぶ条件とv2へ進む条件はアダプターの対応で分かれる

[Upgrading to v2](https://docs.getdbt.com/docs/dbt-versions/dbt-upgrade/upgrading-to-v2)（2026年10月29日更新）がv2の対応アダプターとして挙げるのは、BigQuery・Databricks・Redshift・Snowflake・ClickHouse（非公開ベータ）・Apache Spark（CLIのみのベータ）・DuckDB（CLIのみ）です。PostgreSQLとSQL Serverは一覧にありません。

判断の軸は単純です。接続先が一覧に無い、Pythonモデルや社内マクロに古い書き方が多い、Apache 2.0以外のソフトウェアを社内規程で使えない、のどれかに当たれば1.12系を使います。公式ブログによると、1.13が機能を追加する最後のマイナー版で、セキュリティとインストールの修正は通常の1年を超えて3〜5年続く見込みです。急いで移る必要はありません。

## Python 3.10以上のvenv：dbt-core 1.12とアダプターの導入

ここからは1.12系の手順です。接続先には、ファイル1つで動くDuckDBを使います。

### venvの作成とdbt-duckdbの導入、2.0を避ける版指定のコマンド

dbt-core 1.12.6はPython 3.10以上が必須です。仮想環境を作り、[dbt-duckdb](https://github.com/duckdb/dbt-duckdb)と一緒に版を固定して入れます。

```
# 仮想環境を作って有効化する（Windowsは dbt-env\Scripts\activate）
python3 -m venv dbt-env
source dbt-env/bin/activate

python -m pip install --upgrade pip wheel setuptools
python -m pip install "dbt-core~=1.12.0" "dbt-duckdb~=1.11.0"

dbt --version
# Core: installed: 1.12.x ／ Plugins: duckdb: 1.11.x と出れば成功
```

`~=1.12.0`は「1.12.0以上1.13未満」を意味します。アダプターだけを入れてもdbt-coreは依存として入りますが、dbt-duckdbの依存指定は`dbt-core>=1.8.0`で上限がありません。dbt-coreの行を省くと、2.0.0の正式版が出た日に別物が入ります。

### DWHごとのアダプターパッケージと対応Python版の確かめ方

本番のDWHに合わせて、DuckDBの行を差し替えます。PyPIの分類子で確認した対応Python版は次のとおりです。

| 接続先        | パッケージ（最新版）           | 分類子のPython版 |
| ---------- | -------------------- | ----------- |
| DuckDB     | dbt-duckdb 1.11.1    | 3.10〜3.14   |
| PostgreSQL | dbt-postgres 1.11.0  | 3.10〜3.14   |
| BigQuery   | dbt-bigquery 1.12.2  | 3.10〜3.13   |
| Snowflake  | dbt-snowflake 1.12.5 | 3.10〜3.13   |

BigQueryとSnowflakeのアダプターは3.14を分類子に載せていません。チームで使う版はPython 3.12か3.13にそろえると、アダプターを足すときに詰まりません。版の確認は`python -m pip index versions dbt-snowflake`でも行えます。Snowflakeのキーペア認証やprofiles.ymlの固有設定は[dbtとSnowflakeの連携：キーペア認証の接続設定とdbt Projects on Snowflakeの使い分け【2026年版】](https://www.issoh.co.jp/tech/details/19597/)で解説しています。

## dbt init・profiles.ymlの接続設定とdbt debugの疎通確認

パッケージが入ったら、プロジェクトの雛形と接続設定を作ります。

### dbt initのフォルダとdbt\_project.ymlのprofile名の対応

[dbt init](https://docs.getdbt.com/reference/commands/init)は、プロジェクト名を受け取って雛形を作り、入っているアダプターの中から接続先を対話で選ばせます。

```
dbt init shop_dbt
cd shop_dbt
# 生成物: dbt_project.yml models/example/ seeds/ macros/ snapshots/ tests/ analyses/
```

押さえておくのは、`dbt_project.yml`の`profile: 'shop_dbt'`とprofiles.ymlの最上位のキーが一致していなければ接続できない、という1点です。CIなどで対話を避けたいときは`--skip-profile-setup`を付け、profiles.ymlを自分で書きます。`models/example/`のサンプルは動作確認が済んだら消してかまいません。

### profiles.ymlのtarget・outputsでdevとprodを分ける書き方

[About profiles.yml](https://docs.getdbt.com/docs/local/profiles.yml)によると、1.11以降のv1は`--profiles-dir`、環境変数`DBT_ENGINE_PROFILES_DIR`、旧名の`DBT_PROFILES_DIR`、カレントディレクトリ、`~/.dbt/`の順に探します。v2は環境変数とカレントディレクトリを見ず、プロジェクト直下と`~/.dbt/`だけを探す点が違います。

```
# ~/.dbt/profiles.yml
shop_dbt:
  target: dev
  outputs:
    dev:
      type: duckdb
      path: dev.duckdb
      threads: 4
    prod:
      type: duckdb
      path: "{{ env_var('DBT_DUCKDB_PATH') }}"
      threads: 8
```

`target`が既定の接続先で、`dbt build --target prod`のように実行時に切り替えます。`threads`は同時に処理するモデル数で、既定は4です。DuckDBは1ファイルへの書き込みを1プロセスが握るため、手元で別のツールが同じファイルを開いていると接続に失敗します。

### パスワードはenv\_varとDBT\_ENV\_SECRET\_で渡しリポジトリに置かない

SnowflakeやPostgreSQLのように認証が要る接続先では、profiles.ymlに資格情報を直書きしません。[env\_var](https://docs.getdbt.com/reference/dbt-jinja-functions/env%5Fvar)で環境変数から読み、名前を`DBT_ENV_SECRET_`で始めると、ログに値が出た場合も`*****`に置き換えられます。

```
    prod:
      type: postgres
      host: "{{ env_var('DBT_PG_HOST') }}"
      port: "{{ env_var('DBT_PG_PORT', '5432') | as_number }}"
      user: "{{ env_var('DBT_PG_USER') }}"
      password: "{{ env_var('DBT_ENV_SECRET_PG_PASSWORD') }}"
      dbname: analytics
      schema: dbt_prod
      threads: 4
```

環境変数は常に文字列なので、ポートのような数値は`as_number`で変換します。一方、`DBT_ENV_SECRET_`付きの変数にはフィルターを掛けられず、使える場所もprofiles.ymlとpackages.ymlに限られます。1.12からはカレントディレクトリの`.env`も自動で読まれるので、`.env`は必ず`.gitignore`に入れてください。設定が終わったら[dbt debug](https://docs.getdbt.com/reference/commands/debug)で、2つの設定ファイルの検証と接続テストをまとめて行います。

## 最初のモデルを作る：seed・ref・データテストでCSVから集計表まで

接続できたら、注文データのCSVから日別売上の表を作るところまで進めます。

### seedでCSVを読み込み、本番の生データはsources.ymlで宣言する

`seeds/raw_orders.csv`に次のCSVを置き、[dbt seed](https://docs.getdbt.com/reference/commands/seed)を実行するとテーブルとして読み込まれます。

```
order_id,customer_id,order_date,status,amount
1,101,2026-11-01,completed,4800
2,102,2026-11-01,returned,3200
3,101,2026-11-02,completed,12500
4,103,2026-11-02,pending,2100
```

seedは件数の少ないマスタや検証用の固定データ向けの機能です。本番では、FivetranなどのEL処理がDWHへ取り込んだテーブルを[sources](https://docs.getdbt.com/docs/build/sources)として`models/sources.yml`に宣言し、`{{ source('shop', 'orders') }}`で参照します。取り込み側との役割分担は[Fivetranとdbt統合後の構成](https://www.issoh.co.jp/tech/details/15954/)で解説しています。

### stagingとmartのSQLモデルをrefでつなぎ、materializedを決める

モデルはSELECT文を1ファイル1つ書くだけです。`ref`で上流を指定すると、dbtが依存関係を読み取って実行順を決めます。

```
-- models/staging/stg_orders.sql
select
    order_id,
    customer_id,
    cast(order_date as date) as order_date,
    status,
    amount
from {{ ref('raw_orders') }}

-- models/marts/fct_daily_sales.sql
{{ config(materialized='table') }}

select
    order_date,
    count(*)    as orders,
    sum(amount) as sales
from {{ ref('stg_orders') }}
where status = 'completed'
group by order_date
```

既定のmaterializedは`view`です。参照される回数が多い集計はtableにし、行数が増え続けるファクトはincrementalを検討します。stagingとmartの責務の分け方は[dbtのmarts層と3層の分け方](https://www.issoh.co.jp/tech/details/12323/)で詳しく扱いました。

### unique・not\_null・accepted\_valuesのYAMLテスト設定

schema.ymlに定義するのは、unique・not\_null・accepted\_valuesのテストです。[データテスト](https://docs.getdbt.com/docs/build/data-tests)はYAMLに数行足すだけで書けます。テストの入力値を`arguments:`の下に置く書き方は1.10.5以降で使え、v2では必須です。新しく書くなら最初からこの形にしておきます。

```
# models/staging/schema.yml
version: 2
models:
  - name: stg_orders
    columns:
      - name: order_id
        data_tests:
          - unique
          - not_null
      - name: status
        data_tests:
          - accepted_values:
              arguments:
                values: ['completed', 'returned', 'pending']
```

キー名は`data_tests:`が正式で、`tests:`は互換のために残っている別名です。1つのモデルに両方は書けません。列の型や必須項目を契約として固定したい場合は[データ契約とdbtの実装](https://www.issoh.co.jp/tech/details/16109/)、統計的な分布まで検査したい場合は[Great Expectationsの実装手順](https://www.issoh.co.jp/tech/details/16126/)が次の段階になります。

## dbt runとdbt buildの違い、–selectで実行範囲を絞るコマンド集

モデルとテストがそろったら、実行のしかたを決めます。

### dbt buildのDAG順：seed・model・testと失敗時の下流skip

`dbt run`はモデルだけを作り、テストは`dbt test`で別に流します。[dbt build](https://docs.getdbt.com/reference/commands/build)はseed・モデル・テスト・スナップショットをDAGの順に1回で処理し、上流のテストが落ちると下流のモデルを`SKIP`にします。

```
dbt build
# 1 of 6 OK loaded seed file main.raw_orders
# ...
# Done. PASS=6 WARN=0 ERROR=0 SKIP=0 TOTAL=6
```

`dbt run`と`dbt test`を順に流す運用では、`order_id`の重複を含んだまま集計表が作られ、そのあとでテストが失敗します。間違った数字が一度ダッシュボードに出てしまう分、`dbt build`の方が安全です。テストを止めずに警告だけ出したい列は、テストの`config`で`severity: warn`にします。

### –selectの+演算子とtag・pathで対象を絞る書き方の実例

[選択構文](https://docs.getdbt.com/reference/node-selection/syntax)を覚えると、開発中の待ち時間が大きく減ります。よく使う形を並べました。

```
dbt build --select stg_orders          # 1モデルとそのテストだけ
dbt build --select stg_orders+         # 下流も含める
dbt build --select +fct_daily_sales    # 上流も含める
dbt build --select models/marts        # フォルダ単位
dbt build --select tag:daily           # dbt_project.yml などで付けたタグ単位
dbt build --select fct_daily_sales --empty   # 0行で構文と依存だけ検証
```

`--empty`は`ref`と`source`を0行に置き換えてSQLを実行するため、大きなテーブルを読まずにコンパイルエラーと列名の誤りを見つけられます。v2では旧来の`--models`や`-m`がエラーになるので、手順書やスクリプトは今のうちに`--select`へ書き換えておきます。

### state:modified+と–stateで変更分だけを回すCIの組み方

[stateメソッド](https://docs.getdbt.com/reference/node-selection/methods)は、本番で最後に作った`manifest.json`と比べて、変更されたモデルを選びます。GitHub Actionsでの例です。

```
# .github/workflows/dbt-ci.yml
name: dbt-ci
on: pull_request
jobs:
  build:
    runs-on: ubuntu-latest
    env:
      DBT_ENV_SECRET_PG_PASSWORD: ${{ secrets.DBT_PG_PASSWORD }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - run: pip install "dbt-core~=1.12.0" "dbt-postgres~=1.11.0"
      - run: dbt deps
      # 本番ジョブが保存した manifest.json を prod-artifacts/ に取得しておく
      # リポジトリ直下の profiles.yml に CI 用の target「ci」を足しておく
      - run: dbt build --select "state:modified+" --state prod-artifacts --target ci --profiles-dir .
```

`+`を付けると、変更したモデルの下流まで作り直してテストします。公式ドキュメントは、`--state`と`--target-path`を同じ場所にしないよう注意しています。dbtが解析時に`manifest.json`を上書きし、比較が成り立たなくなるからです。比較元は`prod-artifacts/`のように別フォルダへコピーして持ちます。

## dbt Coreを本番で回す判断：実行基盤とdbt platformへ切り替える条件

手元で動いたあとに残る課題は、誰がいつ`dbt build`を実行するかです。

### cron・Airflowのdbt build実行とmanifest.jsonの保管先

dbt Coreにはスケジューラが付いていません。日次の更新なら、コンテナに上記のpip行を焼き込み、cronやクラウドのジョブ実行サービスから`dbt build --target prod`を呼ぶ構成で足ります。取り込み処理の完了を待つ必要がある場合や、失敗時の再実行を細かく制御したい場合は、Airflowなどのワークフローエンジンから呼びます。

見落としやすいのが成果物の保管です。実行のたびに`target/`へ出力される`manifest.json`と`run_results.json`をオブジェクトストレージへ保存しておかないと、前のh3のCIが比較元を失います。冪等に再実行できるパイプラインの組み方は[データパイプラインの設計判断](https://www.issoh.co.jp/tech/details/15848/)にまとめています。

### dbt Coreで続ける条件とdbt platformを選ぶ場面の分かれ目

dbt Coreで続けてよいのは、Gitとコンテナの運用に慣れたエンジニアが1人以上いて、モデルの実行が日次や時間単位のバッチで足りる場合です。ライセンス費用はかからず、実行基盤も既存のジョブ基盤に相乗りできます。

見送るのは、SQLは書けてもターミナルを使わないアナリストが開発の中心になる場合です。ブラウザ上のIDE、スケジューラ、ドキュメントの公開をdbt platformに任せた方が、実行基盤の保守に人を割かずに済みます。プランごとの費用を試算する際の参照先は、[dbt 料金の全体像](https://www.issoh.co.jp/column/details/19497/)です。取り込みからdbtの変換、BIまでを含めたデータ基盤の設計を任せたい場合は、一創の[データ分析基盤構築・MLOps構築支援](https://www.issoh.co.jp/service/ai/data-platform/)でご相談を受けています。

### v2移行に備えて今やる非推奨警告の解消とrequire-dbt-versionの見直し

1.12系で続ける場合も、移行の下準備は今から進められます。v2へ移る条件は、`dbt parse`で出る非推奨警告をすべて解消していることです。v2では未定義のマクロや変数が`dbt compile`ではなく解析の段階でエラーになり、使われていない設定パスも失敗扱いになります。

パッケージ側の準備も要ります。`packages.yml`で入れているパッケージの[require-dbt-version](https://docs.getdbt.com/reference/project-configs/require-dbt-version)が`">=1.10.0,<3.0.0"`のように2.0を含んでいるかを確かめてください。1.12で付いた`--use-v2-parser`フラグを使えば、移行前にv2の解析器で読めるかを試せます。

## よくある質問

dbt Coreを使い始めるときによく聞かれる質問に答えます。

### dbt Coreは無料で使えますか？

無料です。dbt-core 1.12系とdbt-ossはApache 2.0のオープンソースで、商用でも費用はかかりません。`pip install dbt`で入るv2もdbt Labsへの支払いは不要とされていますが、ライセンスはApache 2.0ではなく、dbt Mesh などの一部機能は有料のdbt platformと組み合わせて使います。費用が発生するのは接続先のDWHの利用料と、実行基盤のサーバー代です。

### dbt CoreはWindowsでも使えますか？

使えます。1.12系の手順はこの記事と同じで、違いはPython 3.10以上を入れたあとのvenvの有効化が`dbt-env\Scripts\activate`になる点だけです。v2はwingetやPowerShellのスクリプトでも導入できます。DuckDBを使う場合、ファイルを別のアプリで開いたままだとロックで接続に失敗するので、検証中はDBeaverなどのクライアントを閉じてから`dbt build`を実行してください。

### dbt Coreとdbt Cloudの使い方の違いは何ですか？

モデルのSQLやYAMLの書き方は同じで、違うのは実行と開発の環境です。dbt Coreはターミナルでコマンドを打ち、スケジュール実行やドキュメントの公開を自分で用意します。dbt Cloud（現在の名称はdbt platform）が提供するのは、ブラウザのIDEとジョブ実行の画面です。どちらを選ぶかの判断軸は[dbtとは：dbt Core・Cloudの選び方](https://www.issoh.co.jp/column/details/16548/)で整理しています。

### dbt runとdbt buildはどちらを使えばよいですか？

日常の実行と本番のジョブは`dbt build`を使ってください。テストが落ちたモデルの下流を作らないため、誤った集計が公開される前に止まります。`dbt run`が向くのは、テストを後回しにしてSQLの書き換えを素早く確かめたい開発中の場面です。その場合も`--select`で対象を1モデルに絞ると、待ち時間が短くなります。

### dbt Coreのバージョンアップはどうすればよいですか？

1.12系の中のパッチ更新は`python -m pip install --upgrade "dbt-core~=1.12.0" "dbt-duckdb~=1.11.0"`のように、上限を保ったまま実行する方法です。1.13へ上げるときは版指定を書き換え、開発用のtargetで`dbt build`が通ることを確かめてから本番に反映します。2.0への移行は非推奨警告の解消が先で、公式の移行ガイドには`dbt-autofix`という書き換え支援ツールも案内されています。

## 関連記事

- [dbtとは？ELTのTを担う仕組みとdbt Core・Cloudの選び方【2026年版】](https://www.issoh.co.jp/column/details/16548/)：dbtの仕組みと採用判断
- [dbtのmarts層とは？3層の分け方とMetricFlowで指標を定義する手順【dbt 1.12対応】](https://www.issoh.co.jp/tech/details/12323/)：モデルを増やす前のレイヤ設計
- [DuckDBの使い方：インストールからCLI・Python・ファイル読み込みまでの手順【1.5.6対応】](https://www.issoh.co.jp/tech/details/15377/)：検証に使うDuckDB自体の操作
- [Lightdash（ライトダッシュ）とは？dbtで指標を定義するOSS BIの料金・AI機能・導入手順【2026年版】](https://www.issoh.co.jp/tech/details/6478/)：dbtのモデルをそのまま見せるBI
- [ETLとは？仕組み・ELTとの違い・ツール選定から導入判断まで解説](https://www.issoh.co.jp/column/details/13364/)：dbtが担うTの位置づけ

---

出典: [dbt Coreの使い方：インストールからprofiles.yml・dbt build・CIまでの手順【1.12対応】](<https://www.issoh.co.jp/tech/details/19592/>)（株式会社一創）