ToolJet Database 主键完全指南单字段与复合主键的创建、修改和删除【免费下载链接】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主键Primary Key是 ToolJet Database 中唯一标识每条记录、保证数据完整性并支撑高效查询与索引的基石。本文以 ToolJet Database 的官方主键文档为主体完整讲解单字段主键与复合主键的创建流程、约束与限制以及主键的修改、删除操作并结合仓库源码前端编辑器与后端表操作服务深入剖析主键在底层是如何被校验和执行的。读完本文你将能在 ToolJet Database 编辑器中熟练设计符合业务需求的主键方案并理解为什么某些列不能设为主键、为什么被外键引用的表不能随意修改主键。ToolJet Database 中主键的定位ToolJet Database 是 ToolJet 内置的托管式数据库无需额外搭建即可在应用内直接维护数据表见 tooljet-database.md。在官方功能清单中主键被明确列为一项核心能力唯一标识每条记录确保数据完整性支撑高效的查询与索引作为外键关系的参照基础与其他表建立关联并维护引用完整性。从数据模型层面看ToolJet Database 底层基于 PostgreSQL通过 PostgREST 暴露为 RESTful API。当你通过数据库编辑器创建一张新表时系统会自动生成一个名为id、数据类型为serial的列并默认将其设为主键。serial类型用于生成连续的整数序列天然适合作为表的自增主键参见 />关于新建表时列配置抽屉中的Primary Key选项database-editor.md 做了补充说明该复选框可以将列设为主键且允许多列同时勾选以构成复合主键。因此单字段主键本质上就是复合主键在列数为 1 时的特例。约束Constraints主键列不能包含 NULL 值主键列的值在所有行中必须唯一。这两条约束共同保证了主键可以作为表中每一条记录的唯一标识符也是外键引用该列时引用完整性得以成立的前提。限制Limitations每张表必须至少有一个主键这是 ToolJet Database 的硬性要求因此你不能把一张表的主键全部取消而不指定新的主键列主键列不能使用 Boolean 数据类型。为什么 Boolean 不能设为主键Boolean 类型只有true、false以及null三种取值最多无法提供超过两个不同的非空值显然无法唯一标识大量记录。这一点在数据类型的约束兼容性表中得到了系统化体现根据>数据类型主键外键唯一非空serial✅❌✅✅varchar✅✅✅✅int✅✅✅✅bigint✅✅✅✅float✅✅✅✅boolean❌❌❌✅date with time❌❌❌✅jsonb❌❌❌✅从前端源码也可以印证这一限制在 ColumnForm.jsx 中当所选数据类型为boolean时会提示Foreign key relation cannot be created for boolean type column而主键的约束同样对 Boolean 关闭。也就是说主键候选列只能从上表允许的数值与字符串类型中选择。创建复合主键当单一列不足以唯一标识一条记录时ToolJet Database 允许你将多个列组合成一个复合主键Composite Primary Key通过多列取值的组合来唯一标识每条记录为数据建模提供更大的灵活性与控制力。操作步骤创建或编辑一张已有的表勾选多个列的 Primary 复选框将它们共同设为主键系统会自动为这些列添加主键约束组合成一个复合主键点击Save changes编辑表或Create新建表按钮提交。约束Constraints复合主键中的任何一列都不能包含 NULL 值所有复合主键列的值组合在每一行中必须唯一。注意与单字段主键的差异复合主键的唯一性是基于列组合判定的例如(a, b)为复合主键时(1, x)与(1, y)可以共存但(1, x)不能出现两次。限制Limitation复合主键中的列同样不能是 Boolean 数据类型。源码中的复合主键处理后端表操作服务在多个环节对复合主键进行了显式校验。例如在 tooljet-db-table-operations.service.ts 中创建外键时会抛出Foreign key cannot be created as the referenced column is in the composite primary key.——即外键不能引用目标表中属于复合主键组成部分的列这是复合主键带来的一个关键联动限制。此外在 tooljet-db-table-operations.service.ts 附近服务会遍历列约束并收集所有is_primary_key为真的列到pkColumnList用于后续的删除/更新/插入操作中定位记录这正是复合主键参与数据行定位的实现证据。修改主键表创建完成后你依然可以重新指定主键列前提是新选定的列必须满足主键约束如果该列已经包含数据则现有值必须满足非空且唯一的要求。此外有一个重要的联动限制如果目标表的主键正被其他源表作为外键引用则不能更新或修改该主键。这是因为修改被引用的主键会破坏引用完整性Referential Integrity——源表中的外键值将无法继续对应到有效记录。操作步骤编辑一张已有的表勾选你希望设为新主键的列的Primary复选框系统自动为该列添加主键约束取消勾选原主键列的 Primary 复选框原列的约束仍然存在但不再是主键点击Save changes保存。从源码层面看这一流程在后端会被解析为列约束变更在 tooljet-db-table-operations.service.ts 中服务会读取新旧列的constraints_type.is_primary_key标志并通过ALTER TABLE ... DROP CONSTRAINT/ADD CONSTRAINT之类的 DDL 同步到 PostgreSQL同时保证serial类型的自动生成逻辑不被破坏。值得注意的是主键列会自动隐式具备唯一性因此当某列既设为主键又勾选了 Unique 时服务端在生成约束时会用isUnique: is_unique !is_primary_key_column做去重处理见同文件 L558-L559避免重复添加冗余的唯一约束。删除主键通过Edit Table面板可以删除已有的主键列。由于每张表必须至少保留一个主键因此删除流程要求你先指定替代主键操作步骤编辑一张已有的表先选择另一列作为新的主键勾选其 Primary 复选框确认新主键生效后回到原来的主键列取消勾选原主键列的 Primary 复选框移除其主键状态移除主键约束后即可将该列从表中删除。同样地如果目标表的主键正被用作任何源表的外键则不能删除该主键。这条限制与修改主键的限制一脉相承目的都是防止外键引用悬空、维护引用完整性。与之呼应table-operations.md 的 Delete Column 一节也明确指出如果某列正被用作主键则不能删除该列必须先移除该列的主键约束后再删除。换言之删除主键列是先解除主键约束、再删列的两步操作UI 上会阻止你直接删除仍是主键的列。主键与外键、批量上传等机制的联动理解主键的价值需要把它放在 ToolJet Database 的整体约束体系中看主键是外键的引用目标外键要求源表列的值必须与目标表的主键列或唯一约束列的值匹配见 database-editor.md 的 Column Constraints 一节。因此被引用的主键不能随意修改或删除详见 foreign-key.md。批量上传依赖主键做去重与更新在 tooljet-db-bulk-upload.service.ts 中CSV 批量导入会基于主键执行插入/更新逻辑若 CSV 中出现重复主键会抛出Duplicate primary key found on row[...]L112若数据未提供serial类型主键列的值则走普通INSERT让 PostgreSQL 自动生成L512-L524反之则走UPSERT更新已有记录。这正是主键唯一标识记录在数据写入链路中的直接应用。行级操作依赖主键定位记录数据操作服务在更新/删除记录时要求指定主键列否则会返回No primary key columns specified错误见 tooljet-db-data-operations.service.ts说明主键是 ToolJet Database 进行行级寻址的基础。主键设计实践建议结合本文的约束与联动规则在设计 ToolJet Database 表结构时可以遵循以下原则优先保留默认的serial自增主键新建表默认生成的id列开箱即用适合大多数业务表需要业务自然键时选择varchar、int、bigint或float列避开boolean、date with time、jsonb它们不支持主键约束只有单列确实无法唯一标识记录时才使用复合主键并牢记外键不能引用复合主键列的限制若后续需要被其他表引用应另行设计唯一约束列修改或删除主键前先排查外键引用凡是被外键引用的主键必须先将外键关系移除或改用其他引用目标才能变更主键利用 Export Schema 保留表结构备份在调整主键等结构前可先通过表的 kebab 菜单导出 JSON 格式的表结构见 table-operations.md 的 Export Schema 一节以便回滚或迁移。小结主键是 ToolJet Database 数据建模的枢纽新建表默认自带serial类型的id主键编辑器通过一个Primary复选框即可完成单字段主键、复合主键的创建以及主键的修改与删除约束层面要求主键列非空、唯一、禁用 Boolean 类型且每表至少保留一个主键与外键、批量上传、行级操作的联动规则则在服务端源码中得到了完整实现与校验。掌握这些规则你就能在 ToolJet 中设计出既灵活又严谨的数据结构。【免费下载链接】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），仅供参考