关系数据库接口规范 0.1.0

本包让应用对已授权的关系数据库执行带类型参数的预备语句、读取多行结果，并把多条写入放进同一个原子批。库名由宿主许可核对。SQL 错误、参数或结果无法用 JSON 表达、超过下述上限时，调用失败并抛出豫言异常，应用可用「尝试运行」捕获；异常消息须包含数据库报告的原因文字，使应用能据此识别唯一约束冲突等可恢复情形。SQL 由应用提供，本包不声称语句只读；授予这项能力等于允许应用向该库提交任意 SQL，应用须自行保证 SQL 与授权范围符合其部署目的。窄能力的[关系查询](../关系查询/规范.汉语.md)仍适用于只需要首行和文字参数的应用。

参数

参数用 JSON 数组文字表示，元素只能是字符串、绝对值不超过 2^53−1 的整数、布尔值或 null，按顺序绑定到 SQL 占位符，不通过字符串拼接生成 SQL。空数组文字 [] 表示无参数。小数、数组、对象元素，以及不是数组的文字，使调用失败；需要小数的应用先用字符串或整数（例如按微单位）表达。参数数量或类型与语句不匹配由数据库报告失败。

函数

取关系库首行 执行语句并返回第一行的 JSON 对象文字，无行时返回字面量 null。取关系库全部行 返回全部结果行的 JSON 数组文字，每行是列名到值的对象，列顺序不作承诺；结果文字超过 8 MiB 时失败，应用应自己用 LIMIT 分页。数据库的 NULL 表示为 JSON null；宿主不得把整数悄悄改成小数，也不得丢失不超过 2^53−1 的整数精度。

执行关系库语句 执行一条语句并返回 {"changes":受影响行数,"lastRowId":最后插入行号}；语句没有插入时 lastRowId 的值由数据库决定，应用不应依赖它。查询语句也可执行，结果行被丢弃。

批量执行关系库语句 接受 JSON 数组文字，每项是 {"sql":文字,"params":参数数组}，params 缺省为空数组；最多 100 项，空数组失败。全部语句在同一个原子批内按顺序执行：任一条失败则整批不生效并使调用失败。返回长度相同的 JSON 数组，第 n 项是 {"changes":n,"lastRowId":n,"rows":[…]}，其中 rows 是该语句产生的结果行，没有结果行的语句给出空数组。批内语句不能互相读取彼此的绑定值，需要串联的写入应在 SQL 内表达（子查询、触发器或 RETURNING）。

边界

单个 SQL 文字不超过 256 KiB，参数数组文字不超过 1 MiB。事务只由批量函数提供；单条函数之间不构成事务，应用不得假定相邻调用之间数据库未被其他请求修改。库名不存在或未获许可属于部署配置错误，宿主直接中止当前请求，应用不应尝试恢复。当前云工适配把库名映射到 D1；其他平台可以接同等的关系数据库，但须保持整数精度和批的原子性。