wehub-resource-sync
377 lines
18 KiB
Markdown
377 lines
18 KiB
Markdown
<!-- WEHUB_ZH_README -->
|
||
> [!NOTE]
|
||
> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。
|
||
> [English](./README.en.md) · [原始项目](https://github.com/sqlpage/SQLPage) · [上游 README](https://github.com/sqlpage/SQLPage/blob/HEAD/README.md)
|
||
> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。
|
||
|
||
<h1 align="center">
|
||
SQLpage
|
||
</h1>
|
||
|
||
[](./docs/sqlpage.mp4)
|
||
|
||
[SQLPage](https://sql-page.com) 是一款**纯 SQL** Web 应用构建器。
|
||
它允许你通过将简单的数据库查询转换为交互式网站，
|
||
快速构建强大的以数据为中心的用户界面。
|
||
|
||
使用 SQLPage，你只需编写包含数据库查询的简单 `.sql` 文件，
|
||
用于查询、分组、更新、插入和删除数据，即可获得美观整洁的网页，
|
||
以文本、列表、网格、图表和表单等形式展示你的数据。
|
||
|
||
## 示例
|
||
|
||
<table>
|
||
<thead>
|
||
<tr><td>代码<td>结果</tr>
|
||
</thead>
|
||
<tbody>
|
||
<tr>
|
||
<td>
|
||
|
||
```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;
|
||
```
|
||
|
||
<td>
|
||
|
||
|
||
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
|
||
```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
|
||
```
|
||
|
||
<td>
|
||
|
||
|
||
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
|
||
```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;
|
||
```
|
||
|
||
<td>
|
||
|
||
|
||
|
||
</tr>
|
||
<tr>
|
||
<td>
|
||
|
||
```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
|
||
```
|
||
|
||
<td>
|
||
|
||
|
||
|
||
</tr>
|
||
</tbody>
|
||
</table>
|
||
|
||
## 支持的数据库
|
||
|
||
- [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) 中使用它
|
||
|
||
|
||
## 工作原理
|
||
|
||
|
||
|
||
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 可从多个来源下载：
|
||
|
||
[](https://github.com/sqlpage/SQLPage/releases/latest)
|
||
[](https://hub.docker.com/r/sqlpage/SQLPage)
|
||
[](https://formulae.brew.sh/formula/sqlpage#default)
|
||
[](https://scoop.sh/#/apps?q=sqlpage&id=305b3437817cd197058954a2f76ac1cf0e444116)
|
||
[](https://crates.io/crates/sqlpage)
|
||
[)](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).
|
||
|
||
除非用户或安装、操作人员明确请求，否则本程序不会将任何信息传输到其他联网系统
|