• 数据库
• 后端
• 前端
• 协作

Mathesar 0.7.1 是围绕 0.7.0 引入的列类型转换（column type casting）回归而发布的修复版本，解决了数字与货币类型互转失败、CSV 导入过程中类型推断调整失效等问题。本文以官方发布说明为骨架，结合仓库内db/sql/05_msar.sql、db/columns.py等源码与测试用例，讲清 bug 根因、修复原理，并给出 Docker Compose 与直接安装两种部署形态的完整升级步骤。

版本概况：一次聚焦的回归修复

Mathesar 0.7.1 的核心目标是修复一个阻断性（critical）bug：该 bug 阻止了数据库列从一种类型转换（cast）为另一种类型。按照官方发布说明，其影响面主要集中在三处：

• CSV 导入新建表：导入数据到新表时，类型转换是必经环节；
• CSV 导入的类型推断调整：Mathesar 的类型推断系统在导入过程中需要依据实际数据调整列类型时；
• 现有表的手动类型修改：用户在表界面中手动把某一列从一种类型改为另一种类型时。

值得注意的是，该回归正是 0.7.0 引入的。0.7.0 发布说明 开头便以醒目的警告框提示"强烈建议升级到 0.7.1（Upgrade to 0.7.1 strongly recommended）"，说明 0.7.0 中已存在"阻止部分数据库类型互转"的已知缺陷，0.7.1 即为该缺陷的定点修复。

核心修复：列类型转换回归（cast regression）

回归的根因

0.7.0 为了提高大文件导入性能，引入了针对 numeric（数字）与 money（货币）类型的优化转换函数（对应 PR #4821 "Fast money and numeric cast during import"，0.7.0 发布说明称大型数据集导入提速最高可达 97%）。然而伴随性能优化的是一处回归：

• 转换函数错误地把货币相关的格式化选项（货币前缀curr_pref、货币后缀curr_suff）应用到了不支持这些选项的数字列上；
• 同时未正确处理cast_options为空、或选项不适用于目标类型的情形。

结果是"在某些数据库类型之间转换列"时直接失败，尤其在 numeric 与 money（mathesar_types.mathesar_money）之间互转时表现最为明显。

从源码看 cast_options 机制与修复点

Mathesar 的类型转换不是简单的ALTER TABLE ... TYPE，而是先依据目标类型构建一条"转换表达式（cast expression）"，转换选项（cast_options）正是驱动该表达式形态的关键数据。仓库中相关字段的定义位于 db/columns.py：

CAST_OPTIONS = "cast_options"

在 db/columns.py 的_transform_column_alter_dict中，前端提交的列变更字典会被转换为数据库函数所需的形态，其中cast_options的结构如下：

"cast_options": {"curr_pref": <str>, "curr_suff": <str>, "decimal_p": <str>, "group_sep": <str>, "mathesar_casting": <bool>},

即：curr_pref（货币前缀，如$）、curr_suff（货币后缀，如元）、decimal_p（小数点符号）、group_sep（千位分组符号）以及mathesar_casting（是否使用 Mathesar 自定义转换）五个键。

真正决定"哪些选项可以被应用"的是 SQL 层的表达式构建函数msar.build_cast_expr，位于 db/sql/05_msar.sql。该函数会根据目标类型的 regtype 分支处理选项：

CREATE OR REPLACE FUNCTION msar.build_cast_expr( val text, type_ text, cast_options jsonb ) RETURNS text AS $$/* Build an expression for casting a column in Mathesar, returning the text of that expression. ... */ SELECT msar.get_cast_function_name(type_::regtype) || '(' || CONCAT_WS(', ', val, CASE WHEN NULLIF(cast_options, '{}'::jsonb) IS NOT NULL THEN CASE type_::regtype WHEN 'numeric'::regtype THEN CONCAT_WS(', ', 'group_sep =>' || quote_literal(cast_options ->> 'group_sep') || '::"char"', 'decimal_p =>' || quote_literal(cast_options ->> 'decimal_p') || '::"char"' ) WHEN 'mathesar_types.mathesar_money'::regtype THEN CONCAT_WS(', ', 'group_sep =>' || quote_literal(cast_options ->> 'group_sep') || '::"char"', 'decimal_p =>' || quote_literal(cast_options ->> 'decimal_p') || '::"char"', 'curr_pref =>' || quote_literal(COALESCE(cast_options ->> 'curr_pref', '')) || '::text', 'curr_suff =>' || quote_literal(COALESCE(cast_options ->> 'curr_suff', '')) || '::text' ) END END ) || ')' $$ LANGUAGE SQL RETURNS NULL ON NULL INPUT;

这段实现精确对应了 0.7.1 修复的两个要点：

1. 按目标类型分发选项：目标为numeric时只接受group_sep与decimal_p；目标为mathesar_types.mathesar_money时才额外拼接curr_pref、curr_suff。这从机制上杜绝了"把货币前缀/后缀强加到数字列"的错误；
2. 空选项兜底：外层NULLIF(cast_options, '{}'::jsonb)保证空对象不会进入参数拼接分支，COALESCE(cast_options ->> 'curr_pref', '')则对缺失的键给出空字符串兜底，避免空值/不适用的选项导致转换失败。

在此基础上，msar.retype_column（同文件后续部分）负责真正执行"改名 → 构建转换表达式 → 执行ALTER TABLE"的完整流程，而 db/sql/05_msar.sql 中msar.set_old_col_default也在重设默认值时复用build_cast_expr，保证默认值表达式与列类型保持一致。

SQL 测试用例也覆盖了这一行为。db/sql/test_sql_functions.sql 中定义了三种典型的cast_options：

cast_options_1 jsonb := '{"mathesar_casting": true}'::jsonb; cast_options_2 jsonb := '{"decimal_p": ".", "group_sep": "", "mathesar_casting": true}'::jsonb; cast_options_3 jsonb := '{"curr_pref": "$", "curr_suff": "", "decimal_p": ".", "group_sep": ",", "mathesar_casting": true}'::jsonb;

并分别用于向boolean、numeric、mathesar_types.mathesar_money的msar.retype_column调用，验证"数字类目标类型不带货币选项、货币类型携带完整格式化选项"的组合均能正确执行。

前端如何回传 cast_options

cast_options的前端类型定义在 mathesar_ui/src/api/rpc/columns.ts：

/** * The ColumnCastOptions are returned when getting column type suggestions. They * are not inspected or used directly by the front end, but instead passed back * to the tables.get_import_preview and/or columns.patch endpoints as needed if * the user accepts Mathesar's type suggestions. */ export type ColumnCastOptions = Record<string, unknown>;

从注释可以确认数据流：类型建议接口返回ColumnCastOptions→ 前端不解析其含义 → 用户接受建议后原样回传给tables.get_import_preview或columns.patch端点。这正是 CSV 导入场景下类型推断的落点：

• 导入预览阶段，mathesar_ui/src/pages/import/preview/importPreviewPageUtils.ts 的buildColumnPreviewSpec会把cast_options写入预览规格，finalizeColumn再把它们并入ColumnPatchSpec提交给后端；
• 若后端在拼接转换表达式时错误地把货币选项套到 numeric 列上（0.7.0 的回归），整条导入或列修改链路就会失败——这解释了为何该 bug 对"CSV 导入新建表"和"类型推断调整"两个场景打击最大。

此外，mathesar_ui/src/api/rpc/tables.ts 的导入预览请求类型同样声明了cast_options?: ColumnCastOptions，与上述数据流相互印证。

文档更新：Railway 一键部署链接修复

除核心 bug 修复外，0.7.1 还包含一处文档修正：更新了 Mathesar 的 Railway 一键部署模板 URL（PR #4967 "Fix railway link in docs"）。仓库中对应的部署文档位于 docs/docs/administration/install-railway.md，需要走 Railway 平台部署的读者可参考该指南核对最新模板入口。

0.8.0 兼容性预告：PostgreSQL 13 与 Python 3.9 即将停止支持

官方发布说明同时预告了下一个版本 0.8.0 的兼容性变化：0.8.0 将终止对 PostgreSQL 13 与 Python 3.9 的官方支持，建议在安装 0.8.0 之前先行升级这些依赖。官方明确表示：旧版本"很可能仍能运行"，但兼容性不再经过测试，且无法为不受支持版本上遇到的问题提供协助。

仓库中的 版本支持策略文档 给出了更精确的版本矩阵：

从该文档还可得知：Mathesar 对"支持"的定义是自动化测试套件会在对应版本上运行并主动维护兼容性；不受支持的版本由用户自行承担风险。另需注意，Python 版本支持主要针对从零安装（Install From Scratch）方式，Docker 镜像则自带固定的 Python/PostgreSQL 版本，不受宿主环境 Python 版本影响。

升级到 0.7.1：Docker Compose 方式

如果使用 Docker Compose 安装 Mathesar，执行以下命令即可拉取最新镜像并滚动升级：

docker compose -f /etc/mathesar/docker-compose.yml up --pull always -d

• --pull always：确保每次启动前都重新拉取最新镜像（即 0.7.1）；
• -d：以守护进程（detached）方式后台运行。

⚠️注意：如果你的安装目录不是/etc/mathesar/，请将命令中的路径替换为实际目录。

仓库根目录的 docker-compose.yml 展示了官方推荐的生产部署拓扑：service（Mathesar 主服务，内部端口 8000，仅对容器网络暴露）、db（PostgreSQL 17，pgautoupgrade/pgautoupgrade:17-bookworm镜像）、caddy-reverse-proxy（Caddy 反代，映射宿主 80/443 端口并自动签发 SSL 证书），并声明了 Docker v23+、Docker Compose v2.10+ 的前置要求。升级时该拓扑与挂载卷（./msar/static、./msar/media、./msar/secrets、./msar/pgdata、./msar/caddy）均保持不变，数据不会因镜像更新而丢失。完整的安装与配置说明可参考 Docker Compose 安装指南。

升级到 0.7.1：直接安装（Linux / macOS / WSL）

对于不使用 Docker、直接在系统上安装 Mathesar 的部署，官方提供了一个 install 脚本，同时支持全新安装与升级。升级步骤如下。

1. 进入安装目录

先确认你的 Mathesar 安装目录（注意：不要带末尾斜杠，不要使用$HOME之类的变量），然后进入：

cd <你的 Mathesar 安装目录>

2. 下载并运行 0.7.1 的安装脚本

curl -sSfL https://github.com/mathesar-foundation/mathesar/releases/download/0.7.1/install.sh -o install.sh chmod +x install.sh ./install.sh .

脚本的最后一个参数.表示当前目录即为安装目录，脚本会自动完成代码与依赖的升级。

3. 用 Mathesar systemd 服务替换旧的 gunicorn 服务

0.7.1 起推荐直接以 Mathesar 自身的 systemd 服务运行，替代以往包裹 gunicorn 的做法：

1. 停用并停止旧的 gunicorn 服务：

   systemctl disable gunicorn.service systemctl stop gunicorn.service

2. 按安装指南中的 systemd 服务配置创建 Mathesar 服务。指南中的服务单元大致如下（路径需替换为你的安装目录）：

   [Unit] Description=mathesar daemon After=network.target network-online.target Requires=network-online.target [Service] Type=notify User=mathesar Group=mathesar RuntimeDirectory=mathesar WorkingDirectory=<安装目录> ExecStart=/bin/bash -c '<安装目录>/bin/mathesar run' EnvironmentFile=<安装目录>/.env Restart=on-failure RestartSec=5s [Install] WantedBy=multi-user.target

   创建后执行systemctl daemon-reload并start/enable该服务，可用journalctl --unit=mathesar.service查看运行日志。

3. 移除旧的 gunicorn 服务文件：

   sudo rm /lib/systemd/system/gunicorn.service

注意：上述 systemd 步骤仅面向使用 systemd 的 Linux 服务器；macOS 可用launchd适配，Windows 建议在 Linux 虚拟机或 WSL 2 中部署。相关命令大多需要 root 或sudo权限。

4. 更新 Caddyfile 并重启 Caddy

若此前使用 Caddy 作为反向代理（提供 HTTPS 与 Let's Encrypt 自动证书），请：

1. 按安装指南中的 Caddy 配置更新/etc/caddy/Caddyfile，要点包括：域名直接写在 Caddyfile 的第一行、reverse_proxy指向 Mathesar 服务地址（默认localhost:8000）、并正确处理/media/*与/static/*的静态文件服务；
2. 重启 Caddy 服务：

   systemctl restart caddy.service

若此前在 Docker 部署中已使用caddy-reverse-proxy容器，则无需手动维护 Caddyfile，直接按上文 Docker Compose 方式升级即可。

5.（可选）仅本机使用、不作为系统服务运行

如果只在localhost上使用、且不希望以系统服务方式常驻运行，也可以：

1. 移除 gunicorn 与 caddy 两个服务；
2. 手动启动 Mathesar：

   mathesar run

升级后验证

升级完成后，建议按以下方式验证修复是否生效：

• 验证类型转换：进入任意现有表的列属性面板，尝试将 numeric 列转换为 money 类型（或反向转换），确认不再报错；
• 验证导入链路：执行一次 CSV 导入新建表操作，观察类型推断建议能否正常生成并应用（该路径会在预览阶段回传cast_options，见 importPreviewPageUtils.ts）；
• 验证服务状态：Docker 方式用docker compose -f /etc/mathesar/docker-compose.yml ps检查容器健康；systemd 方式用systemctl status mathesar.service与journalctl --unit=mathesar.service检查日志。

小结：0.7.1 虽然改动面很小，但精准修复了 0.7.0 性能优化引入的列类型转换回归——其底层修复逻辑（msar.build_cast_expr按目标类型分发cast_options、对空选项做兜底）在 db/sql/05_msar.sql 中清晰可见。对于仍停留在 0.7.0 的实例，建议尽快按本文的 Docker Compose 或直接安装步骤升级；同时可提前规划 0.8.0 的 PostgreSQL 13 与 Python 3.9 迁移，以保持官方支持范围内的兼容性。

• 数据库
• 后端
• 前端
• 协作