> ## Documentation Index
> Fetch the complete documentation index at: https://villagesql.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# MySQL 的 vsql_rest 扩展

> vsql_rest 扩展从服务器进程内部把 MySQL 表作为 HTTP 端点提供，支持 URL 过滤、存储函数调用、JWT 认证和行数上限。

`vsql_rest` 从数据库进程内部通过 HTTP 提供您的表。客户端用 URL 而不是
连接来读取行，用查询参数过滤行，并在 `/rpc/` 下调用存储函数。
不需要编写应用程序，也不需要运行第二个进程。

| | |
| - | - |
| **维护者** | VillageSQL |
| **源代码和完整文档** | [villagesql/vsql-rest](https://github.com/villagesql/vsql-rest) |
| **许可证** | GPL-2.0 |
| **能力** | 预览 |

> [!WARNING]
>
> 此扩展使用了一个预览能力，因此 `vsql_allow_preview_extensions` 必须为
> `ON`。请以 `--vsql_allow_preview_extensions=ON` 启动服务器，或运行
> `SET PERSIST vsql_allow_preview_extensions = ON`。否则 `INSTALL EXTENSION`
> 会被拒绝。

## 安装

如果您使用安装脚本、Docker 镜像或发行版压缩包安装了 VillageSQL，
`vsql_rest.veb` 已经位于服务器的 `lib/veb/` 目录中。
用一条语句将它安装到服务器中：

```sql theme={null}
INSTALL EXTENSION vsql_rest;
```

确认它已存在：

```sql theme={null}
SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_rest';
```

```
+----------------+
| EXTENSION_NAME |
+----------------+
| vsql_rest      |
+----------------+
```

要自行构建，请按照[存储库](https://github.com/villagesql/vsql-rest)中的
构建说明进行操作。

## 新增内容

它不添加 SQL 函数。您用 `SET GLOBAL` 配置它，它响应的每个请求都通过
HTTP 到达。

| 设置 | 默认值 | 控制内容 |
| - | - | - |
| `vsql_rest.vsql_rest_enabled` | `OFF` | 监听器是否运行 |
| `vsql_rest.schema` | 空 | 它提供的数据库；在设置之前，每个表请求和 RPC 请求都得到 `503`（代码 `VSQL0007`） |
| `vsql_rest.allowed_tables` | 空 | 哪些表可以访问；为空表示全部 |
| `vsql_rest.table_methods` | 空 | 每个表接受哪些 HTTP 方法，写作 `table:GET,POST\|table2:GET`；为空表示每个表都接受 `GET`、`POST`、`PATCH` 和 `DELETE` |
| `vsql_rest.allowed_routines` | 空 | 哪些函数可以在 `/rpc/` 下调用；为空表示全部 |
| `vsql_rest.port` | `3000` | HTTP 端口 |
| `vsql_rest.ssl_port` | `3443` | HTTPS 端口 |
| `vsql_rest.ssl_cert`、`vsql_rest.ssl_key` | 空 | HTTPS 的证书和密钥 |
| `vsql_rest.require_auth` | `OFF` | 请求是否必须携带 JWT |
| `vsql_rest.jwt_secret`、`vsql_rest.jwt_public_key` | 空 | 如何验证该 JWT |
| `vsql_rest.max_rows` | `1000` | 请求不带 `?limit` 时返回多少行 |
| `vsql_rest.schema_ttl` | `60` | 缓存的表布局重复使用多长时间，单位为秒；更改 `vsql_rest.schema`，或把 `vsql_rest_enabled` 关闭再打开，会在下一个请求时重建它 |

## 示例

请先创建表，因为监听器在启动时缓存数据库布局，并保留 `schema_ttl` 秒：

```sql theme={null}
CREATE DATABASE extdocs;
USE extdocs;

CREATE TABLE people (id INT PRIMARY KEY, name VARCHAR(32));

INSERT INTO people VALUES
    (1, 'Jonathan Smith'),
    (2, 'John Smyth'),
    (3, 'Joan Smithe'),
    (4, 'Peter Brown');
```

然后指定数据库和表，并打开监听器：

```sql theme={null}
SET GLOBAL vsql_rest.schema = 'extdocs';
SET GLOBAL vsql_rest.allowed_tables = 'people';
SET GLOBAL vsql_rest.vsql_rest_enabled = ON;
```

通过 HTTP 读取该表：

```bash theme={null}
curl http://127.0.0.1:3000/people
```

```json theme={null}
[{"id":1,"name":"Jonathan Smith"},{"id":2,"name":"John Smyth"},{"id":3,"name":"Joan Smithe"},{"id":4,"name":"Peter Brown"}]
```

用查询参数过滤它：

```bash theme={null}
curl "http://127.0.0.1:3000/people?id=eq.2"
```

```json theme={null}
[{"id":2,"name":"John Smyth"}]
```

关闭该设置会关闭端口：

```sql theme={null}
SET GLOBAL vsql_rest.vsql_rest_enabled = OFF;
```

> [!WARNING]
>
> 默认设置下认证关闭、每个表都被提供、每个支持的 HTTP 方法（`GET`、
> `POST`、`PATCH`、`DELETE`）都被允许，并且监听器从启动那一刻起绑定
> 每个网络接口。任何能访问该主机的人都可以读写该架构中的每个表。
> 在打开监听器之前，请设置 `allowed_tables`、`table_methods` 和
> `require_auth`，配置 JWT 密钥或公钥，并把端口放在防火墙之后。
> 没有绑定地址设置。

> [!NOTE]
>
> 用 `SET PERSIST` 写入的设置在重启后仍然保留，但 `UNINSTALL EXTENSION`
> 会删除它。卸载并重新安装后，每个设置都会恢复默认值，重启也不会
> 恢复旧值。

> [!NOTE]
>
> 每个字符串设置都通过服务器读回，服务器最多返回 1022 字节。更长的
> `schema`、`allowed_tables`、`allowed_routines`、`table_methods`、
> `jwt_secret` 或 `jwt_public_key` 会使每个请求都失败并返回 `500`；
> 更长的 `ssl_cert` 或 `ssl_key` 会使监听器无法启动。

## 另请参阅

* [把表作为 REST API 提供](https://villagesql.com/docs/en/guides/rest-api-from-tables.md) — 过滤器、按表设置的方法，以及首先要更改的默认值
* [管理扩展](https://villagesql.com/docs/zh/extensions/managing.md) — 扩展设置如何读取和写入
* [预览能力](https://villagesql.com/docs/zh/extensions/build/preview-capabilities.md) — 预览标志开启了什么，以及它承诺了什么
* [可用扩展](https://villagesql.com/docs/zh/extensions/catalog) — 完整目录
* [villagesql/vsql-rest](https://github.com/villagesql/vsql-rest) — 源代码、完整的路由语法和已知限制


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.