如何将dbt项目从dbt-postgres迁移至dbt-databricks

要将现有dbt-postgres项目迁移到dbt-databricks且无需重写核心模型，核心是利用dbt的跨适配器兼容设计，仅需调整配置并适配少量语法差异，具体步骤如下：

1. 安装dbt-databricks适配器 #

在你的dbt环境中安装Databricks官方适配器：

pip install dbt-databricks

如果用requirements.txt管理依赖，添加dbt-databricks==<最新版本号>即可。

2. 配置Databricks连接信息 #

在dbt的profiles.yml文件中新增Databricks的连接配置（与原有postgres配置并存）：

databricks_demo:
  target: dev
  outputs:
    dev:
      type: databricks
      catalog: your_unity_catalog_name  # 对应Postgres的database
      schema: your_schema_name          # 对应Postgres的schema
      host: your_databricks_workspace_host  # 格式示例：adb-xxxxxx.xx.azuredatabricks.net
      http_path: your_cluster_http_path      # 从Databricks集群页面"高级选项"复制
      token: your_personal_access_token      # 在Databricks workspace中生成的访问令牌

替换上述配置中的占位符为你的Databricks环境实际信息即可。

3. 适配Postgres与Databricks的语法差异 #

大部分dbt通用语法（如{{ ref() }}、{{ var() }}、基础SELECT/INSERT逻辑）无需修改，仅需处理少量Postgres专属语法，通过条件宏实现跨环境兼容：

数据类型兼容 #

比如Postgres的jsonb类型，Databricks推荐用STRING或JSON类型，在项目的macros/目录下创建cast_jsonb.sql宏：

{% macro cast_jsonb(column_name) %}
  {% if target.type == 'databricks' %}
    cast({{ column_name }} as string)
  {% else %}
    {{ column_name }}::jsonb
  {% endif %}
{% endmacro %}

之后模型中用{{ cast_jsonb('your_column') }}代替硬编码的::jsonb即可。

聚合/窗口函数兼容 #

Postgres的string_agg函数在Databricks中需用concat_ws+collect_list替代，创建对应的宏：

{% macro string_agg(column, delimiter) %}
  {% if target.type == 'databricks' %}
    concat_ws('{{ delimiter }}', collect_list({{ column }}))
  {% else %}
    string_agg({{ column }}, '{{ delimiter }}')
  {% endif %}
{% endmacro %}

模型中直接调用{{ string_agg('user_name', ', ') }}即可跨环境生效。

特定对象处理 #

• 物化视图：如果模型用了Postgres的materialized类型，Databricks也支持materialized_view materialization，只需保留模型的config(materialized='materialized_view')配置，dbt-databricks会自动适配语法。
• 索引：Databricks湖仓会自动优化数据存储，无需手动创建索引，若模型中有Postgres专属的索引创建宏，添加条件判断跳过Databricks环境：

  {% macro create_index(table_name, column) %}
    {% if target.type != 'databricks' %}
      create index if not exists idx_{{ column }} on {{ table_name }}({{ column }});
    {% endif %}
  {% endmacro %}
  

4. 验证迁移效果 #

• 切换到Databricks目标环境运行管道：

  dbt run --target databricks_demo
  

• 运行测试确保数据一致性：

  dbt test --target databricks_demo
  

• 生成并查看文档，确认模型依赖关系正常：

  dbt docs generate --target databricks_demo
  dbt docs serve
  

可选：利用Databricks特性优化 #

迁移完成后，可无需修改模型，直接启用Databricks专属特性：

• 增量模型默认支持merge策略，保持原有incremental配置即可享受Databricks的增量更新优化；
• 通过profile中的catalog配置，利用Unity Catalog实现跨环境的权限与数据资产管理。

内容的提问来源于stack exchange，提问作者Derik Roby