ToolJet 3.0.0 Local Data Sources 迁移指南：从停用背景到四步实操的完整数据源迁移方案

ToolJet 3.0.0 Local Data Sources 迁移指南从停用背景到四步实操的完整数据源迁移方案【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet从 ToolJet 3.0.0 开始Local Data Sources本地数据源即 app 级数据源已被彻底移除。它们在前序版本中已被标记为废弃deprecated到 3.0.0 版本则完全停止支持。升级之后凡是连接到 Local Data Sources 的查询都会显示错误提示。本文以官方迁移指南为主线结合 ToolJet 仓库中的实体定义与数据迁移脚本带你理解 Local Data Sources 为何消失、升级后会遇到什么现象并逐步完成查询从旧数据源到新Data Sources全局数据源的迁移确保应用在升级后依然正常工作。背景什么是 Local Data Sources为什么被移除在 ToolJet 的数据模型里data_sources表通过scope字段区分数据源的作用范围。从实体定义可以看到Column({ type: enum, enumName: scope, enum: [local, global], default: local }) scope: string;scope global全局数据源Global Data Source工作区级别的连接可在多个应用间共享受细粒度权限管控是 ToolJet 的正常形态scope local本地数据源 / App-Level Data Source早期遗留的、绑定在单个应用具体到某个 app version上的连接。代码中称之为local界面中称之为 app 级。正如 server/src/modules/data-sources/AGENTS.md 所总结的App-Level Data Source — legacy per-app connection,scope local(code says local, UI says app-level)且当前代码路径中已经没有任何新逻辑会创建 local 作用域的数据源。这意味着 Local Data Sources 是纯遗留产物它把连接信息、凭据与某个应用版本强绑定无法跨应用复用也给权限管理与环境隔离带来额外复杂度。因此 ToolJet 在早期版本将其标记为废弃并在 3.0.0 中彻底移除支持。升级到 3.0.0 后会发生什么根据官方升级文档 docs/versioned_docs/version-2.50.0-LTS/setup/upgrade-to-v3.md 和 docs/versioned_docs/version-2.50.0-LTS/setup/cloud-v3-migration.md这两个文档均包含 Local Data Sources 小节并指向本迁移指南如果你还没有把 local data sources 迁移为 global data sources升级后会遇到一个错误提示说明 local data sources 已不再受支持。具体到编辑器界面升级后打开应用Query Manager查询管理器中原本连接到 Local Data Sources 的查询会显示错误信息并且除了错误提示之外查询的其他内容配置、选项等都会被隐藏。这就是需要执行迁移的信号。四步迁移指南第 1 步识别报错的查询进入你之前使用 Local Data Sources 的应用展开Query Manager查找显示与 Local Data Sources 相关错误信息的查询。这些查询只会显示错误提示其余内容都会被隐藏。第 2 步创建新的数据源导航到Data Sources部分创建一个同类型的新数据源例如之前用的是 PostgreSQL Local Data Source就创建一个 PostgreSQL Data Source填写正确的必填信息并保存新数据源。新创建的数据源默认是工作区级的全局数据源scope global这意味着它可以在多个应用中复用后续同一连接只需配置一次。第 3 步重新连接查询回到之前使用 Local Data Sources 的应用打开显示报错的查询在Source字段下会看到一个下拉框从下拉框中选择刚刚创建的同类型数据源查询即完成重连并可正常使用。第 4 步测试查询运行每一个更新过的查询确认一切按预期工作。完成上述四步后应用中的所有查询都已从 Local Data Sources 平滑迁移到新的 Data Sources不会再出现 Local Data Source is no longer supported 之类的错误。源码级原理迁移背后的数据模型与自动化整合脚本理解了操作步骤之后我们再深入仓库看看迁移在底层是如何运作的。这能帮你判断哪些数据源需要手动迁移、哪些会被自动整合。数据源的三层分类type、scope、kind从 server/src/entities/data_source.entity.ts 的实体定义type字段以及 server/src/modules/data-sources/AGENTS.md 的领域术语说明中可以梳理出如下分类体系typestatic | default | sample表示数据源的创建方式scopelocal | global表示作用域即本文迁移的核心维度kind连接器标识插件名例如restapi、runjs、runpy、tooljetdb、workflows。其中Static/Default Data Source是每个工作区自动存在的内置连接kind属于DefaultDataSourceKindsrestapi、runjs、runpy、tooljetdb、workflows每个工作区每种 kind 一行命名形如${kind}default如restapidefault且不允许用户编辑选项。静态本地数据源的自动化整合对于type static且scope local的本地数据源ToolJet 通过数据迁移脚本自动完成整合无需手动操作server/data-migrations/1745318714733-DeprecateLocalStaticDataSources.tsDeprecate Local Static Data Sources——逐组织、逐应用版本扫描data_sources表中type static AND scope local的记录按kind分组为每种 kind 保留一条主数据源将其更新为scope global、app_version_id NULL、organization_id指向当前组织将同 kind 的其他重复数据源 ID 对应的data_queries.data_source_id全部改指向这条主数据源UPDATE data_queries SET data_source_id $1 WHERE data_source_id ANY($2)删除重复的数据源记录完成去重与收敛。重要提醒该迁移的down()方法明确输出警告——No down migration available for data consolidation即这是一次不可逆的数据整合如需回退只能从备份恢复。server/data-migrations/1745409452884-AddMissingStaticDataSources.tsAdd Missing Static Data Sources——校验每个组织是否都具备 5 种必需的静态数据源restapi、runjs、runpy、tooljetdb、workflows缺失的按${kind}default命名补齐并为每个环境app_environments写入对应的data_source_options记录。server/data-migrations/1745409631920-AddDataSourceConstraintsForStatic.tsAdd Data Source Constraints For Static——从数据库约束层面固化静态数据源必须全局化的规则添加检查约束chk_static_type_global_scopeCHECK (type ! static OR scope global)即 static 类型的数据源不允许再以 local 作用域存在添加部分唯一索引idx_unique_static_kind_org(kind, type, organization_id) WHERE type static保证每个组织内每种静态数据源唯一。非静态本地数据源通过 changeScope 单向迁移对于用户自建的非静态本地数据源例如示例中的 PostgreSQL Local Data Source则通过服务层的能力完成从 local 到 global 的单向迁移。调用链为控制器 server/src/modules/data-sources/controller.ts 暴露POST contenteditable="false">【免费下载链接】ToolJetOpen-source foundation of ToolJet AI - the enterprise app generation platform for internal tools, dashboards, business applications, workflows and AI agents. Build visually, from a prompt, or from Claude Code, Codex and Cursor over MCP 项目地址: https://gitcode.com/GitHub_Trending/to/ToolJet创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考