aadishajay/pgapp

## 面临的问题 你有一个 Postgres 数据库，但你还需要它周边那些枯燥的部分：几个 CRUD 页面、几个仪表板、登录功能和一个管理后台。 通常的选项会让你为了实现这个目标，去搭建一个*第二*系统——一个带有自己的认证服务和 API 网关的 BaaS，一个带有自己的托管 runtime 的低代码 SaaS，或者一个由你编写、部署并维护的 Node/Next 后端。如果 Postgres 已经持有了你的数据，那么以上每一个选项都是你和最终交付之间的额外负担。 ## pgapp 的替代方案 pgapp 删除了那一层。 你在一个纯文本 `.pgapp` 文件中描述应用——实体、页面、报表、表单、图表、认证——然后**一个单一的 Rust 二进制程序**会读取它，将定义作为普通数据行同步到 Postgres 中，构建参数化 SQL，并自行渲染 HTML。 没有 PostgREST。没有 Studio。没有生成的客户端 SDK。没有 JS 工具链。编辑文件——或者点击使用内置的 [App Builder](#the-app-builder)——然后重新加载。**这就是整个部署循环。** 这就是 Oracle APEX 的开发模型——交互式报表、PL/SQL 风格的服务器端 action、声明式动态 action——被重新构建为一个开放的、自托管的、支持 git diff 的单二进制替代方案，运行在你已有的基础设施上。 ## 30 行代码写就的完整应用 ``` app "Todo" { nav { item "Tasks" -> page Tasks } entity "tasks" { field id: id field title: text required field priority: text default Medium field done: boolean default false } page "Tasks" { report "Tasks" of tasks { columns: title, priority, done page_size: 10 } form "Add / edit task" of tasks { fields: title, priority, done item priority as radio ("Low", "Medium", "High") } } } ``` 这是一个**可搜索、可分页、可排序且支持内联创建/编辑/删除的列表**——经典的报表+表单（Report+Form）CRUD 模式——由于表单和报表在同一页面上共享一个实体，因此会自动连接。 没有路由处理器。没有手写 SQL。没有由你编写的客户端 JS。完整的语法——命名查询、所有组件类型、单文件或目录——都在[标记参考](./docs/markup.md)中。 ## 看看它

**交互式报表** —— 分面搜索、可排序的列，以及一个可见的提示（那个 `→`）在你触碰鼠标之前就告诉你某一行是可点击的。	**每行 SQL 生成的图表** —— 柱状图、环形图、饼图等，每个类别都会自动获得自己一致的颜色。
**App Builder 的实体编辑器** —— 选择一个真实的表，它的列、可空性和主键会自动为你填充到字段列表中。	**App Builder 的页面设计器** —— 左侧是组件树，右侧是实时的属性面板，更改会直接保存到 `.pgapp` 文件中。

在内置文件编辑器中编辑原始标记（VS-Code 风格的目录树，直接保存到磁盘）

更多屏幕截图和按功能划分的完整导览在 [`marketing/`](./marketing/index.html) 中。 ## 快速开始 **前置条件：** 一个可访问的 Postgres 服务器，并已安装 Rust。 ``` # 1. Build and install the binary cargo install --path . # 2. One-time setup: an instance (per machine), a workspace (a schema # for your app's tables), and a scaffolded starter app in it pgapp instance init pgapp workspace create --schema demo pgapp app create --workspace demo # 3. Serve it — this prints the app's URL and starts serving pgapp run .pgapp --workspace demo ``` 每一步都是交互式的，并会提示你输入所需的内容。这就是整个流程。 **想先看全貌？** 运行内置的展示项目，而不是空白脚手架： ``` pgapp workspace create --schema demo pgapp run examples/showcase.pgapp --workspace demo ``` `examples/showcase.pgapp` 是一个单文件，涵盖了每种组件类型——报表、表单、可编辑表格、全部六种图表类型、日历、地图、分面搜索、动态 action——并且主页链接到每个组件。带有种子数据的完整演示：[入门指南](./docs/getting-started.md)。 ## 功能 - **一个文件描述整个应用** —— 页面、实体、查询、导航、认证 —— 在启动时和 `/admin/reload` 时同步，无需重启。 - **13 种组件类型**：Report、Form、EditableTable、Chart、Calendar、Map、FacetedSearch、Region、DynamicContent、Action、Button、Link、Text。 → [组件](./docs/components.md) - **交互式报表** —— 搜索、逐列过滤、保存的视图、排序、聚合、控制中断、CSV 导出 —— 全是声明式的。 → [报表](./docs/reports.md) - **19 种内置表单字段类型**，外加一个每种类型一个文件的插件扩展点，供你自定义。 → [表单](./docs/forms.md) - **6 种图表类型**，默认情况下是无需外部依赖的内联 SVG —— 或者可以替换为任何 JS 图表库。 → [图表](./docs/charts.md) - **服务器端 action** —— 一个 Rust 模块或一个普通的 PL/pgSQL 调用 —— 连接到按钮、动态 action 或报表的 `before_load`。 → [Action](./docs/actions.md) - **声明式动态 action**（`on change of x { show/hide/set/refresh }`）外加一个无需刷新页面的 ajax callback。 - **一个区块搞定认证** —— `auth { }` 开启了 argon2 哈希登录、服务器端会话以及基于角色的页面和组件访问控制，精细到单个按钮。 → [认证](./docs/authentication.md) - **一切皆可插拔** —— 主题、图标、图表后端、表单组件；内置六种主题。 → [主题](./docs/themes.md) - **一个内置的点击式管理应用** 涵盖了以上所有内容 —— 包括一个 APEX-SQL-Workshop 风格的临时 SQL 运行器 + 对象浏览器，以及一个克隆并编辑的主题编辑器。 → [App Builder](#the-app-builder) - **单进程支持多租户** —— instance → workspace (schema) → app，一个连接池支持任意数量的应用。 → [架构](./docs/architecture.md) ## 它的与众不同之处 pgapp 重新实现了许多来自 Oracle APEX 的真正优秀的理念。这种借鉴并不是最有趣的部分。以下这些设计决策才是： - **应用*就是*一个可移植的文本文件，而 GUI 永远不会破坏这一点。** 每一个 App Builder 的修改都是对你实际的 `.pgapp` 文件进行的基于行的**文本拼接** —— 对于你*没有*触碰的所有内容，其手写的格式和注释都能逐字节地保留。通过 UI 点击或手动编辑文件：具有相同的唯一事实来源，且两者在 git 中都非常易于进行 diff 对比。 - **绑定类型来自 Postgres，而不是来自你。** 命名查询的 `:param` 标记通过询问 Postgres 自己的 wire-protocol `Describe` 消息来获取每个参数所需的类型 —— 每次同步时都会重新获取，无需手动声明类型转换，也不存在会失去同步的 ORM 模型层。 - **一个进程，N 个租户，热注册。** `pgapp run` 将应用添加到活动服务器的路由表中，无需重启，也不会导致任何正在提供服务的应用停机。 - **管理构建器无法编辑自身** —— 这是故意的，在两个独立的地方进行了强制执行（一次在列表中，另一次在每次执行修改路由时在服务器端进行）。这是一个大多数自托管管理工具都懒得去做的、微小但刻意为之的安全特性。 ## 架构 ``` .pgapp markup file │ parse ▼ AppDef (in memory) │ validate + sync ▼ pgapp_meta.* tables ──creates──▶ . (your real data) │ load ▼ RuntimeApp { pages → components } │ ▼ Axum router ── generic, metadata-driven CRUD + JSON ``` 一个 Rust 二进制程序，一个共享的 Postgres 连接池，任意数量的应用。在请求时使用的每个 SQL **标识符**都会在同步时根据 lexer 自身的字符集进行验证 —— 可以安全地拼接到生成的 SQL 中；而每个用户提供的**值**始终是绑定参数。完整的架构图、源码目录结构和完整的路由表：[架构](./docs/architecture.md)。 ## 示例应用 这些都是你可以运行的真实应用，而不是玩具代码片段 —— 包括负载测试的 fixture： | 应用 | 展示了什么 | |---|---| | [`examples/todo.pgapp`](./examples/todo.pgapp) | 最简结构 —— 一个实体，Report+Form CRUD，一个图表 | | [`examples/helpdesk.pgapp`](./examples/helpdesk.pgapp) | 两个实体，仪表板，两种分页模式，认证，所有 item 类型，`vivid` 主题 | | [`examples/venpay.pgapp`](./examples/venpay.pgapp) | 手工移植的真实 Oracle APEX 应用 —— 参见 [从 Oracle APEX 迁移](./docs/migration-from-apex.md) | | [`examples/showcase.pgapp`](./examples/showcase.pgapp) | 每种组件类型，全部六种图表类型，所有三种服务器端 action 风格，分布在 12 个页面中 | | [`examples/helpdesk-modular/`](./examples/helpdesk-modular/) | 帮助台应用拆分为多个文件而不是合并在一个文件中 —— 语法相同，无需重构 | | [`examples/nexus-erp/`](./examples/nexus-erp/) | **200 个页面，60 个实体，15 个文件。** 负载测试 fixture：30 个线程持续达到 **~900 req/s**（p50 ~27 ms，p99 ~94 ms），且**零错误** | ## App Builder 每个 pgapp 实例都在 `/pgapp/builder` 提供了一个内置的管理应用，并自动完成配置——这样你就可以通过点击来构建和编辑应用，而无需通过 SSH 手动编辑标记。 它为你提供了一个 APEX-Page-Designer 风格的分割视图（可点击的组件树 + 停靠的、带类型的属性编辑器）、完整的数据模型和命名查询编辑（提供从你真实的 Postgres 列中提取的建议）、加密的密钥、带有对象浏览器的临时 SQL 运行器、克隆并编辑的主题编辑器，以及实时的应用/workspace 脚手架生成或销毁功能。 令人意想不到的是：**App Builder 本身就是一个 pgapp 应用** —— 它不是一个硬塞进框架中的定制面板 —— 只有一个刻意的例外，一个硬编码的保护机制，拒绝让该应用编辑自身。

_{Scaffolding a brand-new app in the builder — name it, pick a workspace and theme, and it's live. Every click is a text splice into a real .pgapp file.}

完整演示：[App Builder](./docs/app-builder.md)。 ## 功能对比 与人们首选的工具相比，pgapp 占据了一个更狭窄、更有主见的细分领域。在选择它之前值得了解一下： | | **pgapp** | Supabase | PocketBase | Appsmith / Budibase / ToolJet | |---|---|---|---|---| | 核心语言 | Rust | 主要是 TS + Postgres 扩展 | Go | Java / Node（视情况而定） | | 应用定义 | 纯文本文件，通过 git 进行版本控制 | 控制台 + SQL + 客户端 SDK | 控制台 + 客户端 SDK | 拖拽式操作，以 JSON 格式存储 | | 数据库 | Postgres —— 自带 | Postgres（托管或自托管） | SQLite，嵌入式 | 连接到你已在运行的 DB | | Runtime 形态 | 一个静态二进制程序 | 多容器技术栈（Studio, GoTrue, PostgREST, Realtime, Kong, …） | 一个静态二进制程序 | 你部署的一个应用服务器 | | 管理 / 构建 UI | 内置，其本身就是一个 pgapp 应用 | 独立的 Studio 服务 | 内置的管理 UI | 是的 —— 它*本身*就是产品 | | 最适合 | 希望快速构建强类型 CRUD 应用且活动部件最少的 Postgres 优先团队 | 完整的 BaaS：认证、存储、实时通信、边缘函数 |型嵌入式后端，单二进制部署 | 内部工具构建者，DB 无关，面向团队 | 这些选项中没有哪一个是绝对“更好”的。pgapp 适用于 Postgres **已经**是“数据存在哪里”这一问题的答案的情况。想要一个完整的 BaaS（认证/存储/实时通信/边缘函数）？Supabase 是更完整的答案。需要它具备 DB 无关性且面向团队？那就选择内部工具构建器。 ## 来自社区 ## 文档 README 只是简单的介绍。[文档](./docs/README.md)才是真正的参考资料： | 文档 | 内容包含 | |---|---| | [入门指南](./docs/getting-started.md) | 安装、运行你的第一个应用、内置演示、脚手架、instance 模式 | | [架构](./docs/architecture.md) | 标记 → 元数据 → runtime 流水线、源码目录结构、完整路由表、多应用路由 | | [标记语言](./docs/markup.md) | 完整的 `.pgapp` 语法 —— 实体、页面、查询、目录、集合 | | [组件](./docs/components.md) | 深入介绍每种组件类型 | | [报表](./docs/reports.md) | 分页、搜索和保存视图、计算列、格式化掩码、预加载 action | | [表单和 item 类型](./docs/forms.md) | `ItemType` trait 和所有内置的字段组件 | | [图表和图标](./docs/charts.md) | 图表类型、可插拔的渲染后端、图标包 | | [认证](./docs/authentication.md) | `auth {}`、角色、组件级 `requires:`、认证方案 | | [Action](./docs/actions.md) | 服务器端 action 模块、动态 action、ajax callback | | [主题](./docs/themes.md) | CSS 契约、内置主题、主题编辑器、移动端 | | [App Builder](./docs/app-builder.md) | 完整的点击式管理应用演示 | | [从 Oracle APEX 迁移](./docs/migration-from-apex.md) | 概念对概念的映射表 | | [密钥](./docs/secrets.md) | 用于 action 的静态加密凭证 | | [路线图](./docs/roadmap.md) | 诚实地列出的已知不足 | ## 路线图 pgapp 有意被设计为最小的端到端流程，而不是一个完成的框架。目前还没有真正的外键关系，没有多步骤的流程块，也没有拖拽式的自由页面组合 —— 完整且诚实的清单，以及每个不足背后的原因，都在 [docs/roadmap.md](./docs/roadmap.md) 中。 如果其中哪一项对你来说是决定性的障碍，那么提前了解这一点非常有用 —— 而且这正是我们非常欢迎 PR 的地方。 ## License [MIT](./LICENSE).

**如果 pgapp 正是你一直想要的 Postgres 工具类型，给它点个 ⭐ 可以帮助其他人发现它。** [快速开始](#quick-start) · [文档](./docs/README.md) · [路线图](./docs/roadmap.md) · [App Builder](./docs/app-builder.md)

标签：CRUD, PostgreSQL, Rust, Web开发框架, 低代码平台, 可视化界面, 无代码/低代码, 测试用例, 网络流量审计, 调试插件, 通知系统