dbt Postgresアダプター: 基本構成とローカル検証

Analytics Engineer試験では、アダプターごとの接続定義（profiles.yml）やローカルでの検証フローを正しく理解しているかが問われます。本稿ではPostgresアダプターを題材に、確実に通る基本構成と“落ちない”動作確認のコツをまとめます。

扱う内容は公式ドキュメントの安定仕様に基づき、実務でもそのまま使える形に絞っています。

Postgresアダプターの位置づけ

dbt-postgresは、PostgreSQLに対してdbtのモデル（SELECT）をテーブルやビューとしてデプロイし、テストを実行するための公式アダプターです。接続はprofiles.ymlに定義し、dbt runやdbt testなどのCLIコマンドは他アダプターと同一です。

試験観点では、type: postgres、dbname・schema・threadsなどの主要キー、接続確認コマンド（dbt debug）、および秘密情報のenv_var化が確実に問われます。

• インストール: pip install dbt-postgres
• プロファイル必須キー: type, host, user, password, port, dbname, schema, threads
• ローカル検証の起点: dbt debug（接続とプロファイルを検証）

インストールとバージョン確認（例: Unix系シェル）

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install dbt-postgres

dbt --version

ローカルPostgresの用意と接続確認

ローカル検証はDockerでPostgresを起動すると安全・確実です。開発用に専用のDBとスキーマを用意し、dbtユーザーに作成権限を与えます。ポートはデフォルト5432を使います。

起動後はpsqlで接続確認をすると切り分けが容易です。dbtの前に“DB自体に入れるか”を確かめます。

• 永続化: ボリュームを使ってデータを保持
• 初期化: POSTGRES_USER/POSTGRES_PASSWORD/POSTGRES_DBで最低限の環境を用意
• 接続確認: psql -h localhost -U dbt -d analytics

ローカル検証の構成

docker-compose.yml（最小例）

version: '3.8'
services:
  postgres:
    image: postgres:15
    container_name: pg_local
    environment:
      POSTGRES_USER: dbt
      POSTGRES_PASSWORD: dbtpass
      POSTGRES_DB: analytics
    ports:
      - "5432:5432"
    volumes:
      - pgdata:/var/lib/postgresql/data
volumes:
  pgdata:

profiles.ymlの基本構成（dbt-postgres）

dbtは~/.dbt/profiles.yml（または環境変数DBT_PROFILES_DIRで指すパス）を読み込み、接続情報を解決します。Postgresではdbnameとschemaが重要で、schemaはターゲットごとに分けるのが安全です。

秘密情報はenv_varで外出しします。threadsは開発マシンに合わせて控えめに設定します。sslmodeなどの任意キーは要件に応じて追加します。

• type: postgres（アダプター識別）
• dbname: 接続先データベース名（例: analytics）
• schema: デプロイ先スキーマ（dbtが自動作成可・権限要）
• threads: 同時実行数（ローカルなら2〜4程度から）
• search_path: 既定スキーマの探索順（必要に応じて）
• env_varの利用: {{ env_var('PGUSER') }} など

~/.dbt/profiles.yml（例・環境変数を使用）

nicheelab_project:
  target: dev
  outputs:
    dev:
      type: postgres
      host: {{ env_var('PGHOST', 'localhost') }}
      user: {{ env_var('PGUSER', 'dbt') }}
      password: {{ env_var('PGPASSWORD', 'dbtpass') }}
      port: {{ env_var('PGPORT', '5432') | int }}
      dbname: {{ env_var('PGDATABASE', 'analytics') }}
      schema: analytics_dev
      threads: 4
      search_path: public
      sslmode: prefer

dbt_project.ymlと最小モデル・テスト

プロジェクト名とprofile名を一致させ、models配下に最小のモデルとテストを用意します。シードを使うと、外部依存なくテストデータをロードできるためローカル検証が安定します。

Postgresでは各モデルは基本的にトランザクション内で実行され、失敗時はロールバックされます。materializedは必要に応じてview/tableを選びます。

• dbt init後にdbt_project.ymlを調整
• シードCSVで小さく始めると動作確認が速い
• テストはnot_null/uniqueなどの汎用テストから

最小構成例（複数ファイルを1つに併記）

# dbt_project.yml
name: 'nicheelab_project'
profile: 'nicheelab_project'
version: '1.0.0'
model-paths: ['models']
seed-paths: ['data']
models:
  nicheelab_project:
    +materialized: view
seeds:
  nicheelab_project:
    +schema: analytics_dev

# data/customers.csv
id,name
1,Alice
2,Bob

# models/stg_customers.sql
select
  cast(id as integer) as customer_id,
  name
from {{ ref('seed_customers') }}

# models/schema.yml
version: 2
seeds:
  - name: customers
    config:
      alias: seed_customers
models:
  - name: stg_customers
    columns:
      - name: customer_id
        tests:
          - not_null
          - unique

ローカル検証の手順とよくある出力

まずdbt debugでプロファイルと接続を確認します。次にdbt seedでCSVをロードし、dbt runでモデルをデプロイ、dbt testでテストを実行します。すべてを一括で行うならdbt buildが便利です。

プロファイルの場所を切り替える場合は--profiles-dirを使います。権限不足（CREATE SCHEMA不可）や接続拒否（ポート/ホスト誤り）はこの段階で明確になります。

• 順序の目安: debug → seed → run → test（またはbuild）
• 成功基準: All checks passed!、n models, m tests, k passed等の要約
• 失敗時の切り分け: psqlでの接続可否とスキーマ権限を個別確認

代表的なコマンド（Unix系シェル）

# 接続確認
dbt debug

# シードをロード
dbt seed

# モデルを実行（ビュー/テーブル作成）
dbt run

# テストを実行
dbt test

# すべてを順序よく一括実行
dbt build

# プロファイルの場所を明示する場合
dbt debug --profiles-dir ./profiles

他アダプターとの違いと試験対策ポイント

接続定義のキーや概念はアダプターごとに一部異なります。Postgresではdbnameとschemaが中心で、ウェアハウスやロール切替といった概念は登場しません。SnowflakeやDatabricksでは別の必須キーや権限モデルがあるため、試験では各アダプターの“最低限の相違点”を押さえます。

共通して重要なのは、profiles.ymlの正しい型（type）、機密情報のenv_var化、dbt debugでの事前検証、そしてターゲットごとのスキーマ分離です。

• Postgres: dbname+schemaが核。CREATE SCHEMA権限が無いと初回で失敗
• Snowflake: account/warehouse/database/schemaなど。ロールとウェアハウスの選定が重要
• Databricks: http_path/host/tokenなどのHTTP接続。Unity Catalog/カタログ-スキーマの階層

ターゲット切替の例（一時的にprodでビルド）

# profiles.ymlのtargetを変更せずに一時上書き
dbt build --target prod

問題で確認

よくある質問