Mathesar 用户指南：深入理解其电子表格化协作架构与 PostgreSQL 深度集成原理

数据库后端前端协作【免费下载链接】mathesarAn intuitive spreadsheet-like interface that lets users of all technical skill levels view, edit, query, and collaborate on Postgres data directly. 100% open source and self hosted, with native Postgres access control.项目地址https://gitcode.com/gh_mirrors/ma/mathesar点击查看免费下载Mathesar 是一款 100% 开源自托管的 Web 应用它以类电子表格的界面为 PostgreSQL 数据库提供数据查看、编辑、查询与协作能力让技术与非技术用户直接在同一份关系型数据上协同工作。本文以官方用户指南为主线梳理 Mathesar 的整体工作方式、数据存放边界、与 PostgreSQL 深度绑定的架构设计并结合仓库源码SQL 层、Django 模型、RPC 接口逐层印证其实现原理帮助你理解“数据真正在哪里、权限如何生效、元数据如何存储”等核心问题从而正确规划自己的数据工作流。Mathesar 是如何工作的从官方用户指南 docs/docs/user-guide/index.md 的定义来看Mathesar 的核心定位是一个或多个 PostgreSQL 数据库之上的电子表格式界面。它的工作方式可以概括为以下几点直接面对真实数据你在 Mathesar 界面中看到的数据与你 PostgreSQL 数据库里存储的数据完全一致。界面上的 schemas、tables、relationships 等对象都是对 PostgreSQL 中真实对象的直接呈现而非额外的抽象副本。权限边界由 PostgreSQL 决定Mathesar 用户的全部数据访问能力被严格限制在你赋予 Mathesar 的那个 PostgreSQL role 的 privileges权限 之内。数据库层不授予的能力界面层也无法绕过。面向两类使用场景接入已有数据把 Mathesar 指向你现有的 PostgreSQL 数据集即可获得一个强大的 GUI 管理工具用于数据录入、分析与内部后台流程。从零构建数据与工作流把 Mathesar 当作传统电子表格方案的替代品用于构建数据集和工作流享受关系型数据库带来的可扩展性与数据完整性。数据放在哪里连接数据库与内部数据库的边界理解 Mathesar 最重要的一点是分清两类数据库你连接的 PostgreSQL 数据库与Mathesar 自身的内部数据库。Mathesar 应用程序内部维护着一个小型内部数据库用于存储你在 Mathesar 中创建的 users用户、添加的数据库 连接凭据、保存的 数据探索data explorations以及少量可配置的 metadata元数据。但你真正的业务数据全部存放在 PostgreSQL 数据库中——在 Mathesar 之外。这意味着得益于 PostgreSQL 强大的互操作性你始终对自己的数据保有完全的控制权即使将来你决定在现有工作流中引入其他工具、甚至彻底弃用 Mathesar数据也随时可以迁移或直接被他方工具访问。两类数据库的存放内容对比如下摘自 databases.md存放在你连接的数据库中的数据存放在 Mathesar 内部数据库中的数据你在 Mathesar 中看到的 schemas 与 tablesUsersMathesar 用户这些表内的行、列与单元格数据库连接凭据包括已保存的 role 密码表与表之间的 relationshipsCollaborators协作者Roles 及其权限Metadata元数据已保存的 Explorations数据探索元数据Metadata薄薄的一层“便利层”为了既保持“数据即 PostgreSQL 真实结构”又提供超出关系模型的便利功能Mathesar 在其内部数据库中保存了一层很薄的元数据主要包括表级元数据列顺序PostgreSQL 本身不允许对已有列重新排序而 Mathesar 允许你在表视图中通过拖拽自定义列顺序这个顺序就作为元数据存储。当没有元数据时列按 PostgreSQL 中的原始顺序展示。记录摘要模板record summary template用于生成 record summaries 的模板把指向某条记录的链接压缩成简短、可读的文本。没有元数据时Mathesar 会尽量使用该表第一个文本类列生成摘要。列级元数据Mathesar 的多种 data types 具有类型专属的格式化选项例如数字的小数位数、货币符号等这些选项同样以元数据形式存储。关于元数据的访问控制需要特别留意当前元数据与数据探索对所有数据库协作者都可读可写不受其 PostgreSQL role 权限或用户 admin 状态限制见 docs/docs/snippets/metadata-access-control.md。如果你的使用场景需要收紧这部分权限官方欢迎通过 issue 反馈需求。关于 PostgreSQL深度集成、逻辑下沉数据库层的架构Mathesar 对 PostgreSQL 的承诺远不止“支持”而已而是将应用架构与 PostgreSQL深度绑定很大一部分 Mathesar 应用逻辑实际上运行在它所连接的 PostgreSQL 数据库内部。这种架构带来了两个直接结果高性能与流畅 UI由于减少了 Mathesar 应用与 PostgreSQL 服务器之间的多次网络往返即使 PostgreSQL 服务器与应用服务器相距半个地球例如跨地域部署Mathesar 依然能保持快速响应。当前只支持 PostgreSQL作为短期代价Mathesar 目前只能与 PostgreSQL 数据库协同工作。官方期望未来利用 PostgreSQL 强大的 Foreign Data WrapperFDW 能力连接 MySQL、SQLite、Oracle、MongoDB 等其他类型数据库。Mathesar 在数据库里安装了些什么为了让 Mathesar 正常工作首次连接数据库时它会在你的 PostgreSQL 数据库上安装一批函数。这些函数被安装到Mathesar 专属的 schemas中与数据库上任何用户自定义函数隔离开来。仓库中db/constants.py的INTERNAL_SCHEMAS集合明确列出了这三个内部 schemaMATHESAR_PREFIX mathesar_ MSAR_PUBLIC_SCHEMA msar MSAR_PRIVATE_SCHEMA f__{MSAR_PUBLIC_SCHEMA} TYPES_SCHEMA f{MATHESAR_PREFIX}types INTERNAL_SCHEMAS { TYPES_SCHEMA, # mathesar_types MSAR_PUBLIC_SCHEMA, # msar MSAR_PRIVATE_SCHEMA, # __msar }msar承载 Mathesar 绝大部分应用代码以 PostgreSQL 函数形式定义见 db/sql/README.md。__msar已废弃的旧 schema部分函数正在逐步迁移到msar迁移背景见 db/sql/STANDARDS.md。mathesar_types存放 Mathesar 的自定义数据类型见下文“数据类型”部分。注意上述三个 schema 是 Mathesar 正常运作所必需的Mathesar 允许你操作数据库中的其他所有 schema唯独不允许操作这三个内部 schema。安装流程的源码印证安装逻辑位于 db/sql/install.py其INSTALL_STEPS按固定顺序加载并执行db/sql/目录下的 9 个 SQL 文件INSTALL_STEPS [ _install_sql_file(00_msar_all_objects_table.sql), _install_sql_file(01_msar_types.sql), _install_sql_file(02_msar_remove.sql), _install_sql_file(05_msar.sql), _install_sql_file(10_msar_joinable_tables.sql), _install_sql_file(30_msar_custom_aggregates.sql), _install_sql_file(45_msar_type_casting.sql), _install_sql_file(46_msar_type_inference.sql), _install_sql_file(50_msar_permissions.sql), ]00_msar_all_objects_table.sql创建msar.all_mathesar_objects表登记所有 Mathesar 管理对象的清单obj_schema、obj_name、obj_kind、custom_type四列01_msar_types.sql在mathesar_typesschema 中创建自定义类型05_msar.sql及后续文件依次部署主函数、可连接表、自定义聚合、类型转换、类型推断与权限函数。Django 模型层的Database.install_sql()见 mathesar/models/base.py负责触发这一安装流程并在成功后把last_confirmed_sql_version更新为当前 Mathesar 版本号——这也就是升级提示needs_upgrade_attention的判断依据。连接数据库时要求你提供的 PostgreSQL role 对数据库具有CREATE权限才能成功安装这些 schema安装完成、数据库连接就绪后如果你不希望用户再创建其他 schema可以收回CREATE权限见 schemas.md。用户指南核心主题导览用户指南围绕“数据库 → schema → 表 → 关系 → 数据类型 → 访问控制”这条主线展开以下是对各子文档核心要点的提炼与补充。数据库连接、创建、权限与断开详见 docs/docs/user-guide/databases.md。数据库 vs 电子表格数据库是存放于刚性结构中的自包含数据集能维护数据完整性并支持高效操作一个数据库内可有多张表类比电子表格中的多个 sheet行有时被称为“记录”record。连接数据库在 Mathesar 首页点击Connect Database按钮并按提示操作。连接后 Mathesar 会记住该连接即使应用关闭也不丢失你的 Mathesar 用户会被自动添加为该数据库的 collaborator协作者你输入的 role 密码将存储在内部数据库中并使用 Mathesar 的SECRET_KEY加密。SSL 模式连接外部数据库时可配置 SSL 模式Prefer SSL默认服务器支持 SSL 则使用否则回退到非加密连接兼顾安全与兼容性Require SSL始终使用 SSL服务器不支持时连接失败适合对安全性要求高的生产数据库Disable SSL从不使用 SSL仅建议本地开发或可信网络。注意PostgreSQL 还支持verify-ca、verify-full证书校验模式但 Mathesar 目前不支持。大多数云托管 PostgreSQLAWS RDS、Google Cloud SQL、Supabase 等都支持 SSL官方建议对这类服务使用 Prefer 或 Require。创建新数据库可以在 Mathesar 内部服务器上直接新建并连接适合快速起步但后续若要配置备份或接入其他工具可能需要更多工作且该选项在未安装内部服务器的部署中不可用也可以用其他工具在外部服务器创建后让 Mathesar 连接可自管服务器或选择 RDS、Cloud SQL、Supabase 等托管方案。数据库权限每个数据库有一个 owner所有者role只有所有者能删除数据库、管理数据库级权限、转移所有权此外可授予CONNECT连接、CREATE创建 schema、TEMPORARY创建临时表三种权限。在数据库页面右上角点击Database Permissions即可管理。断开数据库从数据库页右上角下拉菜单选择 “Disconnect Database”。断开不会删除数据库但会删除与该库对象关联的 Mathesar 元数据已保存的探索、自定义列显示选项、自定义记录摘要模板。删除数据库Mathesar 目前不支持直接 drop 数据库需在 PostgreSQL 侧自行完成。Docker 部署提示若通过 Docker 运行连接宿主 PostgreSQL 时 Host 设为localhost可能不生效。macOS/Windows 上一般可用host.docker.internalLinux 上需显式配置host.docker.internal或使用 Docker 网关 IP172.17.0.1。通过 Unix socket 连接时把 Host 设为 socket 路径如/var/run/postgresql使用默认端口5432时可省略 Port且需确保容器以卷方式挂载该 socket 路径。连接凭据的源码印证mathesar/models/base.py 中的Server模型直接体现了上述 SSL 三态设计sslmode models.CharField( max_length20, choices[ (disable, disable), (prefer, prefer), (require, require), ], defaultprefer )而ConfiguredRole模型的密码字段使用EncryptedCharField来自encrypted_fields库加密存储class ConfiguredRole(BaseModel): name models.CharField(max_length255) server models.ForeignKey(Server, on_deletemodels.CASCADE, related_nameroles) password EncryptedCharField(max_length255, blankTrue, nullTrue)UserDatabaseRoleMap用户-数据库-角色映射通过unique_constraintuser_one_role_per_database保证了“一个 Mathesar 用户在同一数据库上只能绑定一个 PostgreSQL role”这一协作模型约束。Schema数据库内的“文件夹”详见 docs/docs/user-guide/schemas.md。PostgreSQL 中每张表必须且只能归属一个 schemaschema 不能嵌套因此对象层级固定为数据库 → schema → 表Mathesar 界面完全镜像这一层级。每个数据库都有一个名为public的 schema不可删除或重命名多数服务器默认允许所有 role 在其中建表如果你不需要划分数据可以一直只用public。Mathesar 允许你在数据库页增删改 schema并可为 schema 添加描述以 PostgreSQLCOMMENT形式存储但public不可改动且操作受 access control 约束。Schema 权限owner 可删除 schema、管理 schema 级权限、转移所有权可授予的权限包括USAGE查看 schema 内的表与CREATE在 schema 内创建新表。在 schema 页右上角点击Schema Permissions管理。表行、列与单元格的基本容器详见 docs/docs/user-guide/tables.md。所有关系型数据库都把数据组织成表又称“关系”一个数据库通常包含数张到数十张表且表之间高度互联。Mathesar 允许在数据库页增删改表、添加表描述同样存为COMMENT操作能力受访问控制限制。表权限owner 可删除表、修改表列、管理表级权限、转移所有权可授予的权限包括SELECT、INSERT、UPDATE、DELETE、TRUNCATE、REFERENCES创建指向本表的外键约束、TRIGGER在本表上创建触发器。在表页右上角点击Table Permissions管理。关系用外键建模规范化数据详见 docs/docs/user-guide/relationships.md。为什么需要关系一份通讯录里“一个人有多个邮箱”若不建关系只能靠“多列堆叠”“逗号合并”“一行重复多次”等反模式凑合既难查询又易出错。而拆成people与emails两张表、让emails.person引用people.id数据库会自动校验引用的有效性甚至阻止你删掉仍被引用的记录。规范化normalization通过多张关联表建模数据即“数据规范化”。规范化结构查询更新更高效、冗余更少、不易不一致代价是数据分散带来的操作迂回而 Mathesar 正是用友好的界面来消解这份复杂度。外键约束PostgreSQL 中引用即“外键约束”foreign key。Mathesar 通过识别数据库中的外键约束来判断引用列你在 Mathesar 中创建引用列时它会自动在 PostgreSQL 中创建相应外键。记录摘要record summaries默认显示被引用表第一个文本类列的值可在“表检查器 → Table 标签页 → Record Summary”或“Column 标签页 → Linked Record Summary”中自定义。记录选择器record selector引用列提供记录选择器可对被引用表的所有列做模糊搜索还能直接从选择器中创建新记录。限制不支持复合外键一次引用被引用表的多列缺少外键约束的隐式引用列不会被识别为引用。关系类型一对多 / 多对一结构等价、视角相反、多对多借助people_tags这类 join/mapping 表、以及更特殊的一对一对引用列加唯一约束、自引用建模层级结构、多态关系等。创建关系在任一方表页的“Table 标签页 → Relationships 区域 → Create relationship”按提示操作也可以在表检查器 “Advanced → Constraints → Foreign Key → Add” 手动为已有列添加外键。数据类型用少量类别驯服 PostgreSQL 类型系统详见 docs/docs/user-guide/data-types.md。Mathesar 把庞杂的 PostgreSQL 类型归并为少量用户友好的“Mathesar 数据类型”每个 PostgreSQL 类型精确映射到一个 Mathesar 类型一个 Mathesar 类型可对应多个 PostgreSQL 类型。例如 Number 一个类别就简化了numeric、smallint、integer、bigint、decimal、real、double precision七种类型默认使用numeric。主要类别及默认 PostgreSQL 类型Mathesar 类型对应 PostgreSQL 类型默认加粗格式化选项存为元数据Booleanboolean用下拉框代替复选框自定义两个选项的显示文本Datedate自定义日期显示格式Date Timetimestamp with time zone、timestamp without time zone自定义日期时间格式Durationinterval自定义时长格式Emailmathesar_types.emailtext上的 domain带邮箱校验—Moneymathesar_types.mathesar_moneynumeric上的 domain、money小数位数、千分位分组、数字 locale、货币符号字符与位置Numbernumeric等七种小数位数、千分位分组、localeTexttext、char、varchar—Timetime with time zone、time without time zone自定义时间格式URLmathesar_types.uritext上的 domain带 URI 校验—FilesJSONBUI 自定义类型需 配置文件后端—Userinteger存 Mathesar 用户 ID仅数据库协作者可被引用—上述自定义 domain 在仓库 db/sql/01_msar_types.sql 中有完整实现例如 Email 的校验正则CREATE DOMAIN mathesar_types.email AS text CHECK ( value ~ ^[a-zA-Z0-9.!#$%*/?^_{|}~-]a-zA-Z0-9?(?:\.a-zA-Z0-9?)*$ );Money 的 domain 则是对NUMERIC的薄封装主要为 CSV 导入时的货币符号转换以及上层“货币符号”元数据字段提供兼容标记。其余 PostgreSQL 类型array、json、jsonb、xml、几何、网络地址、范围类型等Mathesar 提供基础显示支持但存在三点限制不能从 Mathesar 内创建这类列、尚不支持数据录入、无法应用格式化。访问控制用户、角色、存储角色与协作者的四层模型详见 docs/docs/user-guide/access-control.md 及其子文档。Mathesar 的访问控制完全建立在 PostgreSQL 基于角色的权限体系之上由四个概念构成Mathesar 用户users.md每个使用者拥有个人账号Admin 用户 额外拥有管理其他用户、连接/断开数据库、保存/更新/删除 PostgreSQL role 密码、管理协作者等高层级操作权限。首个安装用户自动是 Admin。用户默认用独立密码登录部分部署可启用 SSO。PostgreSQL 角色roles.mdPostgreSQL 用角色管理数据访问角色兼具“用户”与“组”的双重身份可通过继承机制把任意角色的权限授予另一角色。角色属于服务器而非某个数据库因此你在 Mathesar 中增删角色、编辑角色继承位于Database Settings标签页会影响到共享同一服务器的所有数据库。角色密码存于内部数据库并以SECRET_KEY加密重命名角色、修改LOGIN属性等操作 Mathesar 暂不支持需直接在 PostgreSQL 中进行。存储角色stored-roles.md连接数据库时你提供的 role 密码会被保存但之后新建的角色需要手动在 Mathesar 中保存密码保存后的密码无法再查看PostgreSQL 中改密码后需同步更新。角色按数据库服务器维度存储因此同一服务器上的两个数据库可复用同一角色。协作者collaborators.md只有 Admin 可管理协作者。协作者把“Mathesar 用户”与“PostgreSQL 角色”绑定且每个数据库独立设置——同一用户在不同数据库上可使用不同角色。添加协作者的前置条件为数据库已连接、用户已存在、角色已存在于 PostgreSQL 且已在 Mathesar 中存储。常见配置模式多个 Mathesar 用户共享同一 PostgreSQL 角色希望权限一致时不同用户使用不同角色需要差异化权限时一个用户不能同时绑定两个角色但可以保存多个角色并在必要时手动切换无需重复输入密码。移除协作者会撤销该用户对库的访问但用户、角色及其密码仍会保留。数据探索Data Explorer只读的报表工具详见 docs/docs/user-guide/data-explorer.md。Data Explorer 用于从数据中创建报表支持跨多表查看、筛选、排序、聚合汇总并可保存探索结果以便后续运行。其访问控制特点只读不允许修改任何数据可见数据由你当前使用的 PostgreSQL role 权限决定所有协作者共享同一组探索与元数据的访问控制方式相同注意若协作者使用不同角色其看到的数据可能因角色权限不同而有差异。架构与接口的源码侧速览除前文已展示的 SQL 安装流程与模型实现外仓库代码还能进一步印证 Mathesar“应用逻辑下沉数据库层”的架构RPC 接口层Mathesar 前端通过 JSON-RPC 风格接口与后端交互后端再调用db层的函数执行实际数据库操作。例如数据库操作在 mathesar/rpc/databases/base.pydatabases.get、databases.delete、databases.upgrade_sql、连接与断开在 mathesar/rpc/databases/configured.pydatabases.configured.list/patch/disconnect、新建/接入在 mathesar/rpc/databases/setup.pydatabases.setup.create_new、databases.setup.connect_existing表操作tables.list/add/delete/patch/import/list_joinable见 mathesar/rpc/tables/base.py列操作见 mathesar/rpc/columns/base.py角色管理roles.list/add/delete/get_current_role/set_members见 mathesar/rpc/roles/base.py协作者collaborators.list/add/delete/set_role见 mathesar/rpc/collaborators.py。测试验证SQL 层使用 pgTAP 测试运行方式见 db/sql/README.mdPython 侧有对应的 RPC 测试集如 mathesar/tests/rpc/test_endpoints.py、mathesar/tests/rpc/test_roles.py共同保证数据库内函数与接口层的正确性。小结Mathesar 的架构哲学可以浓缩为一句话把数据留在 PostgreSQL把应用逻辑下沉进 PostgreSQL把复杂度收进类电子表格的界面里。理解“连接的数据库 ↔ 内部数据库”的边界、三大内部 schemamsar、__msar、mathesar_types的作用以及“用户 → 角色 → 存储角色 → 协作者”的访问控制链路是安全、高效使用 Mathesar 的前提。官方用户指南的全部子文档数据库、schema、表、关系、数据类型、访问控制、数据探索等均可从 docs/docs/user-guide/index.md 出发继续深入阅读部署与配置类主题则见 docs/docs/administration/ 目录如 环境变量说明、Docker Compose 安装、SSO 配置。赞分享数据库后端前端协作【免费下载链接】mathesarAn intuitive spreadsheet-like interface that lets users of all technical skill levels view, edit, query, and collaborate on Postgres data directly. 100% open source and self hosted, with native Postgres access control.项目地址https://gitcode.com/gh_mirrors/ma/mathesar点击查看免费下载相关推荐Docsify核心架构解析深入理解其工作原理Docsify核心架构解析深入理解其工作原理 本文深入解析了Docsify的核心架构设计包括其采用的混合继承架构、模块分层设计以及各组件间的协作关系。文章详前端文档开发工具Mathesar极速部署指南让PostgreSQL管理变得像电子表格一样简单Mathesar极速部署指南让PostgreSQL管理变得像电子表格一样简单 Mathesar是一款100%开源的PostgreSQL数据管理工具它提供了直数据库后端前端协作Mathesar快速入门终极指南零基础搭建PostgreSQL电子表格界面Mathesar快速入门终极指南零基础搭建PostgreSQL电子表格界面 Mathesar是一款100%开源且可自托管的PostgreSQL数据管理工具它数据库后端前端协作上一篇一机畅玩多人游戏Nucleus Co-Op分屏神器让单机变派对下一篇如何用一台电脑实现四人同屏游戏Nucleus Co-Op分屏工具全解析创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考