> [!NOTE] > 本文档由 WeHub 基于上游 README 翻译整理,属于社区翻译,非官方中文文档。 > [English](./README.en.md) · [原始项目](https://github.com/sqlpage/SQLPage) · [上游 README](https://github.com/sqlpage/SQLPage/blob/HEAD/README.md) > 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。

SQLpage

[![一段简短视频,介绍 sqlpage 的概念](./docs/sqlpage.gif)](./docs/sqlpage.mp4) [SQLPage](https://sql-page.com) 是一款**纯 SQL** Web 应用构建器。 它允许你通过将简单的数据库查询转换为交互式网站, 快速构建强大的以数据为中心的用户界面。 使用 SQLPage,你只需编写包含数据库查询的简单 `.sql` 文件, 用于查询、分组、更新、插入和删除数据,即可获得美观整洁的网页, 以文本、列表、网格、图表和表单等形式展示你的数据。 ## 示例
代码结果
```sql SELECT 'list' as component, 'Popular websites' as title; SELECT name as title, url as link, CASE type WHEN 1 THEN 'blue' ELSE 'red' END as color, description, icon, active FROM website; ``` ![SQLPage 列表组件](./docs/demo-list.png)
```sql SELECT 'chart' as component, 'Quarterly Revenue' as title, 'area' as type; SELECT quarter AS x, SUM(revenue) AS y FROM finances GROUP BY quarter ``` ![SQLPage 列表组件](./docs/demo-graph.png)
```sql SELECT 'form' as component, 'User' as title, 'Create new user' as validate; SELECT name, type, placeholder, required, description FROM user_form; INSERT INTO user SELECT $first_name, $last_name, $birth_date WHERE $first_name IS NOT NULL; ``` ![SQLPage 列表组件](./docs/demo-form.png)
```sql select 'tab' as component, true as center; select 'Show all cards' as title, '?' as link, $tab is null as active; select format('Show %s cards', color) as title, format('?tab=%s', color) as link, $tab=color as active from tab_example_cards group by color; select 'card' as component; select title, description, color image_url as top_image, link from tab_example_cards where $tab is null or $tab = color; select 'text' as component, sqlpage.read_file_as_text('footer.md') as contents_md ``` ![卡片组件 SQL 示例](./docs/cards.png)
## 支持的数据库 - [SQLite](https://www.sqlite.org/index.html),,包括加载扩展(如 *Spatialite*)的能力(参见 [load extensions](./configuration.md))。 - [PostgreSQL](https://www.postgresql.org/), 及其他兼容数据库,如 *YugabyteDB*、*CockroachDB* 和 *Aurora*。 - [MySQL](https://www.mysql.com/), 及其他兼容数据库,如 *MariaDB* 和 *TiDB*。 - [Microsoft SQL Server](https://www.microsoft.com/en-us/sql-server), 及所有兼容的数据库和提供商,如 *Azure SQL* 和 *Amazon RDS*。 - 任何**兼容 ODBC 的数据库**,例如 [*ClickHouse*](https://github.com/ClickHouse/clickhouse-odbc), [*MongoDB*](https://www.mongodb.com/docs/atlas/data-federation/query/sql/drivers/odbc/connect), [*DuckDB*](https://duckdb.org/docs/stable/clients/odbc/overview.html), [*Oracle*](https://www.oracle.com/database/technologies/releasenote-odbc-ic.html), [*Snowflake*](https://docs.snowflake.com/en/developer-guide/odbc/odbc), [*BigQuery*](https://cloud.google.com/bigquery/docs/reference/odbc-jdbc-drivers), [*IBM DB2*](https://www.ibm.com/support/pages/db2-odbc-cli-driver-download-and-installation-information),,以及通过各自 ODBC 驱动连接的其他许多数据库。 ## 快速开始 [在 SQLPage 官网阅读官方*快速开始*指南](https://sql-page.com/get_started.sql). ### 使用可执行文件 最简单的入门方式是,从 [发布页面](https://github.com/sqlpage/SQLPage/releases). 下载最新版本。 - 下载与你的操作系统(linux、macos 或 windows)对应的二进制文件。 - 解压:`tar -xzf sqlpage-*.tgz` - 运行:`./sqlpage.bin` ### 使用 Docker 若要在服务器上运行,可以使用 [Docker 镜像](https://hub.docker.com/r/lovasoa/SQLPage): - [安装 Docker](https://docs.docker.com/get-docker/) - 在终端中运行以下命令: - `docker run -it --name sqlpage -p 8080:8080 --volume "$(pwd):/var/www" --rm lovasoa/sqlpage` - (`"$(pwd):/var/www"` 允许 sqlpage 从你当前工作目录运行 sql 文件) - 创建一个名为 index.sql 的文件,内容来自[此示例](./index.sql) - 在浏览器中打开 https://localhost:8080 - 你也可以选择挂载一个包含 sqlpage 配置文件、 自定义组件和迁移的目录 (参见 [configuration.md](./configuration.md))到容器中的 `/etc/sqlpage`。 - 例如,你可以使用: - `docker run -it --name sqlpage -p 80:8080 --volume "$(pwd)/source:/var/www" --volume "$(pwd)/configuration:/etc/sqlpage:ro" --rm lovasoa/sqlpage` - 并将你的网站放在名为 `source` 的文件夹中,将 `sqlpage.json` 放在名为 `configuration` 的文件夹中。 - 如果你想构建自己的 Docker 镜像,不建议以原始 sqlpage 镜像为基础,因为它被极度精简,可能不包含你所需的依赖。相反,你可以以 debian 为基础,并将官方镜像中的 sqlpage 二进制文件复制到你自己的镜像中: - ```Dockerfile FROM debian:stable-slim COPY --from=lovasoa/sqlpage:main /usr/local/bin/sqlpage /usr/local/bin/sqlpage ``` 我们仅为 x86_64 架构提供编译好的二进制文件,但为其他架构(包括 arm64 和 armv7)提供 Docker 镜像。如果你想在树莓派或 更便宜的 ARM 云实例上运行 SQLPage,使用 Docker 镜像是最简单的方式。 ### 在 Mac OS 上使用 Homebrew Mac OS 用户的另一种选择是使用 [SQLPage 的 Homebrew 软件包](https://formulae.brew.sh/formula/sqlpage). - [安装 Homebrew](https://brew.sh/) - 在终端中运行以下命令: - `brew install sqlpage` ### ODBC 配置 SQLPage 支持 ODBC 连接,用于连接没有原生驱动的数据库。 如果你想使用内置数据库驱动(SQLite、PostgreSQL、MySQL、Microsoft SQL Server)之一,可以跳过本节。 Linux 和 MacOS 发布版二进制文件包含内置的静态链接 ODBC 驱动管理器(unixODBC)。 你仍需要安装或提供你要连接的数据库对应的 ODBC 驱动。 #### 安装 ODBC 数据库驱动 - [DuckDB](https://duckdb.org/docs/stable/clients/odbc/overview.html) - 如果你使用 Docker,提供预装 DuckDB ODBC 驱动的 DuckDB 启用镜像变体 - 使用 `-duckdb` 后缀:`lovasoa/sqlpage:main-duckdb` 或 `lovasoa/sqlpage:latest-duckdb` - 预配置为连接容器内 `/var/lib/sqlpage/duckdb.db` 处的 DuckDB - 要自定义[连接选项](https://duckdb.org/docs/stable/clients/odbc/configuration),,请设置 `DATABASE_URL`: - `docker run -e DATABASE_URL="Driver=DuckDB;Database=/path/to/your.db" -p 8080:8080 lovasoa/sqlpage:main-duckdb` - 要持久化 DuckDB 数据库,请挂载卷: - `docker run -v ./data:/var/lib/sqlpage lovasoa/sqlpage:main-duckdb` - [Snowflake](https://docs.snowflake.com/en/developer-guide/odbc/odbc) - [BigQuery](https://cloud.google.com/bigquery/docs/reference/odbc-jdbc-drivers) - 对于其他数据库,请遵循数据库官方的 ODBC 安装说明。 #### 连接到你的数据库 - 查找你的[连接字符串](https://www.connectionstrings.com/). - 它看起来会像这样:`Driver=/opt/snowflake_odbc/lib/libSnowflake.so;Server=xyz.snowflakecomputing.com;Database=MY_DB;Schema=PUBLIC;UID=my_user;PWD=my_password` - 它必须引用你之前安装的数据库驱动路径,以及驱动本身所需的任何连接参数。请遵循驱动自身文档中的说明。 - 在 [DATABASE_URL 配置选项](./configuration.md) 中使用它 ## 工作原理 ![架构图](./docs/architecture-detailed.png) SQLPage 是一个用 [rust](https://en.wikipedia.org/wiki/Rust_(programming_language)) 编写的[Web 服务器](https://en.wikipedia.org/wiki/Web_server), 并以单个可执行文件的形式分发。 当它收到以 `.sql` 结尾的 URL 请求时,会找到对应的 SQL 文件,在数据库上执行, 并将 Web 请求中的信息作为 SQL 语句参数传入。 当数据库开始为查询返回行时, SQLPage 将行中的每条信息映射到 其预定义组件模板中的一个参数,并将结果流式传输回 用户的浏览器。 ## 示例 - [待办清单](./examples/todo%20application/):一个简单的待办清单应用,演示如何使用 SQLPage 创建基本的 CRUD 应用。 - [图表、表格、表单与交互](./examples/plots%20tables%20and%20forms/):一个简短且注释充分的演示,展示如何使用图表、表格、表单和交互功能,根据 URL 参数筛选数据。 - [迷你 Splitwise 克隆版](./examples/splitwise):一个共享费用追踪应用 - [Corporate Conundrum](./examples/corporate-conundrum/):用 SQL 实现的棋盘游戏 - [主从表单](./examples/master-detail-forms/):展示如何实现一组简单表单,向具有一对多关系的数据库表插入数据。 - [SQLPage 官方站点与文档](./examples/official-site/):项目官方站点的 SQL 源代码,https://sql-page.com - [图片库](./examples/image%20gallery%20with%20user%20uploads/):用户可登录并上传图片的图片库。演示如何使用会话 Cookie 实现用户认证系统,以及如何处理文件上传。 - [用户管理](./examples/user-authentication/):包含用户注册、登录、登出和保密页面的认证演示。使用 PostgreSQL。 - [构建 JSON API 并在前端集成 React 组件](./examples/using%20react%20and%20other%20custom%20scripts%20and%20styles/):展示如何在 SQLPage 网站中集成 React 组件,以及如何轻松用 SQLPage 构建 REST API。 - [处理文件上传](./examples/image%20gallery%20with%20user%20uploads):已认证用户可通过上传表单发布新图片的图片库。 - [从 CSV 文件批量导入数据](./examples/official-site/examples/handle_csv_upload.sql) :一个简单的表单,让用户导入 CSV 文件以填充数据库表。 - [使用 PostgreSQL 存储过程的高级认证示例](https://github.com/mnesarco/sqlpage_auth_example) - [基于 SQLite 的复杂 Web 应用,包含用户管理、文件上传、图表、地图、表格、菜单等](https://github.com/DSMejantel/Ecole_inclusive) - [单点登录](./examples/single%20sign%20on):演示如何在 SQLPage 中实现 OAuth 和 OpenID Connect(OIDC)认证。该演示还包含 CAS(Central Authentication Service)客户端。 - [深色主题](./examples/light-dark-toggle/) :演示如何让用户在浅色主题和深色主题之间切换,并保存用户偏好。 你可以使用 [SQLPage 在 Replit 上的在线演示](https://replit.com/@pimaj62145/SQLPage).,无需在电脑上安装任何东西即可在线试用所有示例。 ## 配置 SQLPage 可通过放置在 `sqlpage/sqlpage.json` 中的配置文件 或环境变量(如 `DATABASE_URL` 或 `LISTEN_ON`)进行配置。 更多信息,请阅读 [`configuration.md`](./configuration.md)。 此外,可以通过将 [`.handlebars`](https://handlebarsjs.com/guide/) 文件放在 `sqlpage/templates` 中来创建自定义组件。[示例](./sqlpage/templates/card.handlebars)。 ### HTTPS SQLPage 原生且透明地支持 HTTP/2 和 HTTPS。 只需设置 `SQLPAGE_HTTPS_DOMAIN=example.com`,SQLPage 就会自动申请受信任的证书, 并用它加密所有用户的流量。 你无需繁琐的手动配置, 用户也不会看到烦人的“连接不安全”提示! ## 无服务器(Serverless) 你可以将 SQLpage [无服务器](https://en.wikipedia.org/wiki/Serverless_computing) 方式运行, 方法是将其编译为 [AWS Lambda 函数](https://aws.amazon.com/lambda/). 一种简单的方式是使用提供的 Docker 镜像: ```bash docker build -t sqlpage-lambda-builder . -f lambda.Dockerfile --target builder docker run sqlpage-lambda-builder cat deploy.zip > sqlpage-aws-lambda.zip ``` 然后只需将你自己的 SQL 文件添加到 `sqlpage-aws-lambda.zip`, 并[将其上传到 AWS Lambda](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-package.html#gettingstarted-package-zip),, 运行时选择 *Custom runtime on Amazon Linux 2*。 ### 将 SQL 文件直接存放在数据库中 在无服务器模式下运行时,你可以将 SQL 文件直接包含在要部署的镜像中。 但如果你想在不创建新镜像的情况下动态更新 sql 文件, 可以将文件直接存储在数据库中,存放在具有以下结构的表中: ```sql CREATE TABLE sqlpage_files( path VARCHAR(255) NOT NULL PRIMARY KEY, contents BLOB, last_modified TIMESTAMP DEFAULT CURRENT_TIMESTAMP ); ``` 每次更新文件内容时,请务必更新 `last_modified`(或在 TRIGGER 中完成此操作)。 SQLPage 仅在文件被修改后才会从数据库重新解析该文件。 ## 使用的技术与库 - [actix web](https://actix.rs/) 以惊人的速度处理 HTTP 请求, - [tabler](https://preview.tabler.io) 为专业、整洁的组件提供样式, - [tabler icons](https://tabler-icons.io) 是一套庞大的图标集,你可以直接在 SQL 中选择, - [handlebars](https://handlebarsjs.com/guide/) 从每个组件的可读模板渲染 HTML 页面。 ## 常见问题 > **为什么要用 SQL 而不是真正的编程语言?SQL 甚至不是[图灵完备](https://en.wikipedia.org/wiki/Turing_completeness)!** 的!** - 你关注错了问题。如果你能声明式地表达应用逻辑,就应该这样做——无论使用 SQL 还是其他语言。声明式代码通常比命令式代码更简洁、可读、易于推理和调试。 - SQL 比传统语言更简单,非程序员往往也能读懂,同时又非常强大。 - 如果你的目标是复杂性,请注意 [SQL 实际上是图灵完备的](https://stackoverflow.com/questions/900055/is-sql-or-even-tsql-turing-complete/7580013#7580013). - 即使没有递归查询,由用户交互驱动的一系列 SQL 语句(如 SQLPage)仍然是图灵完备的,使你能够构建作为图灵机运行的 SQL 驱动网站。 > **能做不代表应该做……** — [Reddit 上某个刻薄的人](https://www.reddit.com/r/rust/comments/14qjskz/comment/jr506nx) 这不是“应不应该”的问题——而是“为什么不呢?” 你想守规矩就继续待在框里涂色吧,我们会在旁边用 SQL 网站玩得很开心。 > **这和 Microsoft Access 一样吗?** 目标相似——创建简单的以数据为中心的应用——但工具差异很大: - SQLPage 是 Web 服务器,不是桌面应用。 - SQLPage 连接现有的强大关系型数据库;Access 试图**成为**数据库。 - Access 昂贵且专有;SQLPage 是[开源](./LICENSE.txt)的。 - SQLPage 让你免于 [Visual Basic for Applications](https://en.wikipedia.org/wiki/Visual_Basic_for_Applications). 的折磨。 > **这个名字是在致敬 Microsoft FrontPage 吗?** FrontPage 是 90 年代末流行的可视化静态网站构建器。直到有人问我之前,我都没听说过它。 > **我喜欢 CSS。我想设计网站,而不是写 SQL。** 如果你想编写自己的 HTML 和 CSS, 可以[创建自定义组件](https://sql-page.com/custom_components.sql), 在 `sqlpage/templates` 中添加 [`.handlebars`](https://handlebarsjs.com/guide/) 文件,并在其中编写 HTML 和 CSS。([示例](./sqlpage/templates/alert.handlebars))。 你也可以使用 `html` 组件编写原始 HTML,或使用 `shell` 组件引入自定义脚本和样式。 但 SQLPage 认为,在你拥有可运行的原型之前,不必为按钮圆角操心。 我们开箱即提供美观的组件,让你专注于数据模型,并快速迭代。 ## 下载 SQLPage 可从多个来源下载: [![GitHub Downloads (all assets, all releases)](https://img.shields.io/github/downloads/sqlpage/SQLPage/total?label=direct%20download)](https://github.com/sqlpage/SQLPage/releases/latest) [![Docker Pulls](https://img.shields.io/docker/pulls/sqlpage/SQLPage?label=docker%3A%20lovasoa%2Fsqlpage)](https://hub.docker.com/r/sqlpage/SQLPage) [![homebrew downloads](https://img.shields.io/homebrew/installs/dq/sqlpage?label=homebrew%20downloads&labelColor=%232e2a24&color=%23f9d094)](https://formulae.brew.sh/formula/sqlpage#default) [![Scoop Version](https://img.shields.io/scoop/v/sqlpage?labelColor=%23696573&color=%23d7d4db)](https://scoop.sh/#/apps?q=sqlpage&id=305b3437817cd197058954a2f76ac1cf0e444116) [![Crates.io Total Downloads](https://img.shields.io/crates/d/sqlpage?label=crates.io%20download&labelColor=%23264323&color=%23f9f7ec)](https://crates.io/crates/sqlpage) [![](https://img.shields.io/badge/Nix-pkg-rgb(126,%20185,%20227))](https://search.nixos.org/packages?channel=unstable&show=sqlpage&from=0&size=50&sort=relevance&type=packages&query=sqlpage) ## 贡献 我们欢迎贡献!SQLPage 使用 Rust 构建, 前端部分使用 vanilla javascript。 请查看我们的[贡献指南](./CONTRIBUTING.md),了解开发环境配置、测试和拉取请求流程的详细说明。 # 代码签名政策 我们的 Windows 二进制文件经过数字签名,因此 Windows 应能将其识别为安全。 免费代码签名由 [SignPath.io](https://about.signpath.io/), 提供,证书由 [SignPath Foundation](https://signpath.org/). [Contributors](https://github.com/sqlpage/SQLPage/graphs/contributors), [Owners](https://github.com/orgs/sqlpage/people?query=role%3Aowner). 除非用户或安装、操作人员明确请求,否则本程序不会将任何信息传输到其他联网系统