無料ではじめる dbt 入門 (3) | プロジェクトの作成と初期設定（SQL Server編）

本記事では、dbt-sqlserver のインストールが完了した状態から、最初の dbt プロジェクトを作成し、SQL Server に接続するための設定と初期動作の確認方法までを丁寧に解説します。

はじめに：この章でできること
ステップ1：新しい dbt プロジェクトの作成
ステップ2：データベース接続設定（SQL Server 用）
ステップ3：接続確認と初期動作チェック
ステップ4：初期モデルの作成と実行
ステップ5：プロジェクト設定ファイルの理解（dbt_project.yml）
複数環境（dev/prod）対応を意識した設定管理のヒント
ステップ6：以後の開発の準備
まとめ：dbt プロジェクトの基盤ができたら、次はモデル開発へ

はじめに：この章でできること

この記事を終えると、以下のことができるようになります：

dbt init を使って新しい dbt プロジェクトを作成
SQL Server 用の接続設定（profiles.yml）の記述
最初のモデルを作って dbt run で実行確認
プロジェクト設定ファイル（dbt_project.yml）の基本構成の理解
SQLクエリ（データモデル）の情報ファイル（schema.yml）の基本構成の理解

ステップ1：新しい dbt プロジェクトの作成

まずは、dbt のプロジェクトを作成します。作成するには次のことを忘れずに実行してください。

dbt をインストールした Python の仮想環境を有効化する
Python の仮想環境をインストールしたフォルダに移動する（ここに dbt プロジェクトも作成する）

こうすることで Python の仮想環境と dbt を同時に管理することができます。

この記事では前回の記事で作成したユーザーのホームディレクトリ下の “my_project_root” フォルダの下に dbt プロジェクト（my_dbt_project）を作成します。コマンドプロンプトで以下を実行します。

C:\>cd:\C:\Users\foo\my_project_root

C:\Users\foo\my_project_root>.venv\Scripts\activate.bat

(.venv) C:\Users\takas\my_project_root>dbt init my_dbt_project

dbt init の実行

実行すると、いくつか対話形式の質問が表示されます。後で修正が必要なのですが、一応以下の内容で入力しておきます。

データベースの選択：　ここでは sqlserver を選択
データベースのホスト名：　SQL Server のホスト名を入力
ポート番号：　SQL Server は通常 “1433”
ユーザ名：　SQL Server にアクセスするユーザ名
パスワード：　上記ユーザのパスワード
データベース名：　SQL Server上のデータベース名を入力
スレッド数：　ここではデフォルトの “1”

プロジェクトフォルダ構成の確認

作成直後のフォルダは図のようになります。

このうち models/example/ はチュートリアル用のサンプルです。不要であれば削除して構いません。

ステップ2：データベース接続設定（SQL Server 用）

dbt init を実行して対話形式の質問に答えると、データベースへの接続設定ファイルが自動的に作成されます。

しかし、SQL Server を利用する場合、自動生成された接続設定ファイルでは dbt は正常に動作しない ため、自分で修正する必要があります。

どちらかと言えば、修正するよりも上書きしてしまった方が混乱が少ないので、作成されたファイルは名前を変更した上で、ここで紹介する内容のファイルを新規で作成することをお勧めします。

接続設定ファイルの保管場所

接続設定ファイルは dbt の共通設定ファイルで、全プロジェクト共通で使用されます。

ファイルはユーザー（ここでは foo ）のホームディレクトリ下の “.dbt” というフォルダの “profiles.yml” という名前で保管されています。

もしこのファイルがなければ自分で作成します。

C:\Users\foo\.dbt\\profiles.yml

SQL Server 向けの設定項目の具体例

以下は SQL Server への接続設定のサンプルです。

WIndows 認証用

Windows 認証で SQL Server に接続する場合の設定です。

既に SQL Server 上にご自分のログインID がユーザとして登録されている必要があります。更に、テーブル作成やビュー作成の権限も設定されている必要があります。

my_dbt_project:
  outputs:
    dev:
      database: my_db
      driver: ODBC Driver 17 for SQL Server
      port: 1433
      schema: dbo
      server: Your_Host_Name\sqlexpress
      trust_cert: true
      type: sqlserver
      windows_login: true
  target: dev

database：使用する SQL Server のデータベース名
driver：　お使いのPCにインストールされている ODBC ドライバを記載します
schema：　デフォルトでモデルが作成されるスキーマ。SQL Server のデフォルトスキーマは “dbo” です。
server：　SQL Server が動いているサーバ名。SQL Server Express を利用している場合は後ろに \sqlexpress を加えます。
trust_cert：　ローカル開発環境で TLS 証明書を省略したいときに true
type：　SQL Server に接続するので “sqlserver”
windows_login：　Widows 認証で SQL Server に接続する場合の設定です。“true” に設定します。

SQL Server 認証用

SQL Server で独自にユーザーを作成している場合の設定です。

user 行と password 行をご自分の利用するIDに合わせて編集してください。

my_dbt_project:
  outputs:
    dev:
      database: my_db
      driver: ODBC Driver 17 for SQL Server
      port: 1433
      schema: dbo
      server: Your_Host_Name\sqlexpress
      trust_cert: true
      type: sqlserver
      user: Your_User_ID
      password: Your_Password
  target: dev

ODBC ドライバの確認とトラブル時のヒント

PCにインストールされている ODBC ドライバは PowerShell で以下のコマンドを実行することで確認できます。

>Get-OdbcDriver

「ODBC Driver 17 for SQL Server」または「ODBC Driver 18 for SQL Server」が表示されていない場合は、Microsoft 公式サイトからダウンロードしてインストールしてください。

ステップ3：接続確認と初期動作チェック

接続設定ファイルの作成が完了したら、まずは dbt が SQL Server に接続できるかを確認しましょう。

dbt のプロジェクトフォルダに移動して dbt debugを実行します。

(.venv) C:\Users\foo\my_project_root\my_dbt_project>cd C:\Users\foo\my_project_root\my_dbt_project

(.venv) C:\Users\takas\my_project_root\my_dbt_project>dbt debug

成功した場合は、図のように接続成功のメッセージとともに「All checks passed!」と表示されます。

ステップ4：初期モデルの作成と実行

以下のような簡単な SQLクエリを models フォルダの下の test.sql として保存して実行してみましょう。

SELECT  
  1 AS sample_id,  
  'dbt works!' AS message

dbt で以下のコマンドを実行することで SQL Server に test という名前のビュー（またはテーブル）が作成されます。

(.venv) C:\Users\takas\my_project_root\my_dbt_project>dbt run --select test

上手くいきましたでしょうか？

これが上手くいったということは dbt で SQLクエリを書いたものがデータベース上に反映できたということになります。

これからどんどん SQLクエリを開発していくことができます。

しかし、その前にもう少しだけ SQLクエリ開発のための知識の習得と、準備作業をしておきましょう。

ステップ5：プロジェクト設定ファイルの理解（dbt_project.yml）

dbt プロジェクトフォルダ直下にある dbt_project.yml は、モデルの出力先や命名規則などを管理する設定ファイルです。

モデルの保存先の指定

dbt_project.yml の一番最後はデフォルトでは以下のようになっていると思います。

# In this example config, we tell dbt to build all models in the example/
# directory as views. These settings can be overridden in the individual model
# files using the `{{ config(...) }}` macro.
models:
  my_dbt_project:
    # Config indicated by + and applies to all files under models/example/
    example:
      +materialized: view

最終行の +materialized: の設定が view になっているので、dbt 上で作成したSQLクエリはデータベース上でビューとして作成されます。

その他に以下の形式で保存が可能です。

table

dbt run を実行した時点のSQLクエリの出力結果がテーブルとして作成されます。

実行時間が長い重たい処理の場合は、毎回SQLクエリを実行するよりも一回実行した結果をテーブルに保管して参照する方が速い処理ができるようになります。

半面、リアルタイム性が失われるのでデータの特性に応じて使い分けると良いでしょう。

incremental

前回の dbt run 実行時からの差分を追加する動作になります。非常に大きなデータを処理する場合に向いています。

ephemeral

これはデータベース上は何も変化せず、dbt 上でSQLクエリとして保管されるのみです。これを使った最終段のクエリから活用されることになります。

複数環境（dev/prod）対応を意識した設定管理のヒント

profiles.yml 側で dev, prod のような複数の outputs を用意すれば、–target オプションで環境を切り替えて実行できます：

(.venv) C:\Users\takas\my_project_root\my_dbt_project>dbt run --target prod

開発・本番のデータベースやスキーマを分けておくことで、事故や上書きミスを防げます。

ステップ6：以後の開発の準備

Staging・Mart フォルダ構成の準備

後々のモデル構造を整理するため、以下のように models/ の中に staging/ や marts/ を用意しておくと良いでしょう：

models/  
├── staging/  
├── marts/

これらに応じて dbt_project.yml にもネームスペース設定を追加できます。

参照するテーブルと作成する SQLクエリの情報ファイルの初期ひな形を作っておく

本格的に SQLクエリの開発をしていくには、主に以下の3つの情報を models/ 以下の SQLクエリと同じフォルダに schema.yml ファイルとして保存する必要があります。

実テーブル参照用の情報（⇒ 依存関係図作成のため）
作成する SQLクエリのドキュメント用の情報（⇒ ドキュメント作成のため）
作成する SQLクエリのテスト用の情報（⇒ テスト実行のため）

ここでは簡単なサンプルを紹介します。これを参考にひな形のファイルを作成してみてください。

version: 2

sources:         # 実テーブルを参照するための情報
  - name: my_db  # データベース論理名　実際のデータベース名にしておくと混乱しない
    schema: dbo  # SQL Server のスキーマ名（例: dbo）
    tables:
      - name: sales # 参照する実テーブルの名前
        description: "売上テーブル（生データ）" # テーブルの説明文（ドキュメントに出力される）

models:             # 作成する SQLクエリ に関する情報
- name: test_model  # SQLクエリの名前
    description: "テスト用の単純なモデル" # SQLクエリの説明文（ドキュメントに出力される）  
    columns:                       # この下に列の情報が入る
    - name: sample_id              # 列名
        description: "サンプルID"  # 列の説明文（ドキュメントに出力される）  
        tests:                     # この下にテストの条件を記述する
        - not_null                 # 列 sample_id に null が含まれないことをテストする。null があるとエラーが出力される。

まとめ：dbt プロジェクトの基盤ができたら、次はモデル開発へ

ここまでで、dbt プロジェクトの初期構築と SQL Server への接続、基本モデルの実行まで完了しました。次は、実際の業務データを活用したモデルの作成、テストやドキュメントの整備といった実践的な開発に進んでいきましょう。

次の記事では、モデル作成・テスト・ドキュメントの具体的な方法をご紹介します。