Docs
文档目录

SQL Proxy(受控 SQL 访问)

这是什么 / 何时用

SQL Proxy 是受控 SQL 网关:请求经 parse → 能力/权限校验 → 逻辑标识改写 → 租户条件注入 → 执行。它不是透明 MySQL 代理,不能绕过 TablesDB 的权限模型。适合:用 SQL 语法做查询与受控 DML/DDL、BI 工具/命令行接入、把既有 MySQL 客户端指到项目表。

前置(访问形态与认证)

形态入口认证能力
User HTTPPOST {endpoint}/sql(endpoint 含 /v1)用户 Session / JWT / cookie有限单表查询、受控双表 INNER JOIN、单层正向 IN、简单单表 DML
Server HTTP同 path项目 API KeyMetadata、查询、受控 DML/DDL(仍受 scope + 项目隔离)
MySQL wireMySQL 协议端点(用户名=Project ID,密码=项目 API Key)项目 API KeyAPI Key 能力 + prepared statement + wire cursor;强制 TLS
Console SQLConsole 当前项目 SQL 终端Console 身份交互查询、结构查看、受控管理

2.6.0 起 Console SQL 页面不再展示 MySQL wire host、CA、连接串或自动创建的直连密码;项目成员使用页面内 SQL 终端。wire 的 host/CA/Key 须经实例管理员批准的服务端流程获取,不要从前端或构建变量推断。

使用骨架

  1. 选访问形态并装载对应身份:浏览器用 User HTTP(用户 Session/JWT);服务端用 Server HTTP 或 MySQL wire(项目 API Key);交互排查用 Console SQL 终端。

  2. SDK 路径(仅 Console SDK):Client 指向应用项目后调 sql.query / sql.execute,按需用 params 绑定 ? 参数标记。

  3. HTTP 路径:POST {endpoint}/sql,body 传 database / sql / params / mode,带 X-Appwrite-Project(+ Server 形态的 X-Appwrite-Key)。

  4. MySQL wire:从实例管理员批准的流程获取 host/CA/Key,强制 TLS 连接后按 prepared statement 执行;cursor 仅在同一条连接内使用。

  5. 校验响应的 truncated / affectedRows;权限管理类 DDL 用 APPBASE SECURITY (...) 且值全部 ? 绑定。

SDK 类别差异(2.6.0 实际 surface)

关键参数与返回

错误与边界

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 子集。

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

受控写入(execute)

mode=execute 返回受影响行数(affectedRows),同时校验 truncated——HTTP 形态无 wire cursor,truncated=true 的结果不可当完整集用。User path 仅开放简单单表 DML;DDL / 权限管理 SQL 仅 Server 形态(项目 API Key)。

const write = await sql.execute({
    databaseId: 'main',
    query: 'UPDATE orders SET status = ? WHERE id = ?',
    params: ['paid', 'order-1']
});
console.log(write.affectedRows, write.truncated);

权限管理 DDL(APPBASE SECURITY)

仅带稳定 key id 的标准项目 API Key 的 Server 形态入口开放(User path 不开放):权限字段值必须全部 ? 绑定(role 数组 / 原生 JSON boolean),禁 literal / 表达式 / 重复字段 / 多语句;PATCH 未出现的动作保持原值,显式 [] 清空该动作。

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,禁止重试原 SQL

MySQL 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)仅在同一条已认证连接内使用

示例指引