dbt 專案初始化與資料庫連線設定

安裝好 dbt 後，第一步是初始化一個新的專案。dbt 提供了 init 指令來自動產生標準的目錄結構。

在終端機中，執行以下指令 (假設專案名稱為 my_dbt_project)：

dbt init my_dbt_project

這個指令會引導你進行一些基本設定，或者直接建立一個包含範例檔案的專案資料夾。

dbt 專案結構

進入剛剛建立的資料夾，你會看到以下結構：

my_dbt_project/
├── dbt_project.yml   # 專案的主要設定檔
├── models/           # 存放 SQL models 的地方 (最重要的目錄)
├── seeds/            # 存放 CSV 檔案 (透過 dbt seed 載入)
├── tests/            # 存放測試 SQL 的地方
├── analyses/         # 存放分析用的 SQL (不會被編譯成 table/view)
├── snapshots/        # 存放 snapshot 定義 (用於記錄歷史資料)
├── macros/           # 存放 Jinja macros
└── target/           # (自動產生) dbt 編譯與執行後的產出物

在這些檔案中，最重要的是 dbt_project.yml。它定義了專案名稱、版本、以及各個目錄的配置。

以下是一個標準的 dbt_project.yml 內容範例：

name: 'my_dbt_project'
version: '1.0.0'
config-version: 2

# 這個名稱很重要，必須跟 profiles.yml 裡面的名稱對應
profile: 'my_dbt_project'

# 這是 dbt 尋找 models 的路徑
model-paths: ['models']
analysis-paths: ['analyses']
test-paths: ['tests']
seed-paths: ['seeds']
macro-paths: ['macros']
snapshot-paths: ['snapshots']

target-path: 'target' # 編譯後的檔案存放位置
clean-targets: # dbt clean 會清除的目錄
  - 'target'
  - 'dbt_packages'

# 設定 models 的配置
models:
  my_dbt_project:
    # 這裡設定專案內所有 model 的預設值
    # 例如：預設所有 model 都會實體化為 view
    +materialized: view

    # 也可以針對特定子目錄設定
    # 例如：models/staging/ 下的 model 預設使用 ephemeral
    staging:
      +materialized: ephemeral

設定 profiles.yml

dbt 的設計哲學是將「專案程式碼」與「敏感連接資訊」分開。

• dbt_project.yml：包含專案邏輯，通常會 commit 到 git。
• profiles.yml：包含資料庫連線資訊 (帳號、密碼)，絕對不應該 commit 到 git。

profiles.yml 在哪裡？

預設情況下，dbt 會在你的使用者家目錄下的 .dbt/ 資料夾中尋找 profiles.yml：

• MacOS / Linux: ~/.dbt/profiles.yml
• Windows: C:\Users\YourUser\.dbt\profiles.yml

如果在執行 dbt init 時，你已經依照提示輸入連線資訊，dbt 可能已經幫你建立好這個檔案了。如果沒有，你需要手動建立。

編輯 profiles.yml (以 PostgreSQL 為例)

打開或建立 ~/.dbt/profiles.yml，並加入以下內容：

# 這個名稱必須與 dbt_project.yml 中的 'profile:' 設定一致
my_dbt_project:
  target: dev # 預設使用的環境 (可以切換 dev, prod 等)
  outputs:
    dev:
      type: postgres
      host: localhost # 資料庫位址
      user: my_user # 資料庫使用者
      password: my_password # 資料庫密碼
      port: 5432 # PostgreSQL 預設 port
      dbname: my_database # 資料庫名稱
      schema: dbt_alice # dbt 輸出的預設 schema (建議每個人用不同的)
      threads: 4 # 執行緒數量 (並行執行的 model 數)

    prod:
      type: postgres
      host: prod-db-host
      user: prod_user
      password: prod_password
      port: 5432
      dbname: my_database
      schema: analytics # 生產環境通常是統一的 schema
      threads: 8

驗證連線設定 (dbt debug)

設定好 profiles.yml 後，我們可以使用 dbt debug 指令來測試連線是否成功。

在專案目錄下執行：

dbt debug

如果一切設定正確，你應該會看到類似以下的輸出：

...
Configuration:
  profiles.yml file [OK found and valid]
  dbt_project.yml file [OK found and valid]

Required dependencies:
 - git [OK found]

Connection:
  ...
  Connection test: [OK connection ok]

All checks passed!

看到 All checks passed! 就代表你的 dbt 專案已經成功連接到資料庫，可以開始開發了！

如果連線失敗，請檢查：

1. 資料庫服務是否已啟動？
2. 帳號密碼是否正確？
3. schema 設定的名稱是否合法 (dbt 會自動嘗試建立該 schema，但需要有 CREATE SCHEMA 權限)。