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 明文 |
角色、入口与关联关系
控制台入口与披露安全边界
- 导航路径:登录 Agentbase Console → 进入项目
企业智能客服与知识中台(enterprise-ai-hub-210)→ 点击左侧栏 Databases → 选择数据库 **企业智能客服业务库**(enterprise_biz_db)→ 点击内置 SQL 访问入口。 - HTTP API 统一入口:
POST https://appbuild.oceanbase.com/v1/sql - 前端披露收敛边界(重要安全契约):
- Console 的 SQL 页面仅通过受当前项目身份保护的 HTTP
/v1/sql接口执行查询,**不再从前端构建变量或/v1/console/variables向浏览器下发 MySQL Wire Host、TLS CA 或直连连接串**,页面明确提示直连信息不在浏览器公开。 - 当组织中的非
owner成员查看项目 API Keys 时,仅能看到 Key 的名称、Scopes 与过期时间等元数据,**无法查看或复制 API Key 的secret明文**,从而防止非授权人员拿取密钥通过 MySQL Wire 绕过前端审计。 - 如企业受控后端服务确需使用 MySQL Wire 协议直连,必须由组织
owner或实例管理员通过受控服务端配置流程获取连接端点与最小权限 API Key(<APPBASE_API_KEY>)。
- Console 的 SQL 页面仅通过受当前项目身份保护的 HTTP
与双存储模式(Shared V2 vs JsonTable)的关联关系
SQL Proxy 对上层调用方屏蔽了 Shared V2 与 JsonTable 的底层物理表结构差异:
- 无论项目处于
Shared V2还是JsonTable模式,编写 SQL 时都**直接书写逻辑表名(如customer_tickets)和逻辑列名(如ticketNo、title、priority、status)**。 - 严禁在 SQL 中直接访问内部物理表或隐藏系统列:任何尝试查询
_id、_tenant、_permissions内部列,或直接查询_jt_documents、_jt_permissions、_jt_index_values、_jt_unique_index_values、_jt_fulltext_index_values、_jt_table_catalog、_jt_table_sequences等内部存储对象的 SQL 语句,都会被 SQL Proxy 在语法解析阶段直接拦截拒绝(Fail-Closed)。
功能详解与操作指南
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 权限) | ✅ 支持单表与受控批量 DML | User 路径下执行 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 内置了严格的运行期保护机制:
- 只读与读写门禁(Read-Only vs Read-Write Gate):
- 当项目处于只读维护模式(Project Read-Only)或正在执行存储模式转换停写窗口(
tableModeConversionStatus)时,所有 DML(INSERT/UPDATE/DELETE)与 DDL 请求会被立即拦截,仅放行安全的只读SELECT查询。
- 当项目处于只读维护模式(Project Read-Only)或正在执行存储模式转换停写窗口(
- 结果集行数上限与游标物化限制(Row Limits):
- 单次 HTTP
/v1/sql查询返回的最大行数受系统配额上限保护;在 MySQL Wire 路径下使用DECLARE c CURSOR FOR SELECT ...游标时,游标的物化结果集同样复用 HTTP 行数上限,防止无界全表拉取耗尽内存。建议所有业务查询显式携带合理的LIMIT子句。
- 单次 HTTP
- 超时熔断与空闲连接自动重连(Timeout & Connection Recovery):
- 单条 SQL 执行时间受 API 数据库超时阈值(
APP_DATABASE_TIMEOUT_MILLISECONDS_API)约束,超时查询会被自动中止。 - 当底层 OceanBase 空闲连接因超时断开后,新的非事务请求会自动透明恢复连接;若操作在异常中断前已涉及写入状态,系统不会盲目自动重放写请求,以避免产生重复插入,调用方应先核对结果再按幂等键(如唯一
$id或uk_ticket_no)重试。
- 单条 SQL 执行时间受 API 数据库超时阈值(
入口与身份
| 入口 | 适用场景 | 身份与权限边界 |
|---|---|---|
| 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 终端。
- 打开目标项目,在 Databases 中选择数据库,再进入 SQL 页面。Console SQL 页面支持 Legacy 和 TablesDB 类型;不支持的数据库类型会显示提示。
- 在终端输入一条 SQL。按 Enter 执行;按 Shift+Enter 换行编辑。
- 查看结果:查询会显示返回行或空结果,写操作会显示受影响行数;请求错误会显示在对应语句下方。
- 页面展示的是 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)。
解决方案:
- 在连接 SQL Proxy 时,请将驱动或客户端配置为自动提交模式(Autocommit),并关闭驱动层的显式事务包装(
BEGIN/COMMIT)。 - 如需执行多条文档的原子批量写入(All-or-Nothing),请使用 表、列、行与索引 中介绍的 SDK 批量事务接口(
createDocuments/updateDocuments/upsertDocuments)。
Q2:为什么同一条带有 GROUP BY 或 LEFT JOIN 的查询语句,在后端调用 /v1/sql 能成功返回,而在前端浏览器用登录用户身份调用却被拒绝?
原因分析: 这是 SQL Proxy 的认证路径分级安全设计:
- 后端携带
X-Appwrite-Key走的是 API Key 管理路径,允许执行GROUP BY、HAVING、LEFT JOIN、CTE、窗口函数与元数据查询。 - 前端浏览器携带 Session 或
X-Appwrite-JWT走的是 User Session 用户路径。为防止恶意终端用户构造高复杂度多表笛卡尔积或全表聚合查询发起拒绝服务攻击(DoS)或侧信道探测,User 路径严格限制为白名单内的单表查询、双表等值INNER JOIN与单层正向IN子查询。
解决方案: 如果前端页面需要展示复杂的统计报表或多表 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,并从实例管理员批准的服务端配置清单中获取接入地址。
相关文档
- 数据库概览(Databases Overview):了解 OceanBase 双存储模式(
Shared V2与JsonTable)的底层架构差异。 - 表、列、行与索引(Tables):管理
customer_tickets等业务表的列定义、索引与行级安全权限。 - Schema 版本与回滚(Schema Versions):通过声明式版本快照管理数据库结构演进。
- 认证概览(Auth Overview):了解 User Session、短期 JWT 与服务端 API Key 的生成与权限边界。