跳转到主要内容

VillageSQL is a drop-in replacement for MySQL with extensions.

All examples on this page work on VillageSQL. Install Now →
本指南使用预览功能。请使用 --vsql_allow_preview_extensions=ON 启动服务器,否则 INSTALL EXTENSION 会被拒绝。
在几张表前面放一个只读的 JSON 端点,通常意味着编写一个小服务、部署它、给它一个数据库账户,并维持它的运行。VillageSQL 的 vsql_rest 扩展改为从服务器进程内部提供这些表,因此没有第二个进程,也没有新的部署。 默认值是为开发者机器设计的,而不是为网络设计的。在把端口开放给任何东西之前,请先阅读下面的”暴露端口之前”。

启用

先创建数据库及其表。监听器在启动时读取数据库布局,并缓存 vsql_rest.schema_ttl 秒(默认 60),所以之后创建的表在缓存过期之前都会回答 table not found。
然后指定数据库,指定您愿意提供的表,并启动监听器:

读取

一张表就是一个路径,查询字符串负责过滤。每个过滤器的形式是 column=operator.value:
只请求您需要的列:
用 or=(...) 组合条件:
用 limit 和 offset 翻页:
运算符有 eq、neq、lt、lte、gt、gte、like、cs_like、in 和 is。in 接受一个列表,例如 ?id=in.(1,3);is 接受 null,例如 ?price=is.null 或 ?price=is.not.null。没有 limit 的请求最多返回 vsql_rest.max_rows 行,初始值为 1000。

允许列表

对 API 而言,不在 allowed_tables 中的表就不存在:
响应是 404,而且无论该表是不存在还是只是被隐藏,响应内容都一样。
把 allowed_tables 留空并不意味着没有表。它意味着所有表。请在启用监听器之前,把它设置为您打算发布的表。

按表限制方法

table_methods 指定每张表接受哪些 HTTP 方法,形式为 table:METHOD,METHOD,表之间用 | 分隔:
默认情况下每张表接受所有方法,所以请在监听器启动之前设置它。表未授予的方法会被拒绝:
授予写入权限用的是同一个设置:
成功的插入回答 201,正文为空。重复键返回 409:

观察运行情况

五个状态计数器报告监听器的情况,包括它实际绑定的端口:
没有任何东西在监听时,http_port 读数为 0,这是判断监听器是否已启动的最快方法。把 vsql_rest.port 设为 0 会让操作系统选择一个端口,而这个计数器就是您读取它选了哪个端口的地方。

暴露端口之前

默认设置敞开着大门,而每一项单独看都合理。 require_auth 初始为 OFF,所以没有请求携带或需要令牌。空的 allowed_tables 发布整个模式。空的 table_methods 允许所有方法,包括 DELETE,而对处于这种状态的监听器发起 DELETE 会成功:
它回答 204,该行就没了。 合在一起,一个在没有其他配置的情况下打开的监听器,会让任何能访问该端口的人读取、插入、更新和删除模式中的每一张表。在笔记本电脑上这很方便。在其他任何地方,请在启用之前更改四项设置:
然后通过设置 ssl_cert 和 ssl_key 以 HTTPS 提供服务。没有绑定地址设置,监听器从启动那一刻起就绑定所有网络接口,所以请在防火墙上封锁该端口,只让反向代理访问它。

故障排除

另请参阅