3. dbt 项目初始化与云数仓连接

dbt 本身不存储数据，它是一层“编译 + 调度 + 元数据管理”的转换引擎，真正执行 SQL 的是云数仓。因此项目初始化的核心任务只有两件：让 dbt 能跑起来，让 dbt 能安全地连上仓库。前者靠安装适配器，后者靠 profiles.yml 与凭证管理。这一节我们把这两件事拆开讲清楚，并给出可复现的验证方法。

一、安装：dbt Core 与适配器是两件事

dbt 采用“核心 + 适配器”的插件式结构。dbt-core 提供 CLI、编译、依赖解析、状态管理等通用能力；具体到某个云数仓（Snowflake、BigQuery、Databricks、Redshift、PostgreSQL 等），需要安装对应的适配器包，例如 dbt-snowflake、dbt-bigquery、dbt-databricks。适配器决定了 profiles.yml 里能写哪些字段、支持哪些物化方式、如何生成平台方言的 SQL。

推荐用独立虚拟环境隔离依赖，避免不同项目的适配器版本互相污染：

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install --upgrade pip
pip install dbt-core dbt-snowflake
dbt --version

dbt --version 会同时打印 core 版本与已安装适配器版本。这里有一个容易踩的坑：适配器版本必须与 dbt-core 主版本兼容。例如 dbt-core 1.8 应搭配 dbt-snowflake 1.8.x，混装 1.7 适配器可能在解析 profiles.yml 时报字段未知。若团队使用 dbt Cloud，则无需本地安装适配器，但 profiles.yml 的字段语义仍然一致，理解它依然必要。

二、profiles.yml：连接信息的唯一入口

dbt 通过 profiles.yml 找到“连哪个仓库、用哪个库/模式、以什么身份登录”。它默认放在 ~/.dbt/profiles.yml，也可以通过环境变量 DBT_PROFILES_DIR 指向项目内目录，便于团队统一管理。文件结构是“profile 名 → target 名 → 连接参数”，而项目里的 dbt_project.yml 通过 profile: 字段引用这个 profile 名，两者必须对得上。

# ~/.dbt/profiles.yml
analytics:
  target: dev
  outputs:
    dev:
      type: snowflake
      account: "xy12345.ap-southeast-1"
      user: "dbt_svc_dev"
      role: "TRANSFORMER_DEV"
      database: "ANALYTICS_DEV"
      warehouse: "WH_XS_DEV"
      schema: "dbt_dev"
      threads: 4
      private_key_path: "~/.dbt/keys/dbt_svc_dev.p8"
      private_key_passphrase: "{{ env_var('DBT_KEY_PASSPHRASE') }}"
    prod:
      type: snowflake
      account: "xy12345.ap-southeast-1"
      user: "dbt_svc_prod"
      role: "TRANSFORMER_PROD"
      database: "ANALYTICS_PROD"
      warehouse: "WH_M_ETL"
      schema: "dbt_prod"
      threads: 8
      private_key_path: "~/.dbt/keys/dbt_svc_prod.p8"
      private_key_passphrase: "{{ env_var('DBT_KEY_PASSPHRASE') }}"

几个字段值得单独说明。target 决定默认使用哪个 output，日常开发用 dev，CI/CD 用 --target prod 切换。threads 控制并发执行的模型数量，不是越大越好：Snowflake 上 4～8 通常足够，过高会争抢 warehouse 资源并放大失败重试成本。schema 是 dbt 写入模型的目标模式，建议 dev 与 prod 严格隔离，避免开发误覆盖生产表。role 决定权限边界，应使用专用的转换角色，而不是账号默认角色。

三、凭证管理：不要把密码写进文件

把明文密码提交进 Git 是最常见的初始化事故。dbt 支持 {{ env_var('NAME') }} 在 profiles.yml 中读取环境变量，因此推荐两种做法：一是密钥对认证（Snowflake 的 private_key_path + private_key_passphrase），二是把敏感值放进环境变量或密钥管理服务，由 CI 在运行时注入。BigQuery 则通常使用服务账号 JSON 的 keyfile 路径或 method: oauth，同样应避免把 JSON 内容直接写进仓库。

四、验证连接与权限：从“能连”到“能建”

安装和配置完成后，不要直接跑全量模型，而应按“连接 → 权限 → 写入 → 读取”的顺序逐层验证。dbt 提供了几个轻量命令：dbt debug 检查 profile 解析、网络连通与认证；dbt run-operation 可执行自定义宏做更细的探测；dbt seed 或 dbt run 则验证真实写入能力。

dbt debug --profiles-dir ~/.dbt
# 期望看到：Connection test: OK connection ok

dbt run-operation current_role_and_grants
# 自定义宏内执行：select current_role(), current_database(), current_schema()

dbt seed --select raw_orders
# 验证能否在目标 schema 中创建表并写入数据

判断依据要具体：dbt debug 通过只说明认证与网络没问题，不代表有建表权限；dbt seed 成功才说明角色对目标 schema 具备 CREATE TABLE 与 INSERT 权限；随后用 select count(*) from analytics_dev.dbt_dev.raw_orders 确认数据可读。若 dbt debug 报 “Database Error: 250001”，通常是账号、角色或 warehouse 名称写错；若报权限类错误，则要检查角色是否被授予目标 database/schema 的 USAGE 与 CREATE 权限。

五、常见失败与定位顺序

初始化阶段的问题大多集中在三类。第一类是配置解析失败：dbt debug 直接报 “Could not find profile named 'analytics'”，说明 dbt_project.yml 的 profile: 与 profiles.yml 顶层键不一致，或 DBT_PROFILES_DIR 指向了错误目录。第二类是认证失败：账号、区域、角色拼写错误，或密钥对未正确注册到用户。第三类是权限不足：认证通过但 dbt seed 报 “Insufficient privileges”，此时应检查角色是否被授予目标 database 的 USAGE、schema 的 USAGE 与 CREATE TABLE，以及 warehouse 的 USAGE 与 OPERATE。

完成以上步骤后，你得到的不是一个“能跑”的项目，而是一个连接边界清晰、凭证不落盘、权限可验证的项目。后续所有模型开发、测试与部署，都建立在这条已验证的连接链路上。