AgentbaseDocs
文档目录

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 的核心解析、重写与安全门禁架构:

flowchart TB
    subgraph Entrypoints["四大执行入口与认证路径 (Entrypoints & Auth Paths)"]
        WebClient["1. Web / 移动端用户路径<br/>HTTP POST /v1/sql<br/>凭证: Session / Cookie / X-Appwrite-JWT<br/>(严禁携带 API Key)"]
        ServerHTTP["2. 服务端管理 HTTP 路径<br/>HTTP POST /v1/sql<br/>凭证: X-Appwrite-Key: <APPBASE_API_KEY>"]
        ConsoleTerm["3. Console 内置 SQL 终端<br/>HTTP /v1/sql (Owner 管理态或项目身份)<br/>前端不暴露 MySQL Wire 直连凭据"]
        MySQLWire["4. MySQL Wire 协议直连路径<br/>MySQL CLI / JDBC / 后端驱动<br/>用户名: <PROJECT_ID>, 密码: <APPBASE_API_KEY>"]
    end

    subgraph ProxyCore["SQL Proxy 安全解析与重写核心引擎"]
        AuthGate["身份与 Scope 门禁<br/>区分 User Session 路径 vs API Key 管理路径"]
        ASTParser["SQL AST 语法白名单与形态检查<br/>拦截 DCL (GRANT/REVOKE)、隐式系统列 (_tenant/_id)<br/>拦截事务状态命令 (BEGIN/COMMIT -> transaction_not_supported)"]
        ACLInjector["权限与租户隔离注入器<br/>• User 路径强制注入表级 Read/Write 与行级 ACL<br/>• 强制限定当前 project_seq 与 databaseId"]
        ModeRewriter["双存储模式 SQL 重写器 (TableMode Rewriter)<br/>• Shared V2: 重写物理表名并注入 _tenant 过滤<br/>• JsonTable: 编译为 Rust native JsonTable 执行计划,隐藏 _jt_* 内部表"]
    end

    subgraph OBBackend["OceanBase 分布式数据库集群"]
        OBExec["受控执行与结果集净化<br/>(行上限保护 / 超时熔断 / 剥离内部物理列)"]
    end

    WebClient & ServerHTTP & ConsoleTerm & MySQLWire --> AuthGate
    AuthGate --> ASTParser --> ACLInjector --> ModeRewriter --> OBExec

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

执行入口认证路径与凭证要求允许执行的 SQL 能力范围明确拒绝(Fail-Closed)的 SQL 与操作
1. Web 浏览器 / 客户端用户路径User Session Path:使用用户登录 Session Cookie 或短期 X-Appwrite-JWT 调用 HTTP /v1/sql。• 单表基础 SELECT(含投影、别名、WHERE、ORDER BY、LIMIT)<br/>• 两个不同逻辑表的单个 INNER JOIN ... ON(等值条件,两表分别校验读权限或行 ACL)<br/>• 单层非相关正向 IN (SELECT ...) 子查询<br/>• 简单单表 INSERT ... VALUES、UPDATE、DELETE(须满足对应表/行写权限)<br/>• 白名单内非事务初始化命令(如 SET NAMES)• **严禁从浏览器表面携带 X-Appwrite-Key**<br/>• 元数据查询(SHOW TABLES、information_schema.*)<br/>• 任何 DDL(CREATE/ALTER/DROP/TRUNCATE TABLE)<br/>• LEFT/RIGHT/FULL JOIN、多表或自连接、GROUP BY/HAVING/聚合函数、UNION、CTE、游标(Cursor)<br/>• 事务控制命令(BEGIN/COMMIT/ROLLBACK)
**2. 后端服务 HTTP /v1/sql**API Key Path:在可信后端通过 X-Appwrite-Key: <APPBASE_API_KEY> 调用 HTTP /v1/sql。• 元数据自省(SHOW TABLES、SHOW COLUMNS、SHOW INDEX、information_schema)<br/>• 复杂 SELECT(INNER JOIN、LEFT JOIN、GROUP BY、HAVING、聚合函数、受控子查询、派生表、UNION、CTE、窗口函数 ROW_NUMBER/RANK/DENSE_RANK、EXPLAIN SELECT)<br/>• 完整受控 DML(INSERT、UPDATE、DELETE)与受控 DDL(CREATE/ALTER/DROP/TRUNCATE TABLE、CREATE/DROP INDEX)<br/>• 带稳定 Key ID 的标准 API Key 支持参数化 APPBASE SECURITY 权限管理子句• MySQL Wire 协议游标(DECLARE/OPEN/FETCH CURSOR)<br/>• DCL 与实例管理命令(GRANT、REVOKE、修改全局变量)<br/>• 视图(View)、存储过程、触发器、外键、分区等未覆盖 DDL<br/>• 显式事务状态命令(统一返回 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 能力<br/>• 独占支持 MySQL Wire 游标(Cursor):DECLARE c CURSOR FOR SELECT ...、OPEN c、FETCH、CLOSE c、CLOSE ALL• 不支持浏览器用户态 Session / JWT 认证<br/>• 不适用 HTTP JSON 请求体的 mode / params 包装语义<br/>• 同样拒绝 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 内置了严格的运行期保护机制:


入口与身份

入口适用场景身份与权限边界
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 终端。

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,并从实例管理员批准的服务端配置清单中获取接入地址。


相关文档