NocoBase 外部数据源 PostgreSQL 接入指南连接已有业务库、Schema 收窄、字段映射与同步维护【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase导读本文基于 NocoBase 官方文档中外部数据源 PostgreSQL 的接入说明结合当前仓库中的源码与配套文档系统讲解如何把已存在的 PostgreSQL 业务数据库作为「外部数据源」接入 NocoBase包括支持版本与适用场景、商业插件的安装激活、连接参数与 Schema/表前缀收窄策略、数据表选择与同步、字段类型自动映射以及主键与记录唯一标识的设置。读完本文你将能够在不改动原 PostgreSQL 表结构的前提下用 NocoBase 为已有 ERP/MES/WMS/CRM 等系统快速搭建管理界面、权限控制、工作流与报表。外部 PostgreSQL 是什么PostgreSQL 可以作为外部数据库接入 NocoBase。接入后NocoBase 会读取 PostgreSQL 中的数据表、字段和视图并把它们作为外部数据源中的数据表使用进而参与页面区块、权限、工作流和 API 的能力编排。与主数据库不同外部 PostgreSQL 的真实表结构仍由原业务系统、数据库客户端或迁移脚本维护。NocoBase 负责读取结构、保存字段元数据、配置页面区块、权限、工作流和 API不会修改外部数据库的真实表结构。配置项说明支持版本PostgreSQL 9.5商业版本标准版、专业版、企业版支持对应插件nocobase/plugin-data-source-external-postgres注意外部 PostgreSQL 不是 NocoBase 的系统数据库。NocoBase 不会接管它的备份、还原、迁移和表结构变更这些运维职责仍然归属于外部数据库侧。适合使用外部 PostgreSQL 的场景接入已有 ERP、MES、WMS、CRM 等业务系统的 PostgreSQL 数据库在不迁移历史数据的情况下用 NocoBase 搭建管理界面对已有表做权限控制、流程处理、数据修正或报表展示数据库结构继续由 DBA、迁移脚本或原系统维护NocoBase 只做「读结构 配界面 用数据」。这一能力定位与仓库中外部数据库通用文档一致外部数据库的职责边界是「读取表结构和视图」表结构的演进由原系统、DBA 或迁移脚本负责。与主数据库 PostgreSQL 的区别NocoBase 文档目录中同时存在主数据源 PostgreSQL与本文所述的外部数据源 PostgreSQL两者差异主要体现在对比维度主数据库 PostgreSQL外部数据源 PostgreSQL支持版本 10 9.5商业版本社区版、标准版、专业版、企业版均支持标准版、专业版、企业版数据职责存储 NocoBase 系统表数据和主数据源业务数据读取已有业务库不改真实表结构字段创建通过 NocoBase 创建字段时会同步创建真实 PostgreSQL 字段NocoBase 不创建、不修改、不删除真实字段插件内置能力无需安装需要安装商业插件nocobase/plugin-data-source-external-postgres从源码看NocoBase 核心数据库层对 PostgreSQL 的支持封装在 PostgresDialect 中它声明static dialectName postgres并在 getVersionGuard 中通过select version() as version读取服务端版本并用 semver 解析版本门槛为10——这是 NocoBase 自身主数据库连接 PostgreSQL 时的版本校验而外部数据源插件对业务库的版本要求放宽到 9.5以兼容更老的历史业务系统。另外仓库中还存在针对 PostgreSQL schema 行为的测试用例见 packages/core/database/src/tests/postgres/schema.test.ts说明 NocoBase 对 PostgreSQL 的 schema 读写与表结构同步有完整的实现与回归保障。插件安装外部 PostgreSQL 由商业插件nocobase/plugin-data-source-external-postgres提供。该插件为商业插件安装并启用插件后才能在「数据源管理」的「Add new」菜单中看到 PostgreSQL 类型。激活插件需要商业授权。详细的激活与授权方式可参考 NocoBase 官方发布的商业插件激活指南见插件安装章节说明激活后即可在数据源管理中添加 PostgreSQL 外部数据源。如果「Add new」菜单里没有 PostgreSQL 选项通常需要按以下顺序排查对应插件是否已经安装插件是否已经启用当前商业授权是否包含该插件当前用户是否拥有数据源管理权限。添加数据源在「数据源管理」中点击「Add new」选择 PostgreSQL然后填写连接信息。常见连接配置如下配置说明Data source name数据源标识名称用于页面区块、权限、工作流和 API 中引用。创建后不能修改。Data source display name数据源在界面中显示的名称建议使用业务人员能理解的名称比如「ERP PostgreSQL」「报表库」。Host / PortPostgreSQL 主机地址和端口。默认端口通常是5432。Database要连接的 PostgreSQL 数据库名称。Username / Password用于连接 PostgreSQL 的账号和密码。NocoBase 只能读取这个账号有权限访问的对象不会授权或读取其他账号私有对象。Schema要读取的 PostgreSQL schema比如public。如果数据库里有多个 schema建议只填写当前业务需要接入的 schema。Table prefix表名前缀。配置后NocoBase 只读取匹配该前缀的数据表和视图并在 NocoBase 中生成不带前缀的数据表名称。Collections / Add all collections控制接入范围。启用「Add all collections」时NocoBase 会接入当前范围内的全部表和视图关闭后只接入你在「Collections」里勾选的对象。Enabled the data source是否启用这个数据源。关闭后数据源配置会保留但页面区块、权限、工作流和 API 无法继续读取它的数据。SSL optionsPostgreSQL 的 SSL 连接配置。可以设置 SSL mode、是否拒绝未授权证书以及 CA 证书、客户端证书和客户端密钥路径。提示如果 PostgreSQL 中对象很多优先通过Schema、Table prefix和「Collections」收窄范围。只接入当前应用会用到的表和视图后续权限配置、页面搭建和同步维护都会更轻。连接参数解析与底层支撑在仓库的外部数据库通用文档中PostgreSQL 属于支持接入的九类外部数据库之一MySQL、PostgreSQL、MariaDB、KingbaseES、OceanBase、MSSQL、Oracle、ClickHouse、Doris其中 KingbaseES 仅支持 PostgreSQL 兼容模式。从 NocoBase 核心数据库层看PostgreSQL 的连接与 SQL 方言能力由 PostgresDialect 提供它基于 Sequelize 的 postgres dialect 构造连接选项并通过afterConnect钩子挂接连接后的初始化逻辑再配合版本守卫在建立连接时校验服务端版本。这意味着「Host / Port / Database / Username / Password / Schema / SSL」这些参数最终会落到底层 Sequelize 的 postgres 连接配置上Schema 则决定了读取元数据时默认查询的命名空间。选择数据表填写连接信息后可以点击「Load Collections」读取 PostgreSQL 中可用的数据表和视图。读取结果会受到连接账号、Schema、Table prefix和「Collections」配置影响。默认会启用「Add all collections」表示接入当前范围内的全部表和视图。如果只想接入部分对象可以关闭「Add all collections」然后在列表中勾选需要的数据表或视图。注意单个外部数据源一次最多接入 500 张数据表或视图。如果 PostgreSQL 中对象很多建议先通过Schema、Table prefix或「Collections」收窄范围再执行加载。这条上限约束进一步印证了「收窄接入范围」的重要性对于大型业务库合理设置 Schema 与表前缀既能控制接入规模也能让后续权限配置、页面搭建与元数据同步保持轻量。同步和配置字段外部 PostgreSQL 的表结构由数据库侧维护。NocoBase 不会在外部 PostgreSQL 中创建字段、修改字段类型或删除真实字段。当 PostgreSQL 侧表结构发生变化时可以在数据源中执行「Sync from database」重新读取表和字段元数据。同步会更新 NocoBase 中保存的数据表、字段、主键、唯一键和字段类型映射信息但不会删除 PostgreSQL 中的真实表或数据。这一行为与外部数据库的通用约定一致外部数据库建立连接后直接读取数据源中的所有数据表不支持在 NocoBase 中直接添加数据表或修改表结构如需调整表结构应通过数据库客户端操作再回到 NocoBase 同步刷新详见外部数据库通用文档。字段同步后可以在 NocoBase 中配置字段标题、字段类型Field type和字段组件Field interfaceField type数据类型定义字段可以存储的数据种类、格式和结构Field interfaceUI 类型指在用户界面中用于显示和输入字段值的控件类型。如果需要建立 NocoBase 关系字段同样是在 NocoBase 中保存关系元数据不会在 PostgreSQL 表里自动新增真实外键字段——关系字段只是表与表之间的逻辑连接并不落地为数据库外键。字段类型映射NocoBase 会根据 PostgreSQL 字段类型自动映射到合适的 Field type 和 Field interface。你可以在字段配置中调整界面展示方式。常见映射如下PostgreSQL 字段类型NocoBase Field type可选 Field interfaceBOOLEANbooleanCheckbox、SwitchSMALLINT、INTEGER、SERIAL、SMALLSERIALinteger、boolean、sortInteger、Sort、Checkbox、Switch、Select、Radio groupBIGINT、BIGSERIALbigInt、sortInteger、Sort、Checkbox、Switch、Select、Radio group、Unix timestamp、Created at、Updated atREALfloatNumber、PercentDOUBLE PRECISIONdoubleNumber、PercentDECIMAL、NUMERICdecimalNumber、Percent、CurrencyVARCHAR、CHARstring、password、uuid、nanoidInput、Email、Phone、Password、Color、Icon、Select、Radio group、UUID、Nano IDTEXTtext、jsonTextarea、Markdown、Vditor、Rich text、URL、JSONUUIDuuidUUIDJSON、JSONBjsonJSONTIMESTAMPdateDate、Time、Created at、Updated atDATEdateOnlyDateTIMEtimeTimePOINT、LINESTRING、POLYGON、CIRCLEpoint、lineString、polygon、circlePoint、Line string、Polygon、Circle、JSONARRAYarrayMultiple select、Checkbox group注意不支持的 PostgreSQL 字段类型会在字段配置中单独展示。这类字段需要开发适配后才能在 NocoBase 中作为普通字段使用。对照主数据源 PostgreSQL 的字段映射可以看到外部数据源与主数据源共享同一套 PostgreSQL → NocoBase 类型映射规则如BOOLEAN→boolean、JSON/JSONB→json、TIMESTAMP→date。区别只在于方向主数据源中通过 NocoBase 页面创建字段时会反向创建 PostgreSQL 真实字段而外部数据源只做单向的「读库映射」映射元数据仅保存在 NocoBase 侧。映射的最终落点仍是字段配置中的 Field type 与 Field interface更多字段类型与字段组件的说明可参考数据表字段文档。主键和记录唯一标识用于页面区块展示和编辑的数据表建议有主键或唯一字段。NocoBase 会优先使用主键作为记录唯一标识Record unique key。如果接入的是视图、无主键表或联合主键表需要在数据表配置中手动设置「Record unique key」。没有可用唯一标识时页面区块可能无法正确查看、编辑或删除记录。「Record unique key」的作用是在页面区块中唯一定位一条记录通常选择主键或唯一字段。对于视图、无主键表、联合主键表这类对象手动指定唯一键是让区块可用性的前提。外部数据源的记录唯一标识规则与主数据源完全一致参见数据源管理 / 外部数据库以及主数据源 / 编辑数据表的相关章节。接入后的使用与维护要点完成外部 PostgreSQL 接入后可以像使用主数据源一样在页面区块、权限配置、工作流和 API 中引用该数据源下的数据表。日常维护时注意以下几点表结构变更走数据库侧新增列、改类型、删列等操作通过 DBA、数据库客户端或迁移脚本在 PostgreSQL 中完成变更后执行同步在数据源中执行「Sync from database」刷新元数据使 NocoBase 中的字段、主键、唯一键与类型映射与数据库保持一致收窄接入范围合理使用Schema、Table prefix与「Collections」配置避免一次接入过多对象单数据源上限 500 张表/视图为无主键对象指定唯一键视图、无主键表或联合主键表需要手动配置「Record unique key」否则相关页面区块可能无法正确查看、编辑或删除记录SSL 按需启用通过 SSL options 设置 SSL mode、证书校验策略及 CA/客户端证书路径满足生产环境的加密传输要求。相关文档外部数据库 — 外部数据库的通用配置和管理说明含九类数据库的支持版本与商业版本对照数据源管理 — 数据源入口和数据源管理方式数据表字段 — 字段类型和字段映射说明主数据源 PostgreSQL — 与外部数据源的对比参考含同样的字段类型映射表PostgresDialect 源码 — NocoBase 核心层对 PostgreSQL 方言与版本守卫的实现【免费下载链接】nocobaseNocoBase is an open-source AI no-code platform for building business systems fast. Instead of generating everything from scratch, AI works on top of production-proven infrastructure and a WYSIWYG no-code interface, so you get both speed and reliability.项目地址: https://gitcode.com/GitHub_Trending/no/nocobase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考