SQLPage 0.47.0 介绍与选型指南

目标：面向"会写 SQL 就想直接做出 Web 页面"的读者，梳理 SQLPage 的定位、工作原理、版本信息基准与适用边界，并给出与 PostgREST、Metabase、Apache Superset 等"数据驱动 Web"方案的量化选型对比。全部关键结论均标注官方来源与查询日期（2026-10-28）；运行行为数据来自本系列在 Ubuntu 22.04.5 LTS 上的实测，安装与验证过程见《Ubuntu 22.04 安装 SQLPage 0.47.0 指南》。

一、SQLPage 是什么

1.1 一句话定位

SQLPage 是一个用 SQL 编写 Web 应用的开源框架。其 GitHub 官方仓库（sqlpage/SQLPage）的描述为："Fast SQL-only data application builder. Automatically build a UI on top of SQL queries."（用纯 SQL 快速构建数据应用，自动在 SQL 查询之上生成用户界面）（来源：GitHub 仓库 sqlpage/SQLPage，查询日期 2026-10-28）。官方网站为 sql-page.com。

它解决的是一个很具体的痛点：内部工具、管理面板、数据报表这类"以数据库为中心"的小型 Web 应用，传统做法需要前端框架 + 后端接口 + ORM 三层配合，而掌握 SQL 的人远多于掌握全栈开发的人。SQLPage 把整个应用压缩成"一个二进制 + 一堆 .sql 文件"。

1.2 工作模型：.sql 文件即页面

SQLPage 是一个 Web 服务器，把 URL 路径映射到 web root 目录下的 .sql 文件：访问 /index 就执行 index.sql，访问 /users/list 就执行 users/list.sql。文件里每一条 SELECT 语句都会把查询结果交给一个"组件（component）"渲染成 HTML——SELECT 的第一列固定叫 component，指定用哪个官方组件渲染，其余列是该组件的参数。

一个最小页面只需一条 SELECT：

SELECT 'text'    AS component,
       '由 SQL 驱动的第一个页面' AS title,
       '本页面没有任何传统后端代码，仅由一条 SELECT 语句渲染。' AS contents_md;

浏览器访问后即得到一张带标题的富文本卡片。组件库里还有 list（列表）、table（数据表格）、form（表单）、chart（图表）、card、steps 等，覆盖了信息展示与数据录入两大类场景（组件清单见官方文档 sql-page.com/components）。

1.3 技术形态与数据库支持

• 技术栈：Rust 编写的单一静态链接二进制，无 Python/Node/Java 运行时依赖；v0.47.0 的 Linux 版压缩包仅 12.9 MB，解压后主程序 34 MB（实测）。
• 数据库支持：SQLite、PostgreSQL、MySQL、MariaDB、Microsoft SQL Server，以及通过内置 ODBC 驱动管理器对接 Oracle、Snowflake、DuckDB 等（来源：官方 configuration.md 的 Database connection strings 一节，查询日期 2026-10-28）。
• 内置 SQLite：不配置任何数据库时，SQLPage 默认使用配置目录下的 SQLite 文件库（实测日志："No DATABASE_URL provided, ... creating a new database file."），零外部依赖即可跑通完整增删改查。
• 许可：MIT（来源：仓库 LICENSE.txt 与 GitHub 仓库元数据，查询日期 2026-10-28）。

二、版本与信息基准（查询日期 2026-10-28）

发布节奏：从 Release 历史看保持了高频小版本迭代，0.x 阶段意味着 API 与组件参数偶有调整，升级时需关注 CHANGELOG——本系列的升级与回滚操作见《SQLPage 0.47.0 常用 CLI 命令与运维实战》。

三、核心机制：组件、连接与安全的三层设计

3.1 组件渲染层

页面 = 若干条 SELECT，每条 SELECT 一个组件。组件参数即查询结果的列名，因此"改页面"和"改查询"是同一件事。组件模板基于 Handlebars，也支持在配置目录 templates/ 下放置 .handlebars 文件自定义组件（来源：官方 configuration.md 的 Custom components 一节）。

3.2 数据访问层

• 连接池：max_database_pool_connections 默认按数据库引擎区分（SQLite 16、PostgreSQL 50、MySQL 75），连接重试 6 次、获取超时 10 秒（来源：官方 configuration.md，2026-10-28）。
• 连接初始化/清理：配置目录下的 on_connect.sql 在每个新连接建立时执行（如设置时区、ATTACH 附加库），on_reset.sql 在请求结束后执行（如 ROLLBACK、PostgreSQL 的 DISCARD ALL），用于隔离请求间的连接状态。
• 迁移：migrations/ 目录下的带时间戳前缀 SQL 文件在启动时按序自动执行，执行记录写入数据库的 _sqlx_migrations 表（实测确认）。

3.3 安全层

• 默认开启内容安全策略（CSP），script-src 'self' 'nonce-{NONCE}' 占位符按请求注入随机 nonce（实测响应头确认）。
• environment = "production" 后 SQL 报错只返回通用提示与 HTTP 500，不再向用户暴露表名、SQL 语句与行号（实测 development 与 production 两种回显对比确认）。
• 内置 OpenID Connect（OIDC）单点登录，可按路径前缀划分保护范围；allow_exec 默认关闭，显式开启才允许 SQL 调用 sqlpage.exec 执行系统命令（来源：官方 configuration.md）。

四、适用与不适用场景

4.1 适合 SQLPage 的场景

1. 内部工具与管理面板：运营后台、工单列表、资产台账、审批看板——数据在库里，页面只是查询和表单。
2. DBA/运维自助平台：慢查询展示、备份状态页、巡检报表；配合 systemd 托管与只读数据库账号，一天内可上线。
3. 嵌入式/边缘部署：空闲常驻内存约 3.6 MB（本系列实测，v0.47.0 空闲态 systemd cgroup 数据），加上文件型 SQLite，树莓派级别的小机器也能跑。
4. 原型验证：数据模型建好之后，先直接暴露查询结果给业务方确认字段与口径，再决定是否正式开发。

4.2 不适合 SQLPage 的场景

1. 复杂业务逻辑系统：业务规则全部落在 SQL 里会迅速失控，需要应用层代码（订单流转、库存扣减这类强状态机场景）。
2. 面向 C 端的高交互产品：组件是预制的专业风格模板，做不了高度定制的交互体验与自定义视觉体系。
3. 无数据库控制权的环境：页面即查询，需要自己建表、管索引；如果连建表权限都要审批，落地会很难受。
4. 强多租户权限隔离：权限控制需要自己在每条 SQL 里写过滤条件，或依赖 OIDC 注入的身份做判断，缺乏框架级行级权限。

五、与同类方案的量化选型对比

"数据驱动 Web"赛道上，SQLPage 并不是唯一选择。下表从定位、技术形态、资源占用、许可与社区五个维度对比（仓库数据均来自 GitHub API，查询日期 2026-10-28；SQLPage 内存为本系列实测，其余方案不引入未实测数字，以定性描述）：

5.1 三条选型结论

1. 要"SQL 变成能用的页面"，选 SQLPage。PostgREST 的产出物是 API，前端还要另起炉灶；Metabase/Superset 是"看"数据的 BI 工具，几乎不做"写"数据的表单流。只有 SQLPage 把查询、表单、页面导航做成一个自包含应用。
2. 看板选 BI，应用选框架。如果需求止步于"给老板看图表"，Metabase/Superset 的拖拽体验完胜；一旦出现"填个表单、更新一条记录、走个流程"，BI 工具就到了边界，这正是 SQLPage 的主场。
3. 资源预算是小机器场景的决定项。3.6 MB 对 GB 级是三个数量级的差距；在仅 512 MB 内存、无独立数据库的边缘环境，SQLPage + SQLite 几乎是唯一体面的"SQL 直出页面"方案。

5.2 一个混合架构建议

三者并不互斥：PostgREST 对外供 API，SQLPage 做内部管理页，Metabase 给分析师看板——它们连接的是同一个 PostgreSQL。SQLPage 官方文档也专门给出 Nginx 反向代理与子路径（site_prefix）共存的部署指引（来源：官方 configuration.md 的 Custom URL routes 一节）。

六、本系列导航

• 安装部署：《Ubuntu 22.04 安装 SQLPage 0.47.0 指南》（https://www.quzuo.net/document/BdtuMjKpDGfZ）——官方二进制校验、目录布局、systemd 托管与首页面验收；
• 配置详解：《SQLPage 0.47.0 配置详解与参数生效验证》（https://www.quzuo.net/document/Ctizz1tZy2fN）——sqlpage.toml 核心参数逐项实测生效；
• 命令运维：《SQLPage 0.47.0 常用 CLI 命令与运维实战》（https://www.quzuo.net/document/5hWuXdBdgT1b）——CLI 参数、迁移、日志级别、升级与备份。