ToolJet 数据库外键Foreign Key完整指南约束、动作与引用完整性实战【免费下载链接】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导读外键Foreign Key是 ToolJet 内置数据库ToolJet Database中用于连接两张表、保证数据一致性的核心约束机制。本文基于 ToolJet 官方文档并结合前端表单实现与后端服务源码系统讲解在 ToolJet 数据库编辑器中创建外键关系的完整流程、四类更新/删除动作Restrict、Cascade、Set NULL、Set to Default的行为差异、引用完整性的底层保障以及一张表可同时建立多条外键等进阶用法。读完本文你将能在 ToolJet 数据库 UI 中熟练设计多表关联并理解外键约束背后的校验规则与源码实现。什么是外键关系外键关系Foreign Key Relation是指将当前表Source源表中的一个或一组列与已存在的其他表Target目标表中的一个或一组列进行关联。这一关系在两张表之间建立连接使源表可以引用目标表的数据。在 ToolJet 数据库中当你在源表中创建或编辑表结构时可以添加一条或多条外键每条外键都指向另一张已存在表中具备唯一约束的列。创建外键关系时你还可以为源行选择当目标行被更新或删除时执行的动作Action相关选项的完整说明见下文外键动作一节。从源码角度看ToolJet 数据库服务层通过 tooljet-db-table-operations.service.ts 中的createForeignKey方法执行外键创建内部最终调用 TypeORM 的createForeignKeys生成 PostgreSQL 的FOREIGN KEY ... REFERENCES约束并在成功后通过NOTIFY pgrst, reload schema通知 PostgREST 重新加载 schema使新约束立即生效。Constraints约束条件在 ToolJet 数据库中创建外键关系时必须满足以下三个约束条件数据类型匹配目标表中被引用的列必须与源表中建立外键的列具有相同的数据类型。目标列必须具备 Unique 约束目标表中被引用的列必须显式设置 Unique 约束也包含主键列因为主键天然具备唯一性。目标表必须已存在添加外键关系之前目标表必须先创建完成即在源表上建立外键时无法引用一张尚不存在的表。在 UI 层上述约束被编码为类型过滤逻辑在 TableKeyRelations.jsx 中目标列下拉列表会根据源列的数据类型动态过滤仅展示数据类型匹配的候选列源列为integer时可匹配目标表的integer或serial列源列为bigint时可匹配integer或bigint其余类型则要求完全一致。Limitations限制除了约束条件ToolJet 数据库对外键还有以下限制不允许自引用目标表和源表不能是同一张表。serial 类型列不能作为源表的外键列无法用源表中数据类型为serial的列创建外键。不能引用复合主键的组成部分目标表中作为其复合主键Composite Primary Key一部分的列不能被外键引用。前端源码与上述限制一一对应。在 TableKeyRelations.jsx 中源列下拉列表将serial、boolean、timestamp with time zone、jsonb类型的列标记为禁用isDisabled无法选为外键源列。而后端在createForeignKey中会调用 checkIfForeignKeyReferencedColumnsAreFromCompositePrimaryKey遍历目标表的列约束若目标列属于由多个列组成的复合主键则抛出ConflictExceptionForeign key cannot be created as the referenced column is in the composite primary key.从服务端再次拦截。此外创建外键时源表需至少有一列满足必填字段要求且数据库中至少要有两张表目标表加源表否则 UI 上的 Add relation按钮会处于禁用状态并给出对应的 tooltip 提示相关判断见 ForeignKeyRelation.jsx。Exception例外有一条值得注意的例外规则源表中数据类型为integer的列可以引用目标表中数据类型为serial的列。这在前端源码中得到印证在 TableKeyRelations.jsx 的过滤逻辑中当sourceColumn.dataType integer时允许的目标列类型为integer或serial。serial本质上是 PostgreSQL 基于序列sequence生成的整数自增列因此从值域上看与integer兼容。Creating Foreign Key创建外键在创建或编辑表此时该表即为源表时你可以添加一条或多条外键分别引用其他已存在表目标表的列。创建外键关系的步骤如下创建或编辑一张表该表将作为源表。在Foreign key relation区域点击 Add relation按钮打开右侧外键配置抽屉。Source源从下拉菜单中选择要建立外键的列。源表默认为当前正在创建/编辑的表且已通过数据类型过滤禁用不可用的列。Target目标从下拉菜单中选择目标表再从该表的下拉菜单中选择被引用的列。目标列列表会随目标表的切换而重新加载调用viewTable接口拉取目标表列信息且同样经过数据类型匹配过滤。Actions动作选择目标行被更新或删除时源表行应执行的动作。点击Create按钮创建外键关系。提示在目标表的下拉菜单底部有一个进入 ToolJet 数据库页面的入口源码中通过getPrivateRoute(database)打开数据库主页面方便你跳转到目标表确认列定义。创建成功后源表的外键关系列表会以源列 → 目标表.目标列的形式展示每条关系旁都有编辑图标点击可修改目标表、目标列或动作编辑已有外键关系时如果更改了目标表或目标列界面会弹出确认对话框提示更新外键关系将先删除当前约束再添加新约束对应后端updateForeignKey先dropForeignKey再createForeignKeys的实现见 tooljet-db-table-operations.service.ts确认后才会提交变更。删除外键关系同样需要二次确认。Foreign Key Actions外键动作创建外键关系时ToolJet 数据库允许你为目标行被更新或删除时源行执行什么操作选择动作。On Update 与 On Delete 各有四个选项前端在 TableKeyRelations.jsx 中维护了onUpdateOptions与onDeleteOptions两个选项列表RESTRICT、CASCADE、SET NULL、SET DEFAULT且抽屉打开时会默认选中第一项RESTRICT。On Update目标行更新时选项说明Restrict默认若目标表中的某行被其他源行引用则禁止对该目标行执行更新。Cascade目标行中的引用值更新后源表中引用该值的行会同步更新。Set NULL目标行中的引用值更新后源表中引用该值的列会被置为 NULL。Set to Default目标行中的引用值更新后源表中引用该值的列会被重置为源表外键列的默认值。On Delete目标行删除时选项说明Restrict默认若目标表中的某行被其他源行引用则禁止删除该目标行。Cascade目标行被删除后源表中引用该值的行会一并被删除。Set NULL目标行被删除后源表中引用该值的列会被置为 NULL。Set to Default目标行被删除后源表中引用该值的列会被重置为源表外键列的默认值。这些动作在创建外键时以 JSON 形式提交到后端字段名为on_delete与on_update见 ForeignKeyRelation.jsx 中handleCreateForeignKey构造的请求体最终由createForeignKeys生成对应的 PostgreSQLON UPDATE/ON DELETE子句。实际使用中最常见的组合是On Delete 选择 Restrict以防止误删被引用的主数据同时配合On Update 选择 Cascade让主键值变更自动同步到所有关联子表。Referential Integrity引用完整性外键约束的核心价值在于保证源表与目标表之间的引用完整性Referential Integrity它强制源表中的外键列只能取目标表外键列中存在的唯一值之一。ToolJet 数据库在 UI 层面提供了三层保障新增行时在源表新增一行、操作外键列时该列会以下拉框形式展示目标表中存在的唯一值确保新增数据与目标表保持一致。编辑行时在源表编辑已有行的外键单元格时下拉框同样只展示目标表中的唯一值保证更新后的数据始终与目标表一致。快捷跳转下拉框底部提供Open referenced table按钮点击可直接跳转到目标表便于核对引用数据。需要注意的是当插入或更新的值违反了外键约束例如引用了目标表中不存在的值或在 Restrict 动作下删除仍被引用的目标行时ToolJet 数据库会拒绝该操作并返回约束违规错误前端会以 toast 形式提示具体失败原因。这一点与后端createForeignKey对 PostgreSQL 错误码如42710表示外键约束已存在的处理逻辑对应见 tooljet-db-table-operations.service.ts。完整示例Orders 与 Customers 表下面通过一个电商场景演示如何为Orders订单与Customers客户表建立外键关系。首先在 ToolJet 数据库中创建以下两张表Customers目标表列名数据类型主键非空唯一customer_idint✅✅✅namevarchar❌✅❌emailvarchar❌✅✅Orders源表列名数据类型主键非空唯一order_idint✅✅✅customer_idint❌✅❌order_datevarchar❌✅❌total_amountfloat❌✅❌两张表的结构满足外键约束条件Orders.customer_id与Customers.customer_id数据类型一致均为int目标列Customers.customer_id同时具备主键与唯一约束主键天然唯一目标表Customers先于外键创建存在。现在我们希望在Orders.customer_id与Customers.customer_id之间建立外键关系定义外键关系编辑Orders表。在Foreign key relation区域点击 Add relation按钮。在Source区域选择customer_id列。在Target区域选择Customers表和它的customer_id列。选择目标动作例如RESTRICT以防止删除仍有关联订单的客户。保存变更点击Save Changes按钮创建外键关系。此后每当向Orders表插入或更新记录时customer_id的值必须对应Customers表中已存在的customer_id值同时由于 On Delete 选择了 Restrict你无法删除仍被订单引用的客户记录。这样就能确保订单永远关联到一个有效的客户从而维护数据的完整性与一致性。外键的进阶用法与底层原理一条外键关联多个目标列外键并不局限于单列。ToolJet 数据库支持一个外键关系同时引用目标表的一组列后端在 prepareForeignKeyDetailsJSON 及 TypeORMTableForeignKey构造中均以数组形式处理referenced_column_names前端请求体也使用column_names/referenced_column_names数组结构见 ForeignKeyRelation.jsx为多列复合外键预留了能力。一张表多个外键创建/编辑表时你可以为不同的源列分别添加多条外键关系每条关系独立引用不同的目标表。前端foreignKeyDetails状态以数组维护多条关系handleCreateForeignKey通过[...prevValues]追加新关系后端createForeignKey同样接收foreign_keys数组并一次性批量创建见 controller.ts。外键操作的后端调用链从一次完整的外键创建操作来看其调用链为前端 ForeignKeyRelation.jsx 组装column_names、referenced_table_name、referenced_column_names、on_delete、on_update并调用tooljetDatabaseService.createForeignKey服务端 controller.ts 接收请求将操作委托给tableOperationsService.perform(organizationId, create_foreign_key, params)tooljet-db-table-operations.service.ts 校验目标表存在、复合主键限制后在事务中执行createForeignKeys随后NOTIFY pgrst, reload schema刷新 schema 缓存。其中create_foreign_key、update_foreign_key、delete_foreign_key等操作标识集中定义在 constants/index.ts与前端表单的增、改、删三种操作一一对应。修改已有外键关系的本质是先删旧约束、再建新约束因此 UI 才会在变更目标列或目标表时弹出二次确认。相关文档主键Primary Key约束外键通常引用主键列建议先掌握主键的定义方式。表操作Table Operations表的创建、编辑与字段类型定义。数据库编辑器Database EditorToolJet 数据库的整体界面与数据浏览方式。查询 ToolJet 数据库建立外键后可在查询中利用关联关系进行 Join 查询。【免费下载链接】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），仅供参考