Docs
文档目录

SQL 访问面

功能概述

SQL 访问面(SQL Proxy)是 Agentbase 构建在 OceanBase 存储引擎之上的多租户受控 SQL 解析、重写与安全执行网关。在项目 企业智能客服与知识中台(Project ID:enterprise-ai-hub-210)中,除了使用标准 REST / SDK 的文档与表接口(listDocuments、createDocument)操作数据库 企业智能客服业务库(Database ID:enterprise_biz_db)外,研发人员、数据分析师与 AI 智能体还可以通过 HTTP SQL 接口(/v1/sql)、Console 内置受控 SQL 终端以及面向可信后端的 MySQL Wire 协议直连入口,直接使用熟悉的 SQL 语法对 customer_tickets 等业务表执行查询投影、多表关联(JOIN)、分组聚合(GROUP BY / HAVING)、窗口函数、参数化绑定(Parameterized Queries)及受控 DML / DDL 操作。

与直接裸连底层数据库不同,Agentbase SQL Proxy 在 SQL 真正到达 OceanBase 之前,会强制执行身份路径识别(User Session vs Server API Key)、SQL 语法树白名单校验(AST Validation)、租户与存储模式自动重写(自动注入 Shared V2 的 _tenant 隔离条件或将逻辑表查询透明编译为 JsonTable 的 _jt_* 查询)以及表级/行级安全权限(Row Security ACL)裁剪,在释放 SQL 强大表达能力的同时,严守多租户隔离与零信任数据安全边界。


核心概念与架构

判断任意一条 SQL 语句在 Agentbase 中能否执行以及能看到哪些数据,遵循严格的四维判定模型:执行入口(Entrypoint) × 认证路径(Auth Path) × SQL 形态(SQL Shape) × 存储模式(tableMode: Shared V2 / JsonTable)。下图展示了 SQL Proxy 的核心解析、重写与安全门禁架构:

SQL 访问面:流程示意,不是运行截图

流程示意,不是运行截图;按箭头阅读步骤或状态之间的关系。

查看流程图大图

四大执行入口与认证路径核心能力对比

执行入口认证路径与凭证要求允许执行的 SQL 能力范围明确拒绝(Fail-Closed)的 SQL 与操作
1. Web 浏览器 / 客户端用户路径User Session Path:使用用户登录 Session Cookie 或短期 X-Appwrite-JWT 调用 HTTP /v1/sql。• 单表基础 SELECT(含投影、别名、WHERE、ORDER BY、LIMIT)
• 两个不同逻辑表的单个 INNER JOIN ... ON(等值条件,两表分别校验读权限或行 ACL)
• 单层非相关正向 IN (SELECT ...) 子查询
• 简单单表 INSERT ... VALUES、UPDATE、DELETE(须满足对应表/行写权限)
• 白名单内非事务初始化命令(如 SET NAMES)
• 严禁从浏览器表面携带 X-Appwrite-Key
• 元数据查询(SHOW TABLES、information_schema.*)
• 任何 DDL(CREATE/ALTER/DROP/TRUNCATE TABLE)
• LEFT/RIGHT/FULL JOIN、多表或自连接、GROUP BY/HAVING/聚合函数、UNION、CTE、游标(Cursor)
• 事务控制命令(BEGIN/COMMIT/ROLLBACK)
2. 后端服务 HTTP /v1/sqlAPI Key Path:在可信后端通过 X-Appwrite-Key: <APPBASE_API_KEY> 调用 HTTP /v1/sql。• 元数据自省(SHOW TABLES、SHOW COLUMNS、SHOW INDEX、information_schema)
• 复杂 SELECT(INNER JOIN、LEFT JOIN、GROUP BY、HAVING、聚合函数、受控子查询、派生表、UNION、CTE、窗口函数 ROW_NUMBER/RANK/DENSE_RANK、EXPLAIN SELECT)
• 完整受控 DML(INSERT、UPDATE、DELETE)与受控 DDL(CREATE/ALTER/DROP/TRUNCATE TABLE、CREATE/DROP INDEX)
• 带稳定 Key ID 的标准 API Key 支持参数化 APPBASE SECURITY 权限管理子句
• MySQL Wire 协议游标(DECLARE/OPEN/FETCH CURSOR)
• DCL 与实例管理命令(GRANT、REVOKE、修改全局变量)
• 视图(View)、存储过程、触发器、外键、分区等未覆盖 DDL
• 显式事务状态命令(统一返回 transaction_not_supported)
3. MySQL Wire 协议直连MySQL Wire Path:使用标准 MySQL 客户端连接受控端口,用户名为 <PROJECT_ID>(如 enterprise-ai-hub-210),密码为 <APPBASE_API_KEY>。• 具备 后端服务 HTTP API Key Path 的全部查询、元数据、DML、受控 DDL 与 Prepared Statement 能力
• 独占支持 MySQL Wire 游标(Cursor):DECLARE c CURSOR FOR SELECT ...、OPEN c、FETCH、CLOSE c、CLOSE ALL
• 不支持浏览器用户态 Session / JWT 认证
• 不适用 HTTP JSON 请求体的 mode / params 包装语义
• 同样拒绝 DCL、管理命令与显式事务状态命令
4. Console SQL 终端Console 管理态:通过受当前登录身份保护的 HTTP /v1/sql 端点执行。• 当组织 owner 在 Console 管理态执行时,经服务端内省确认 owner 身份后继承 Server HTTP 管理查询与受控操作能力(但动态会话 Actor 不执行 APPBASE SECURITY 权限变更)• 安全披露边界:Console 前端绝不向浏览器下发 MySQL Wire 主机地址、CA 证书、连接串或创建直连 Key;非 owner 成员无法查看管理 API Key 的 secret 明文

角色、入口与关联关系

控制台入口与披露安全边界

与双存储模式(Shared V2 vs JsonTable)的关联关系

SQL Proxy 对上层调用方屏蔽了 Shared V2 与 JsonTable 的底层物理表结构差异:


功能详解与操作指南

1. SQL 能力矩阵细则(按认证路径与 SQL 类型)

在编写业务 SQL 前,请对照下表确认目标语法在对应路径下的支持状态:

SQL 能力域具体语法与特性Web 用户态路径(Session / JWT)服务端 API Key 路径(HTTP /v1/sql & MySQL Wire)关键约束与治理规则
基础查询SELECT col1, col2 AS alias FROM tbl WHERE ... ORDER BY ... LIMIT N✅ 支持✅ 支持User 路径自动注入表级 read 或行级安全(rowSecurity)过滤条件。
表关联(JOIN)INNER JOIN / LEFT JOIN⚠️ 仅支持两个不同逻辑表、唯一别名、单个 INNER JOIN(ON 为一个或多个 AND 连接的跨表公开列等值条件)✅ 支持受控 INNER JOIN 与 LEFT JOIN ... ON ...任何路径均不支持 RIGHT JOIN、FULL JOIN、NATURAL JOIN。User 路径下参与 INNER JOIN 的两张表会分别独立校验读权限。
子查询WHERE col IN (SELECT ...)⚠️ 仅支持单层、非相关、正向 IN (SELECT ...)(外表与内表须为不同逻辑表并分别鉴权)✅ 支持受控 IN / EXISTS 及简单派生表子查询User 路径不支持 NOT IN (SELECT ...)、EXISTS、相关子查询或多层嵌套子查询。
分组与聚合GROUP BY、HAVING、COUNT、SUM、AVG、MIN、MAX、COUNT(DISTINCT ...)❌ 拒绝✅ 支持复杂统计报表与聚合分析请统一通过后端 API Key 路径或服务端接口执行。
高级分析与窗口CTE(WITH ... AS)、UNION [ALL]、ROW_NUMBER() / RANK() / DENSE_RANK()❌ 拒绝✅ 支持受控子集JsonTable 模式下同样支持 DATE、受控 CAST、SUBSTRING、CONCAT 与基础窗口函数,自动按 project_seq + catalog_id 隔离。
数据变更(DML)INSERT INTO ... VALUES、UPDATE ... SET ... WHERE、DELETE FROM ... WHERE✅ 支持简单单表 DML(必须命中表/行对应的 create / update / delete 权限)✅ 支持单表与受控批量 DMLUser 路径下执行 INSERT 必须具备表级 create/write 权限;UPDATE/DELETE 若无表级权限则必须在开启 rowSecurity 时按行 ACL 过滤。
结构变更(DDL)CREATE TABLE、ALTER TABLE、CREATE/DROP INDEX、DROP/TRUNCATE TABLE❌ 拒绝✅ 支持受控 DDL 子集仅服务端 API Key 管理路径可执行受控 DDL,且同样受 Schema 版本互斥锁约束。
元数据自省SHOW TABLES、SHOW COLUMNS、SHOW INDEX、information_schema.tables❌ 拒绝✅ 支持返回结果仅展示当前项目与数据库下的逻辑表和逻辑列,不泄露跨租户元数据。
会话与事务命令SET NAMES utf8mb4 vs BEGIN / COMMIT / ROLLBACK / SET autocommit白名单内 SET NAMES 返回空 OK;事务状态命令统一拒绝白名单内 SET NAMES 返回空 OK;事务状态命令统一拒绝SQL Proxy 为无状态受控代理,所有显式事务命令(START TRANSACTION、BEGIN、COMMIT、ROLLBACK)均明确返回 transaction_not_supported。

2. 通过 HTTP /v1/sql 执行参数化查询与读写操作

在应用研发中,强烈建议使用参数化绑定(params 数组 + ? 参数标记)代替字符串拼接 SQL,从根源上杜绝 SQL 注入风险,同时享受执行计划复用。

示例 1:服务端 API Key 路径执行工单多维聚合分析(只读查询)

以下示例展示在可信后端使用 <APPBASE_API_KEY> 调用 /v1/sql,统计 enterprise_biz_db 库中 customer_tickets 表各优先级与状态下的工单数量及平均满意度评分:

curl -X POST "https://appbuild.oceanbase.com/v1/sql" \
  -H "Content-Type: application/json" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -d '{
    "databaseId": "enterprise_biz_db",
    "sql": "SELECT priority, status, COUNT(*) AS ticket_count, AVG(satisfactionScore) AS avg_score FROM customer_tickets WHERE creatorUserId = ? GROUP BY priority, status ORDER BY priority ASC",
    "params": ["user_zhangwei_001"]
  }'

示例 2:客户端用户态路径(X-Appwrite-JWT)执行受行级 ACL 保护的查询与双表关联

当终端用户张伟(user_zhangwei_001)在前端登录后,可使用短期 JWT(X-Appwrite-JWT)调用 /v1/sql 查询自己有权限访问的工单记录(严禁在前端传入 X-Appwrite-Key):

curl -X POST "https://appbuild.oceanbase.com/v1/sql" \
  -H "Content-Type: application/json" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-JWT: <USER_SHORT_LIVED_JWT>" \
  -d '{
    "databaseId": "enterprise_biz_db",
    "sql": "SELECT t.ticketNo, t.title, t.priority, t.status FROM customer_tickets AS t WHERE t.status = ? ORDER BY t.ticketNo DESC LIMIT 10",
    "params": ["processing"]
  }'

示例 3:使用 APPBASE SECURITY 语法在服务端管理路径下绑定行级权限

在持有标准 API Key(带稳定 Key ID)的服务端管理路径中,SQL Proxy 提供了独创的 APPBASE SECURITY 扩展语法,允许在 INSERT、UPDATE 或 CREATE/ALTER TABLE 时通过参数化绑定直接指定 Agentbase 角色权限数组:

curl -X POST "https://appbuild.oceanbase.com/v1/sql" \
  -H "Content-Type: application/json" \
  -H "X-Appwrite-Project: enterprise-ai-hub-210" \
  -H "X-Appwrite-Key: <APPBASE_API_KEY>" \
  -d '{
    "databaseId": "enterprise_biz_db",
    "sql": "INSERT INTO customer_tickets (ticketNo, title, priority, status, creatorUserId) VALUES (?, ?, ?, ?, ?) APPBASE SECURITY READ ? UPDATE ? DELETE ?",
    "params": [
      "TK-20261022-005",
      "SQL Proxy 参数化写入与行级 ACL 联调验证",
      "P1",
      "open",
      "user_zhangwei_001",
      ["user:user_zhangwei_001", "team:team_support_ops"],
      ["user:user_zhangwei_001", "team:team_support_ops/admin"],
      ["team:team_support_ops/admin"]
    ]
  }'

3. 连接恢复、行上限与超时治理规则

为防止慢查询或超大结果集拖垮多租户共享连接池,SQL Proxy 内置了严格的运行期保护机制:

  1. 只读与读写门禁(Read-Only vs Read-Write Gate):

    • 当项目处于只读维护模式(Project Read-Only)或正在执行存储模式转换停写窗口(tableModeConversionStatus)时,所有 DML(INSERT/UPDATE/DELETE)与 DDL 请求会被立即拦截,仅放行安全的只读 SELECT 查询。

  2. 结果集行数上限与游标物化限制(Row Limits):

    • 单次 HTTP /v1/sql 查询返回的最大行数受系统配额上限保护;在 MySQL Wire 路径下使用 DECLARE c CURSOR FOR SELECT ... 游标时,游标的物化结果集同样复用 HTTP 行数上限,防止无界全表拉取耗尽内存。建议所有业务查询显式携带合理的 LIMIT 子句。

  3. 超时熔断与空闲连接自动重连(Timeout & Connection Recovery):

    • 单条 SQL 执行时间受 API 数据库超时阈值(APP_DATABASE_TIMEOUT_MILLISECONDS_API)约束,超时查询会被自动中止。

    • 当底层 OceanBase 空闲连接因超时断开后,新的非事务请求会自动透明恢复连接;若操作在异常中断前已涉及写入状态,系统不会盲目自动重放写请求,以避免产生重复插入,调用方应先核对结果再按幂等键(如唯一 $id 或 uk_ticket_no)重试。


入口与身份

入口适用场景身份与权限边界
Console SQL 终端在项目中交互查询或执行受控 SQL当前登录用户必须是项目所有者(owner)。终端通过 HTTP 请求工作;页面只显示 HTTP 端点,不提供 MySQL Wire 直连配置。
用户身份 HTTP代表当前应用用户访问数据使用用户会话、JWT 或 Cookie;仍受表权限和行级权限控制。
服务端 HTTP / MySQL Wire由可信服务端程序访问使用项目 API Key;密钥只能保存在服务端,不能放入浏览器代码。MySQL Wire 的可用状态以实例配置为准。

在 Console 中执行 SQL

Console 入口路径示意(不是运行截图):项目 → Databases → 选择数据库 → SQL → HTTP SQL 终端。

  1. 打开目标项目,在 Databases 中选择数据库,再进入 SQL 页面。Console SQL 页面支持 Legacy 和 TablesDB 类型;不支持的数据库类型会显示提示。

  2. 在终端输入一条 SQL。按 Enter 执行;按 Shift+Enter 换行编辑。

  3. 查看结果:查询会显示返回行或空结果,写操作会显示受影响行数;请求错误会显示在对应语句下方。

  4. 页面展示的是 HTTP 端点。当前 Console 不开放 MySQL Wire 直连配置,SQL 终端仍可通过 HTTP 使用。

SQL Proxy 只实现受控的 SQL 子集,不保证兼容所有 MySQL 语法或扩展。若语句被拒绝,先检查是否为单条语句、当前入口是否支持该操作,以及当前身份是否具有所需权限。

事务与写入结果

SQL Proxy 不提供公开的事务状态。BEGIN、START TRANSACTION、COMMIT、ROLLBACK、SET TRANSACTION 和修改 autocommit 的语句都会被拒绝,并返回 transaction_not_supported。因此,不能把多次提交当作一个原子事务,也不能用 ROLLBACK 撤销此前已执行的 SQL。

如果写操作遇到超时或连接中断,且没有明确结果,先查询受影响的数据,再按业务幂等策略决定是否重试;不要假设服务会自动重放请求。

常见问题与排障

Q1:为什么在客户端或 ORM 工具中执行 SQL 时报错 transaction_not_supported?

原因分析: 许多通用数据库驱动或 ORM 框架在执行 SQL 前默认会自动发送 START TRANSACTION、BEGIN、COMMIT、ROLLBACK、SET SESSION TRANSACTION ISOLATION LEVEL ... 或 SET autocommit=0。由于 Agentbase SQL Proxy 是面向多租户无状态 HTTP 与受控代理设计的安全网关,不向外部客户端承诺跨请求的连接独占与长事务状态保持,因此对所有事务状态控制语句统一明确返回 transaction_not_supported(而对于 SET NAMES utf8mb4 等无副作用的非事务初始化命令则兼容返回空 OK)。

解决方案:

Q2:为什么同一条带有 GROUP BY 或 LEFT JOIN 的查询语句,在后端调用 /v1/sql 能成功返回,而在前端浏览器用登录用户身份调用却被拒绝?

原因分析: 这是 SQL Proxy 的认证路径分级安全设计:

解决方案: 如果前端页面需要展示复杂的统计报表或多表 LEFT JOIN 汇总结果,请由企业后端服务(或 Agentbase 云函数 Functions)使用 Server API Key 调用 /v1/sql 完成聚合计算后,再将脱敏结果返回给前端。

Q3:为什么在 Console 页面找不到 MySQL 直连的 Host、端口和连接密码?

回答: 根据 Agentbase 的生产安全收敛规范,Console 浏览器前端不向客户端披露底层 MySQL Wire 的主机地址、CA 证书及直连连接串,且非组织 owner 的普通成员无法查看管理 API Key 的 secret 明文。在 Console 界面内调试 SQL 请直接使用页面内置的 HTTP 受控 SQL 终端;若受控后端微服务需要通过 MySQL Wire 协议直连,请联系组织 owner 获取项目 API Key,并从实例管理员批准的服务端配置清单中获取接入地址。


相关文档