尧图网站建设 
ToolJet Database 数据类型详解8 种列类型的取值规则、约束矩阵与默认值校验机制【免费下载链接】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 官方文档 Data Types 展开系统介绍 ToolJet Database 支持的 8 种列数据类型serial、varchar、int、bigint、float、boolean、date with time、jsonb各自的用途与取值范围并完整给出“每种数据类型允许哪些列约束”的判定矩阵。结合服务端源码 server/src/modules/tooljet-db/types.ts、server/src/modules/tooljet-db/dto/index.ts 与 server/src/helpers/utils.helper.ts你会了解到文档中的类型名如何映射到 PostgreSQL 的实际类型、默认值是如何被校验和格式化的以及约束冲突时后端会返回什么错误信息从而在 ToolJet Database 建表时做出正确且可运行的类型设计。一、ToolJet Database 支持的 8 种数据类型ToolJet Database 为不同性质的信息提供了若干种数据类型每种类型有其特定的特征与适用场景。官方文档定义的完整类型表如下与 docs/docs/tooljet-db/data-types.md 完全一致数据类型说明示例serial用于生成整数序列常用作表的主键。在 ToolJet Database 中新建一张表时会自动创建一个id列其数据类型为serial并作为该表的主键。从 1 开始的整数1, 2, 3, 4, 5……varchar用于存储不定长度的字符任意字符串值int数值类型存储无小数部分的整数范围从 -2147483648 到 2147483647 的整数bigint数值类型存储更大的、无小数部分的整数范围从 -9223372036854775808 到 9223372036854775807 的整数float数值类型存储不精确的、可变精度的数值任意浮点数如 3.14boolean可取 true、false 和 nulltrue或falsedate with time同时存储日期与时间信息格式为 ISO 8601。默认时区为用户设备的时区也可指定其他时区。所有时间戳数据均以 UTC 格式存储显示时再转换为指定时区2024-07-22 15:30:00jsonb用于存储 JSON 数据可保存数组或嵌套对象等结构化数据{name: John Doe, age: 30, skills: [JavaScript, Python], address: {city: New York, zip: 10001}}从源码看文档类型名与 PostgreSQL 实际类型的映射上表中 float、date with time 等名称是界面友好名而数据库底层实际使用的 PostgreSQL 类型可以完整地在服务端代码中找到。server/src/modules/tooljet-db/types.ts 定义了TJDB常量它是 ToolJet Database 允许的全部类型白名单export const TJDB { character_varying: character varying as const, // 对应界面显示的 varchar integer: integer as const, // 对应 int bigint: bigint as const, serial: serial as const, double_precision: double precision as const, // 对应 float boolean: boolean as const, timestampz: timestamp with time zone as const, // 对应 date with time jsonb: jsonb as const, }; export type TooljetDatabaseDataTypes (typeof TJDB)[keyof typeof TJDB];从源码结构看可以确认几个关键实现事实界面中的float在 PostgreSQL 中实际是double precision双精度浮点这解释了文档中“inexact, variable-precision values不精确、可变精度”的表述date with time对应timestamp with time zonetimestamptzPostgreSQL 的 timestamptz 本身就是以 UTC 存储、按会话时区呈现与文档中“All timestamp data is stored in UTC format and converted to the specified timezone when displayed”的描述一致只有这 8 种类型会被后端接受。DTO 层通过IsIn(Object.values(TJDB), { message: Incorrect datatype. })强制校验传入白名单之外的类型会直接报“Incorrect datatype.”见 server/src/modules/tooljet-db/dto/index.ts。二、每行记录的完整描述结构理解数据类型如何被“描述”并下发到数据库有助于理解建表/改列时的校验逻辑。server/src/modules/tooljet-db/types.ts 中的TooljetDatabaseColumn类型给出了列的完整元数据结构export type TooljetDatabaseColumn { column_name: string; data_type: TooljetDatabaseDataTypes; // 必须是 TJDB 白名单中的类型 column_default: string | null; character_maximum_length: number | null; // varchar 的长度信息 numeric_precision: number | null; // 数值类型的精度信息 constraints_type: { is_not_null: boolean; is_primary_key: boolean; is_unique: boolean; }; keytype: string | null; };其中constraints_type的三个布尔字段正对应下文约束矩阵中的 Not Null、Primary Key、Unique 三列data_type则与约束组合起来决定了一个列的合法形态。三、各数据类型的默认值校验与格式化规则官方文档在 Database Editor 中建表说明中提到可以指定列的默认值Default value留空则允许 null。而默认值“留空/填写”时后端会做哪些转换可以从 DTO 的Transform管道中完整还原。server/src/modules/tooljet-db/dto/index.ts 中PostgrestTableColumnDto.column_default的转换链为Transform(({ value, obj }) { const transformedJsonbData formatJSONB(value, obj); const sanitizedValue sanitizeInput(transformedJsonbData); const transformedData formatTimestamp(sanitizedValue, obj); return validateDefaultValue(transformedData, obj); }) Match(data_type, { message: Default value must match the data type }) column_default: string | number | boolean;四个处理函数均定义在 server/src/helpers/utils.helper.ts逐一看它们与数据类型的对应关系formatJSONB针对 jsonb 列JSONB 列的默认值必须以字符串化形式存入数据库该函数会先把输入转为 JSON 字符串并递归转义其中的单引号→最后包上外层单引号生成合法 SQL 字面量如{a:1}见 utils.helper.ts。这解释了为什么 jsonb 列的默认值即使含嵌套对象也能正确落地。formatTimestamp针对 date with time 列当data_type timestamp with time zone时默认值会被显式包裹成带引号的字符串2024-07-22 15:30:00避免被误解析为裸数字或表达式见 utils.helper.ts。validateDefaultValue针对 boolean 列布尔列的默认值若为空会回退为字符串false见 utils.helper.ts。Match(data_type) 类型匹配校验自定义校验器MatchTypeConstraintserver/src/modules/tooljet-db/dto/index.ts按类型检查默认值的形态——character varying/timestamp with time zone/jsonb默认值必须是字符串integer/bigint/double precision默认值必须是数值允许整数或浮点数boolean默认值必须是true或false字符串不匹配时报错 “Default value must match the data type”。也就是说你在界面上为不同类型列填写默认值时后端会按上表逐一做形态校验类型与值不匹配会在校验层直接拒绝。四、每类数据类型的允许约束矩阵文档给出了每种数据类型允许应用的列约束Primary Key / Foreign Key / Unique / Not Null矩阵。关于四种约束的完整定义主键保证唯一且非空、外键保证引用完整性、Unique 允许 null 但要求唯一、Not Null 禁止 null请参见 Database Editor 的 Column Constraints 一节以及 Primary Key 文档、Foreign Key 文档。完整矩阵如下与 docs/docs/tooljet-db/data-types.md 一致数据类型Primary KeyForeign KeyUniqueNot Nullserial✅❌✅✅varchar✅✅✅✅int✅✅✅✅bigint✅✅✅✅float✅✅✅✅boolean❌❌❌✅date with time❌❌❌✅jsonb❌❌❌✅从这张矩阵可以读出 ToolJet Database 的类型约束设计规律serial 不能作外键序列生成列只适合做本表的唯一标识主键或唯一键不适合去引用别表的键boolean、date with time、jsonb 不能作主键、外键或唯一键布尔只有三个取值、时间戳与 JSONB 在 PostgreSQL 的约束语义上不适合作为唯一性标识例如 jsonb 不支持直接作为唯一约束的列因此三者都只能叠加 Not Null其余五种类型约束全开varchar、int、bigint、float 既可作主键、外键、唯一键也可加非空约束。这与 Primary Key 文档 中的说明互相印证“主键列可以是任何受支持的数据类型Boolean 除外”且复合主键的每一列同样不能是 Boolean 类型。从源码看约束冲突时后端返回什么当你违反上述约束写入或修改数据时server/src/modules/tooljet-db/types.ts 中的errorCodeMapping会把 PostgreSQL 错误码翻译成面向用户的消息例如对唯一约束列写入重复值Postgres 错误码23505批量上传场景提示 “Duplicate value violates unique constraint”行内写入提示 “Unique constraint violated as {{value}} already exists in {{table}}.{{column}}”对 Not Null 列写入空值错误码23502提示 “Not null constraint violated for {{table}}.{{column}}”编辑列时新增 NOT NULL 但列中已有 null则提示 “Cannot add NOT NULL constraint as this column contains null values”违反外键引用错误码23503提示 “Update or delete on {{table}}.{{column}} with {{value}} violates foreign key constraint”。这些消息通过TooljetDatabaseError类types.ts结合操作上下文edit_column、bulk_upload、proxy_postgrest等与表名做占位符替换后展示给前端也就是说矩阵中每一个 ❌ 在界面上的“不可选”状态在数据库层面也有对应的错误兜底。五、建表与数据写入时的类型实践要点结合文档与源码给出在 ToolJet Database 中运用这些类型的几个实践要点主键策略新建表时idserial自动成为主键可改为任意其他列含复合主键可勾选多列。若表要被其他表以 Add Relation建立外键关系被引用的键必须来自矩阵中“✅ Primary Key / Unique”的类型——即 serial、varchar、int、bigint、float避免选择 boolean、date with time、jsonb 列。数值选型常规计数/金额以外的整数用 int约 ±21 亿超出 int 范围的计数、时间戳毫秒值等用 bigint约 ±9.2×10^18需要小数用 float底层为 double precision注意其“不精确”的特性涉及金额精度敏感场景时应结合业务自行规避浮点误差。时间列date with time 以 ISO 8601 输入如2024-07-22 15:30:00底层 timestamptz 统一 UTC 存储、按指定时区展示跨时区协作场景下无需担心存储漂移。jsonb 列适合存嵌套对象/数组如文档示例中的用户 skills、address 结构写默认值时后端会自动字符串化并转义单引号写入行数据时后端还会通过 validateTjdbJSONBColumnInputs 校验 jsonb 列的取值是否为合法 JSON 对象/数组非法值会被列入inValidValueColumnsList拒绝。默认值与 null留空默认值即允许 null只有当某列标记了 Not Null 约束时才要求每行必填且对该列批量加 NOT NULL 时若列中已存在 null 值会被拒绝见上文源码错误映射。与筛选操作的配合在 Database Editor 的过滤能力中is操作专门用于 boolean 类型like/ilike/match/imatch等文本操作则适用于 varchar 等字符串列——选型时可以把“列之后要支持哪些查询”纳入考虑。六、小结ToolJet Database 提供 8 种列数据类型serial自动主键序列、varchar、int、bigint、floatdouble precision、boolean、date with timetimestamp with time zoneUTC 存储与 jsonb。每种类型的允许约束遵循清晰矩阵布尔、时间、jsonb 三类只能加 Not Nullserial 可作主键与唯一键但不可作外键varchar/int/bigint/float 约束全开。后端以TJDB白名单限定合法类型通过Match、formatJSONB、formatTimestamp等对默认值做类型级校验并在违反唯一、非空、外键约束时给出带表名/列名上下文的明确错误。按本文的矩阵与规则设计列类型与约束即可在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 ToolJet Database 数据类型详解：8 种列类型的取值规则、约束矩阵与默认值校验机制
ToolJet Database 数据类型详解8 种列类型的取值规则、约束矩阵与默认值校验机制【免费下载链接】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 官方文档 Data Types 展开系统介绍 ToolJet Database 支持的 8 种列数据类型serial、varchar、int、bigint、float、boolean、date with time、jsonb各自的用途与取值范围并完整给出“每种数据类型允许哪些列约束”的判定矩阵。结合服务端源码 server/src/modules/tooljet-db/types.ts、server/src/modules/tooljet-db/dto/index.ts 与 server/src/helpers/utils.helper.ts你会了解到文档中的类型名如何映射到 PostgreSQL 的实际类型、默认值是如何被校验和格式化的以及约束冲突时后端会返回什么错误信息从而在 ToolJet Database 建表时做出正确且可运行的类型设计。一、ToolJet Database 支持的 8 种数据类型ToolJet Database 为不同性质的信息提供了若干种数据类型每种类型有其特定的特征与适用场景。官方文档定义的完整类型表如下与 docs/docs/tooljet-db/data-types.md 完全一致数据类型说明示例serial用于生成整数序列常用作表的主键。在 ToolJet Database 中新建一张表时会自动创建一个id列其数据类型为serial并作为该表的主键。从 1 开始的整数1, 2, 3, 4, 5……varchar用于存储不定长度的字符任意字符串值int数值类型存储无小数部分的整数范围从 -2147483648 到 2147483647 的整数bigint数值类型存储更大的、无小数部分的整数范围从 -9223372036854775808 到 9223372036854775807 的整数float数值类型存储不精确的、可变精度的数值任意浮点数如 3.14boolean可取 true、false 和 nulltrue或falsedate with time同时存储日期与时间信息格式为 ISO 8601。默认时区为用户设备的时区也可指定其他时区。所有时间戳数据均以 UTC 格式存储显示时再转换为指定时区2024-07-22 15:30:00jsonb用于存储 JSON 数据可保存数组或嵌套对象等结构化数据{name: John Doe, age: 30, skills: [JavaScript, Python], address: {city: New York, zip: 10001}}从源码看文档类型名与 PostgreSQL 实际类型的映射上表中 float、date with time 等名称是界面友好名而数据库底层实际使用的 PostgreSQL 类型可以完整地在服务端代码中找到。server/src/modules/tooljet-db/types.ts 定义了TJDB常量它是 ToolJet Database 允许的全部类型白名单export const TJDB { character_varying: character varying as const, // 对应界面显示的 varchar integer: integer as const, // 对应 int bigint: bigint as const, serial: serial as const, double_precision: double precision as const, // 对应 float boolean: boolean as const, timestampz: timestamp with time zone as const, // 对应 date with time jsonb: jsonb as const, }; export type TooljetDatabaseDataTypes (typeof TJDB)[keyof typeof TJDB];从源码结构看可以确认几个关键实现事实界面中的float在 PostgreSQL 中实际是double precision双精度浮点这解释了文档中“inexact, variable-precision values不精确、可变精度”的表述date with time对应timestamp with time zonetimestamptzPostgreSQL 的 timestamptz 本身就是以 UTC 存储、按会话时区呈现与文档中“All timestamp data is stored in UTC format and converted to the specified timezone when displayed”的描述一致只有这 8 种类型会被后端接受。DTO 层通过IsIn(Object.values(TJDB), { message: Incorrect datatype. })强制校验传入白名单之外的类型会直接报“Incorrect datatype.”见 server/src/modules/tooljet-db/dto/index.ts。二、每行记录的完整描述结构理解数据类型如何被“描述”并下发到数据库有助于理解建表/改列时的校验逻辑。server/src/modules/tooljet-db/types.ts 中的TooljetDatabaseColumn类型给出了列的完整元数据结构export type TooljetDatabaseColumn { column_name: string; data_type: TooljetDatabaseDataTypes; // 必须是 TJDB 白名单中的类型 column_default: string | null; character_maximum_length: number | null; // varchar 的长度信息 numeric_precision: number | null; // 数值类型的精度信息 constraints_type: { is_not_null: boolean; is_primary_key: boolean; is_unique: boolean; }; keytype: string | null; };其中constraints_type的三个布尔字段正对应下文约束矩阵中的 Not Null、Primary Key、Unique 三列data_type则与约束组合起来决定了一个列的合法形态。三、各数据类型的默认值校验与格式化规则官方文档在 Database Editor 中建表说明中提到可以指定列的默认值Default value留空则允许 null。而默认值“留空/填写”时后端会做哪些转换可以从 DTO 的Transform管道中完整还原。server/src/modules/tooljet-db/dto/index.ts 中PostgrestTableColumnDto.column_default的转换链为Transform(({ value, obj }) { const transformedJsonbData formatJSONB(value, obj); const sanitizedValue sanitizeInput(transformedJsonbData); const transformedData formatTimestamp(sanitizedValue, obj); return validateDefaultValue(transformedData, obj); }) Match(data_type, { message: Default value must match the data type }) column_default: string | number | boolean;四个处理函数均定义在 server/src/helpers/utils.helper.ts逐一看它们与数据类型的对应关系formatJSONB针对 jsonb 列JSONB 列的默认值必须以字符串化形式存入数据库该函数会先把输入转为 JSON 字符串并递归转义其中的单引号→最后包上外层单引号生成合法 SQL 字面量如{a:1}见 utils.helper.ts。这解释了为什么 jsonb 列的默认值即使含嵌套对象也能正确落地。formatTimestamp针对 date with time 列当data_type timestamp with time zone时默认值会被显式包裹成带引号的字符串2024-07-22 15:30:00避免被误解析为裸数字或表达式见 utils.helper.ts。validateDefaultValue针对 boolean 列布尔列的默认值若为空会回退为字符串false见 utils.helper.ts。Match(data_type) 类型匹配校验自定义校验器MatchTypeConstraintserver/src/modules/tooljet-db/dto/index.ts按类型检查默认值的形态——character varying/timestamp with time zone/jsonb默认值必须是字符串integer/bigint/double precision默认值必须是数值允许整数或浮点数boolean默认值必须是true或false字符串不匹配时报错 “Default value must match the data type”。也就是说你在界面上为不同类型列填写默认值时后端会按上表逐一做形态校验类型与值不匹配会在校验层直接拒绝。四、每类数据类型的允许约束矩阵文档给出了每种数据类型允许应用的列约束Primary Key / Foreign Key / Unique / Not Null矩阵。关于四种约束的完整定义主键保证唯一且非空、外键保证引用完整性、Unique 允许 null 但要求唯一、Not Null 禁止 null请参见 Database Editor 的 Column Constraints 一节以及 Primary Key 文档、Foreign Key 文档。完整矩阵如下与 docs/docs/tooljet-db/data-types.md 一致数据类型Primary KeyForeign KeyUniqueNot Nullserial✅❌✅✅varchar✅✅✅✅int✅✅✅✅bigint✅✅✅✅float✅✅✅✅boolean❌❌❌✅date with time❌❌❌✅jsonb❌❌❌✅从这张矩阵可以读出 ToolJet Database 的类型约束设计规律serial 不能作外键序列生成列只适合做本表的唯一标识主键或唯一键不适合去引用别表的键boolean、date with time、jsonb 不能作主键、外键或唯一键布尔只有三个取值、时间戳与 JSONB 在 PostgreSQL 的约束语义上不适合作为唯一性标识例如 jsonb 不支持直接作为唯一约束的列因此三者都只能叠加 Not Null其余五种类型约束全开varchar、int、bigint、float 既可作主键、外键、唯一键也可加非空约束。这与 Primary Key 文档 中的说明互相印证“主键列可以是任何受支持的数据类型Boolean 除外”且复合主键的每一列同样不能是 Boolean 类型。从源码看约束冲突时后端返回什么当你违反上述约束写入或修改数据时server/src/modules/tooljet-db/types.ts 中的errorCodeMapping会把 PostgreSQL 错误码翻译成面向用户的消息例如对唯一约束列写入重复值Postgres 错误码23505批量上传场景提示 “Duplicate value violates unique constraint”行内写入提示 “Unique constraint violated as {{value}} already exists in {{table}}.{{column}}”对 Not Null 列写入空值错误码23502提示 “Not null constraint violated for {{table}}.{{column}}”编辑列时新增 NOT NULL 但列中已有 null则提示 “Cannot add NOT NULL constraint as this column contains null values”违反外键引用错误码23503提示 “Update or delete on {{table}}.{{column}} with {{value}} violates foreign key constraint”。这些消息通过TooljetDatabaseError类types.ts结合操作上下文edit_column、bulk_upload、proxy_postgrest等与表名做占位符替换后展示给前端也就是说矩阵中每一个 ❌ 在界面上的“不可选”状态在数据库层面也有对应的错误兜底。五、建表与数据写入时的类型实践要点结合文档与源码给出在 ToolJet Database 中运用这些类型的几个实践要点主键策略新建表时idserial自动成为主键可改为任意其他列含复合主键可勾选多列。若表要被其他表以 Add Relation建立外键关系被引用的键必须来自矩阵中“✅ Primary Key / Unique”的类型——即 serial、varchar、int、bigint、float避免选择 boolean、date with time、jsonb 列。数值选型常规计数/金额以外的整数用 int约 ±21 亿超出 int 范围的计数、时间戳毫秒值等用 bigint约 ±9.2×10^18需要小数用 float底层为 double precision注意其“不精确”的特性涉及金额精度敏感场景时应结合业务自行规避浮点误差。时间列date with time 以 ISO 8601 输入如2024-07-22 15:30:00底层 timestamptz 统一 UTC 存储、按指定时区展示跨时区协作场景下无需担心存储漂移。jsonb 列适合存嵌套对象/数组如文档示例中的用户 skills、address 结构写默认值时后端会自动字符串化并转义单引号写入行数据时后端还会通过 validateTjdbJSONBColumnInputs 校验 jsonb 列的取值是否为合法 JSON 对象/数组非法值会被列入inValidValueColumnsList拒绝。默认值与 null留空默认值即允许 null只有当某列标记了 Not Null 约束时才要求每行必填且对该列批量加 NOT NULL 时若列中已存在 null 值会被拒绝见上文源码错误映射。与筛选操作的配合在 Database Editor 的过滤能力中is操作专门用于 boolean 类型like/ilike/match/imatch等文本操作则适用于 varchar 等字符串列——选型时可以把“列之后要支持哪些查询”纳入考虑。六、小结ToolJet Database 提供 8 种列数据类型serial自动主键序列、varchar、int、bigint、floatdouble precision、boolean、date with timetimestamp with time zoneUTC 存储与 jsonb。每种类型的允许约束遵循清晰矩阵布尔、时间、jsonb 三类只能加 Not Nullserial 可作主键与唯一键但不可作外键varchar/int/bigint/float 约束全开。后端以TJDB白名单限定合法类型通过Match、formatJSONB、formatTimestamp等对默认值做类型级校验并在违反唯一、非空、外键约束时给出带表名/列名上下文的明确错误。按本文的矩阵与规则设计列类型与约束即可在 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考