SQL Proxy(受控 SQL 访问)
这是什么 / 何时用
SQL Proxy 是受控 SQL 网关:请求经 parse → 能力/权限校验 → 逻辑标识改写 → 租户条件注入 → 执行。它不是透明 MySQL 代理,不能绕过 TablesDB 的权限模型。适合:用 SQL 语法做查询与受控 DML/DDL、BI 工具/命令行接入、把既有 MySQL 客户端指到项目表。
前置(访问形态与认证)
| 形态 | 入口 | 认证 | 能力 |
|---|---|---|---|
| User HTTP | POST {endpoint}/sql(endpoint 含 /v1) | 用户 Session / JWT / cookie | 有限单表查询、受控双表 INNER JOIN、单层正向 IN、简单单表 DML |
| Server HTTP | 同 path | 项目 API Key | Metadata、查询、受控 DML/DDL(仍受 scope + 项目隔离) |
| MySQL wire | MySQL 协议端点(用户名=Project ID,密码=项目 API Key) | 项目 API Key | API Key 能力 + prepared statement + wire cursor;强制 TLS |
| Console SQL | Console 当前项目 SQL 终端 | Console 身份 | 交互查询、结构查看、受控管理 |
2.6.0 起 Console SQL 页面不再展示 MySQL wire host、CA、连接串或自动创建的直连密码;项目成员使用页面内 SQL 终端。wire 的 host/CA/Key 须经实例管理员批准的服务端流程获取,不要从前端或构建变量推断。
使用骨架
- 选访问形态并装载对应身份:浏览器用 User HTTP(用户 Session/JWT);服务端用 Server HTTP 或 MySQL wire(项目 API Key);交互排查用 Console SQL 终端。
- SDK 路径(仅 Console SDK):Client 指向应用项目后调
sql.query/sql.execute,按需用params绑定?参数标记。 - HTTP 路径:
POST {endpoint}/sql,body 传database/sql/params/mode,带X-Appwrite-Project(+ Server 形态的X-Appwrite-Key)。 - MySQL wire:从实例管理员批准的流程获取 host/CA/Key,强制 TLS 连接后按 prepared statement 执行;cursor 仅在同一条连接内使用。
- 校验响应的
truncated/affectedRows;权限管理类 DDL 用APPBASE SECURITY (...)且值全部?绑定。
SDK 类别差异(2.6.0 实际 surface)
- **仅 Console SDK 导出
Sql服务**(客户端须指向应用项目): sql.query({ databaseId, query, params? })—— 固定mode=query,返回行集;sql.execute({ databaseId, query, params? })—— 固定mode=execute,返回受影响行数;?参数标记按从左到右顺序绑定params数组;返回SqlResponse(含columns/rows/rowCount/affectedRows/truncated)。
- **Node SDK、Web SDK 均无
Sql服务**;Java Console SDK 也没有。Web 用户场景可用底层 HTTP(POST {endpoint}/sql携带用户 Session,JWT 场景先setJWT)。 - HTTP body:
database(必填)、sql(必填,单条,禁多语句)、params(可选,?数组:JSON 标量 / role 数组 / boolean)、mode(query|execute,默认 query,须匹配语句类型)。请求头X-Appwrite-Project/X-Appwrite-Key。
关键参数与返回
- 稳定响应字段:
columns[{name, type_name}]、rows、rowCount、affectedRows(execute)、truncated。 - 行数/响应大小限制为实例相关:触发时
truncated=true,结果不可当完整集用;HTTP 形态无 wire cursor,完整批处理按业务键分页或改走 MySQL wire。 - 权限管理 SQL(仅带稳定 key id 的标准项目 API Key):
CREATE TABLE ... APPBASE SECURITY (READ=?, CREATE=?, UPDATE=?, DELETE=?, ROW_SECURITY=?, ENABLED=?)值必须 ? 绑定(role 数组 / 原生 JSON boolean);禁 literal / 表达式 / 重复字段 / 多语句。Row 动作只有 READ / UPDATE / DELETE(无行级 CREATE ACL);PATCH 未出现的动作保持原值,显式 [] 清空。响应可能附 commitStatus / operationReference / retrySql;commitStatus=committed_degraded 表示已提交但后置效果未知——记录 operationReference,禁止重试原 SQL。
错误与边界
- 事务类语句(BEGIN / COMMIT / ROLLBACK / SET TRANSACTION / autocommit)一律
transaction_not_supported——不要当空结果成功处理。 - 不支持:存储过程、触发器、View、外键、分区、用户管理、GRANT/REVOKE、任意 MySQL 扩展。
unsupported_capability:入口身份 / SQL 形态 / table mode / 安全矩阵未开放(数据库能执行 ≠ Proxy 支持)。authorization_denied:先核对入口身份、项目、table/row permission 与 Key scope;不要用更高权限 Key 掩盖 User path 的问题。- User RLS 行级语义:SELECT 需表读权限,或
rowSecurity=true时仅返回当前角色可读的行;INSERT 必须命中表 create/write;UPDATE/DELETE 需表动作或行安全限定。聚合、GROUP BY、CTE、UNION、大多数 JOIN/子查询、wire cursor 不属于 User path;权限元数据未知时 fail closed——同一条 SQL 不同用户结果可以不同。 - API Key scope 对照:Metadata=
tables.read;SELECT=表读 +rows.read;普通 DML=表读 +rows.write;CREATE TABLE=tables.write。为 SQL 建独立最小 scope Key。 - 启用状态/实际 endpoint/TLS/能力以实例
/ready为准(/health仅进程存活)。
SDK 类别差异
- Console SDK(console-sdk/nodejs.md):唯一的
Sql服务载体。 - Server SDK / 客户端 SDK(server-sdk/nodejs.md / client-sdk/web.md):无
Sql服务;按需走 HTTP 形态。 - Java Console SDK 无
Sql:走 HTTP API 或 JS Console SDK。
各语言调用示例
以下按使用骨架逐项给出各语言调用示例;每个卡片可切换语言(全页同步)。
查询(query)
四种入口先选形态并装载身份:浏览器 User HTTP(用户 Session,JWT 场景先 setJWT);服务端走 Server HTTP 或 MySQL wire(项目 API Key);交互排查用 Console SQL 终端。SDK 面仅 Console SDK(Node)导出 Sql 服务(Java Console SDK 无 Sql;Python / Go 无逐方法事实源)——本卡页签取 Console / Web / REST 子集。
- Console(Node)
- Web(用户 Session)
- REST(curl)
import { Client, Sql } from 'agentbase-console-sdk';
const client = new Client()
.setEndpoint(process.env.APPBASE_ENDPOINT!) // 须包含 /v1,且指向应用项目
.setProject(process.env.APPBASE_PROJECT_ID!)
.setKey(process.env.APPBASE_API_KEY!);
const sql = new Sql(client);
const result = await sql.query({
databaseId: 'main',
query: 'SELECT id, status FROM orders WHERE status = ? ORDER BY id LIMIT 100',
params: ['pending'] // ? 按从左到右顺序绑定;不要把用户输入拼接进 SQL
});
console.log(result.rows, result.rowCount, result.truncated);import { Client } from 'agentbase-web-sdk'; // 前提:用户已登录;JWT 场景先 client.setJWT(...)
const endpoint = import.meta.env.VITE_APPBASE_ENDPOINT;
const client = new Client()
.setEndpoint(endpoint)
.setProject(import.meta.env.VITE_APPBASE_PROJECT_ID);
// Web SDK 无 Sql 服务:底层 client.call 携带当前用户 Session 走 User HTTP path
const result = await client.call(
'POST',
new URL(`${endpoint.replace(/\/+$/, '')}/sql`),
{ 'content-type': 'application/json' },
{ database: 'main', sql: 'SELECT id, status FROM orders WHERE id = ?', params: ['order-1'], mode: 'query' }
);
console.log(result.rows, result.rowCount, result.truncated); // 与 Console 面同款输出校验:truncated=true 不可当完整集用curl -sS -X POST "$APPBASE_ENDPOINT/sql" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"database":"main","sql":"SELECT id, status FROM orders WHERE status = ? LIMIT 100","params":["pending"],"mode":"query"}'
# 稳定响应字段:columns / rows / rowCount / affectedRows / truncated;truncated=true 不可当完整集用受控写入(execute)
mode=execute 返回受影响行数(affectedRows),同时校验 truncated——HTTP 形态无 wire cursor,truncated=true 的结果不可当完整集用。User path 仅开放简单单表 DML;DDL / 权限管理 SQL 仅 Server 形态(项目 API Key)。
- Console(Node)
- Web(用户 Session)
- REST(curl)
const write = await sql.execute({
databaseId: 'main',
query: 'UPDATE orders SET status = ? WHERE id = ?',
params: ['paid', 'order-1']
});
console.log(write.affectedRows, write.truncated);// Web SDK 无 Sql 服务:底层 client.call 携带当前用户 Session;User path 仅简单单表 DML
const result = await client.call(
'POST',
new URL(`${endpoint.replace(/\/+$/, '')}/sql`),
{ 'content-type': 'application/json' },
{ database: 'main', sql: 'UPDATE orders SET status = ? WHERE id = ?', params: ['paid', 'order-1'], mode: 'execute' }
);
console.log(result.affectedRows, result.truncated); // execute 校验受影响行数;事务类语句一律 transaction_not_supported# mode 必须与语句类型匹配
curl -sS -X POST "$APPBASE_ENDPOINT/sql" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"database":"main","sql":"UPDATE orders SET status = ? WHERE id = ?","params":["paid","order-1"],"mode":"execute"}'
# 校验 affectedRows 与 truncated;事务类语句(BEGIN / COMMIT 等)一律 transaction_not_supported权限管理 DDL(APPBASE SECURITY)
仅带稳定 key id 的标准项目 API Key 的 Server 形态入口开放(User path 不开放):权限字段值必须全部 ? 绑定(role 数组 / 原生 JSON boolean),禁 literal / 表达式 / 重复字段 / 多语句;PATCH 未出现的动作保持原值,显式 [] 清空该动作。
- REST(curl)
curl -sS -X POST "$APPBASE_ENDPOINT/sql" \
-H 'Content-Type: application/json' \
-H "X-Appwrite-Project: $APPBASE_PROJECT_ID" \
-H "X-Appwrite-Key: $APPBASE_API_KEY" \
-d '{"database":"main","sql":"CREATE TABLE orders (id VARCHAR(255) PRIMARY KEY, status VARCHAR(32)) APPBASE SECURITY (READ = ?, CREATE = ?, UPDATE = ?, DELETE = ?, ROW_SECURITY = ?, ENABLED = ?)","params":[["user:alice"],["users"],["team:ops"],[],true,true],"mode":"execute"}'
# 响应可能附 commitStatus / operationReference / retrySql;commitStatus=committed_degraded 表示已提交但后置效果未知——记录 operationReference,禁止重试原 SQLMySQL wire(prepared statement)
wire 的 host / CA / Key 须经实例管理员批准的服务端流程获取,不要从前端或构建变量推断;强制 TLS,用户名=Project ID,密码=项目 API Key。各语言用标准 MySQL 客户端/驱动按 prepared statement 接入即可(此卡为 CLI 形态,无各语言 SDK 页签)。
MYSQL_ENABLE_CLEARTEXT_PLUGIN=1 mysql \
--protocol=tcp \
--enable-cleartext-plugin \
--ssl \
-h "${APPBASE_SQL_PROXY_HOST}" \
-P "${APPBASE_SQL_PROXY_PORT}" \
-u "${APPBASE_PROJECT_ID}" \
-p"${APPBASE_API_KEY}" \
main
# prepared statement 参数数量按用户 SQL 计算;cursor(DECLARE / OPEN / FETCH / CLOSE)仅在同一条已认证连接内使用示例指引
- JavaScript(Console SDK
sql.query/sql.execute):examples/javascript.md
事实源
skills/ob-agentbase/references/sql-proxy.mdskills/ob-agentbase/references/release-2.6.0.md(Console SQL 页面不再展示 wire 凭据)- appbase v2.7.0(tag v2.7.0)
- agentbase-sdks v2.7.0 specs(
packages/sdks/console-web/src/services/sql.ts:query/execute,path/sql)