MySQL 的 vsql_rest 扩展

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


维护者	VillageSQL
源代码和完整文档	villagesql/vsql-rest
许可证	GPL-2.0
能力	预览

此扩展使用了一个预览能力，因此 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/ 目录中。用一条语句将它安装到服务器中：

INSTALL EXTENSION vsql_rest;

确认它已存在：

SELECT EXTENSION_NAME
FROM INFORMATION_SCHEMA.EXTENSIONS
WHERE EXTENSION_NAME = 'vsql_rest';

+----------------+
| EXTENSION_NAME |
+----------------+
| 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 秒：

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');

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

SET GLOBAL vsql_rest.schema = 'extdocs';
SET GLOBAL vsql_rest.allowed_tables = 'people';
SET GLOBAL vsql_rest.vsql_rest_enabled = ON;

通过 HTTP 读取该表：

curl http://127.0.0.1:3000/people

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

用查询参数过滤它：

curl "http://127.0.0.1:3000/people?id=eq.2"

[{"id":2,"name":"John Smyth"}]

关闭该设置会关闭端口：

SET GLOBAL vsql_rest.vsql_rest_enabled = OFF;

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

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

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

另请参阅

把表作为 REST API 提供 — 过滤器、按表设置的方法，以及首先要更改的默认值
管理扩展 — 扩展设置如何读取和写入
预览能力 — 预览标志开启了什么，以及它承诺了什么
可用扩展 — 完整目录
villagesql/vsql-rest — 源代码、完整的路由语法和已知限制

安装和运行扩展

扩展目录

构建扩展

安装

新增内容

示例

另请参阅

​安装

​新增内容

​示例

​另请参阅

安装

新增内容

示例

另请参阅