从dbt Core v1迁移到Snowflake上的dbt v2实践指南

一份实用指南，介绍如何为现有 Snowflake dbt 项目做好迁移到 v2 的准备、验证兼容性，以及处理静态分析中的缺口。

dbt v2 于 2026 年 9 月 16 日正式可用（dbt Labs 的公告），将以“Fusion”为代号开发的引擎带入了 dbt 的产品化版本。

当我开始研究将一个现有的 Snowflake dbt 项目 迁移到 v2 需要做些什么时，我原本以为引擎变更本身会是困难的部分。但后来变得更重要的其实是准备工作：先让项目在 v1 上就绪，在切换前检查兼容性，并把有文档记录的迁移指引与你在过程中可能发现的环境和 SQL 小问题区分开来。

本文聚焦于这条实用的迁移路径。

读完本文后，你将了解：

• dbt v1 与 dbt v2 之间的核心架构变化
• dbt v2 带来的新增内容，包括静态分析和性能改进
• dbt Labs 推荐的迁移顺序——先在 v1 上准备，然后切换，再进行验证
• 切换后值得检查的一个 Snowflake SQL 兼容性缺口

TL;DR

对于现有的 Snowflake dbt 项目，迁移路径是：

升级到 dbt v1.12 → 解决弃用项并检查包兼容性 → 运行 dbt parse --use-v2-parser → 切换到 dbt v2 → 编译并测试项目。

关键在于把 v1.12 用作准备步骤，而不是把迁移当作直接替换包来处理。切换之后，静态分析还可能暴露出 v1 未标记出的仓库特定 SQL，因此要验证整个项目，并把解析器限制与实际的 Snowflake 运行时问题区分开来。

迁移路径一览

实际发生变化的是什么

在 dbt v1 中，工具链被拆分为两个独立版本化的包：dbt-core（Python 引擎——Jinja 渲染、DAG 解析、CLI）以及每个仓库对应的独立适配器包，例如 dbt-snowflake。它们按照各自的发布节奏发布，并通过定义的适配器接口进行协调，因此核心引擎与仓库适配器之间的兼容性需要作为 v1 设置的一部分来管理。

dbt v2 将其合并为单个包。根据 dbt Labs 的说法，“所有 v2 适配器都通过 Arrow Database Connectivity (ADBC) 标准连接到数据仓库，而非基于 Python 的适配器库”（升级到 v2）。对于 Snowflake 来说，这意味着无需安装或匹配版本的单独适配器包：

- dbt-core>=1.10,<1.11
- dbt-snowflake>=1.10,<1.11
+ dbt>=2.0,<3.0

dbt v2 还在 Jinja 渲染之外新增了第二个编译阶段：静态分析，它会在任何内容对仓库执行之前，为你的 SQL 构建并验证逻辑查询计划。正是这一点带来了列级血缘和更强的验证能力——也是本文末尾那条兼容性说明的来源。

为什么要迁移到 dbt v2？

这项迁移工作带来了有意义的改进。dbt v2 引入了本地 SQL 编译和静态分析，使得更多 SQL 错误及其下游影响能在查询到达 Snowflake 之前被识别出来。由于 dbt 不仅理解 SQL 本身，还理解项目图，这种分析还能支持列级血缘等能力，并有助于在开发周期更早阶段揭示变更的下游影响。

这个 基于 Rust 的引擎还旨在提升解析和编译性能，这在较大或高度定制化的 dbt 项目中能带来明显差异。dbt v2 还与 dbt State 集成，通过识别可以跳过的模型，或在适用情况下可以克隆而非重建的模型，帮助减少不必要的执行。

总体而言，这些变化可以缩短开发反馈循环，并在仓库执行之前捕获更多问题——随着开发者和编码代理更快地生成 SQL，这一点愈发有用。

推荐的迁移路径

dbt Labs 记录了一条将现有 v1 项目迁移到 v2 的具体顺序，值得按顺序执行，而不是直接跳到安装 v2。

1. 仍在 v1 上进行准备

起点不是你现在使用的 v1 版本——而是最新的版本。dbt Labs 对此说得很明确：

“准备迁移的最佳方式是先升级到 dbt v1.12（或 dbt 平台中的‘Latest’发布轨道）。”—— dbt Core v2 来了

v1.12 之所以重要，是因为它强制执行了在 v2 中变为必需的许多行为变更，并且它附带一个可选择性启用的标志，让你无需真正切换引擎就能测试 v2 的解析器。

一旦你升级到 v1.12，在真正接触 v2 之前，有三件事值得做：

• 解决弃用警告。 升级指南将此视为前提条件：“在升级到新引擎之前，必须解决所有弃用警告。”其中许多可以用 dbt-autofix 自动修复，这是 dbt Labs 专门为此发布的工具。
• 检查第三方包兼容性——通过每个包的 require-dbt-version 设置或 dbt 包中心上的 v2 兼容徽章。
• 在不切换引擎的情况下测试 v2 解析器，使用 v1.12 上可用的选择性启用标志：

dbt parse --use-v2-parser

这会“将解析委托给 v2 解析器，而不改变任何其他行为，使其成为一种低风险的早期捕获兼容性问题的方式”（升级到 v2）。趁你仍安全地处于 v1 上，修复它暴露出的所有问题。

2. 切换到 v2

dbt Labs 自己给出的准备就绪信号很直接：一旦解析器检查顺利通过，就安装 v2。

“运行 dbt parse --use-v2-parser 来试用它。如果你的项目成功，那就没问题了，你应该查看安装指南进行切换。”—— dbt Core v2 来了

对于全新环境，安装 dbt可通过 pip、Homebrew 或基于 curl 的安装方式完成。Homebrew/curl 会在任何 Python 环境之外安装一个自包含的二进制文件；pip 则将 dbt 作为 Python 包安装到当前激活的环境中。dbt Labs 自身更倾向于二进制安装，但 pip 也受到完全支持，并且如果你的工具链特别需要从 Python 环境中解析 dbt，那么 pip 就是正确的选择——例如，某些 IDE 集成会从项目的虚拟环境而非 $PATH 中选择 dbt。

对于现有的基于 pip 的环境，有一条实用提示：根据我们的迁移经验，我们建议重新创建虚拟环境，而不是将 dbt v2 叠加到已经包含 v1 Python 包的环境之上。这是一条实用建议，而非 dbt Labs 记录的迁移要求，它能为项目提供一个基于其声明依赖的干净、可复现的环境：

rm -rf .venv
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

3. 在 v2 上验证

切换后，运行完整的项目编译，而不仅仅是抽查——v2 更严格的解析会暴露 v1 从未检查过的问题，最好一次性看到全部问题。然后运行你实际的测试套件（dbt build 或 dbt test）以确认运行时行为，因为仅靠静态分析不会对仓库执行任何操作。

静态分析默认采用基线模式，在此模式下，发现的问题只是警告，而非导致构建失败的错误：

“即使编译器标记出无效或有问题的 SQL，你的项目仍可继续运行。”—— 关于静态分析

同一页面将不支持的 SQL 视为迁移中预期且正常的一部分，并请用户报告缺口，以便解析器得以改进。

一个值得检查的兼容性缺口

我们在验证过程中遇到的一个具体缺口：当 stage 参数以裸标识符形式传入时，dbt v2 的解析器尚未完全理解 Snowflake 的 GET_PRESIGNED_URL() 函数。这并非只是我们注意到的问题——dbt Labs 自己的 支持的 Snowflake 函数参考文档明确将 GET_PRESIGNED_URL 列为目前不支持类型检查。

Snowflake 的 语法文档将不带引号的形式作为标准示例展示：

GET_PRESIGNED_URL(@my_stage, 'path/to/file.csv', 3600)

文档仅说明当 stage 名称包含空格或特殊字符时才需要加引号。在实践中，将 stage 引用包裹在引号中可以满足 dbt v2 当前的解析器并消除警告，且不改变行为：

-- Compiles cleanly under dbt v2's current baseline static analysis
GET_PRESIGNED_URL('@my_stage', 'path/to/file.csv', 3600)

在我们的验证中，这表现为一种满足解析器的改动，而非运行时行为的改变：两种语法在对 Snowflake 执行时返回相同的预签名 URL，并且运行实际模型并获取生成的文件确认了它在运行时正确解析。

值得精确说明：这是针对 dbt v2 解析器当前覆盖范围的变通方法，而非 Snowflake 文档要求或官方 dbt 修复。如果你遇到类似情况，根据 dbt Labs 自身的指导，更好的长期做法是 提交一个 issue，并附上无法解析的具体 SQL。

实用建议

• 不要跳过 v1.12 这块垫脚石。 在仍使用 v1 时用 --use-v2-parser 进行测试，是一种低风险的发现兼容性问题的方式，dbt Labs 正是为此目的构建了它。
• 在切换 dbt-autofix 之前运行，而不是之后——它会自动处理许多弃用项。
• 对于现有的基于 pip 的设置，考虑重新创建虚拟环境，而不是将 v2 叠加到现有的 v1 环境之上。请将此视为实用的环境管理建议，而非 dbt Labs 的迁移要求。
• 切换后，编译整个项目并运行测试套件——而不仅仅是单个模型——并且不要假设静态分析警告就意味着 SQL 已损坏。在花时间做变通之前，先检查你使用的函数是否出现在 dbt 的 Snowflake 函数支持参考文档中。

结论

dbt Labs 记录的路径——在最新的 v1 版本上做好准备，在切换前用 v2 解析器进行验证，然后在 v2 上通过完整编译和测试运行进行确认——将原本可能充满风险的跳跃变成可预测、低波折的迁移。一个值得关注的领域是针对仓库特定函数的 SQL 理解覆盖范围。在默认的基线静态分析模式下，不受支持或有问题的 SQL 会以警告形式出现，而不一定会阻断构建，这让团队有机会将解析器缺口与实际运行时失败分开调查。

参考资料

• dbt v2 正式发布——dbt Labs 官方 GA 公告（2026 年 9 月 16 日）
• dbt Core v2 来了：依然开源，为未来而重建——推荐的 v1.12 优先迁移路径以及 --use-v2-parser 就绪检查
• 升级到 v2——官方升级指南：ADBC 适配器架构、弃用项解决要求、包兼容性
• 安装 dbt——dbt v2 的官方安装说明（pip、Homebrew、curl）
• 关于静态分析——基线模式与严格静态分析模式，以及针对不受支持 SQL 的指导
• dbt v2 支持的 Snowflake 函数——官方函数支持矩阵，每周更新
• dbt-autofix——dbt Labs 官方工具，用于自动化 v1 到 v2 的弃用项修复
• dbt Fusion GitHub Issues——报告 dbt v2 解析器尚不支持的 SQL 的官方渠道
• Snowflake: GET_PRESIGNED_URL——官方语法参考

从 dbt Core v1 到 Snowflake 上的 dbt v2：实用迁移指南最初发表于 Snowflake Builders Blog: Data Engineers, App Developers, AI, & Data Science，在 Medium 上，人们通过高亮并回应这个故事来继续对话。