---
name: apisql-sudb
description:
  通过 apiSQL 的 SUDB（Super Database API），用一个 HTTP 接口对数据库执行任意
  SQL（查询/增删改查/DDL/DML/聚合/多表 JOIN 等）。适用于用户想"用一个接口跑
  SQL"、想体验 apiSQL、想让 AI 直接读写数据库的场景。触发词：SUDB、apiSQL、Super
  Database API、一个接口跑 SQL、数据库转 API。支持 MySQL、Oracle、SQL
  Server、PostgreSQL、SQLite、Apache Doris、SelectDB、StarRocks、TiDB、华为
  DWS(GaussDB)、达梦、Trino、PrestoSQL 等数据库，企业版还支持自定义 JDBC
  驱动接入（如 OceanBase、人大金仓等）。
---

# apiSQL SUDB（Super Database API）技能

SUDB 把**整个数据库通过一个 HTTP 接口暴露**：把 SQL 语句作为文本放进 JSON 请求体，apiSQL 执行后返回结果（查询返回行，写操作返回影响行数）。无需为每条 SQL 预先定义 REST 路由 —— 一个接口承载任意 SQL，并支持命名参数安全传值。

## 支持的数据库

SUDB 底层可对接多种数据库，切换只需改请求体里的 `ds`（数据源名）字段：

MySQL、Oracle、SQL Server、PostgreSQL、SQLite、Apache
Doris、SelectDB、StarRocks、TiDB、华为 DWS(GaussDB)、达梦(DM)、Trino、PrestoSQL 等。

此外，**企业版支持自定义 JDBC 驱动**：只要目标数据库提供 JDBC 驱动，即可接入使用，例如 OceanBase、人大金仓(KingbaseES) 等国产及各类数据库。

## 公开演示接口

- 地址：`https://open.apisql.cn/api/demo-area/$sudb`
- 方法：`POST`
- 请求头：`Content-Type: application/json;charset=UTF-8`
- 鉴权头：`Authorization: Bearer <APIKEY>`

演示用 API Key 是公开的（这是有意开放的演示项目）：
`sk-93e23231a9c8257f2c21854531f42b0a`

建议存入环境变量，curl 时用 `$APISQL_DEMO_KEY`
引用，不要在交给用户的脚本里硬编码：

```bash
export APISQL_DEMO_KEY="sk-93e23231a9c8257f2c21854531f42b0a"
```

演示环境目前提供 **MySQL**（`ds=mysql`）与
**PostgreSQL**（`ds=postgresql`）两个数据源。

## ⚠️ 安全须知（务必先读）

这是一个"AI 可直接操作数据库"的能力，请遵守：

1. **默认只做只读查询（SELECT / SHOW / DESC / 聚合）**，除非用户明确要求写入。
2. 演示库对**大部分表设为只读**：MySQL 通过账号权限控制、PostgreSQL 通过只读事务控制。只有 MySQL 的
   `user` 表可增删改。越权操作会在数据库层被拒绝（返回 `command denied` /
   `read-only transaction` / `permission denied`）——这是正常的，不要绕过。
3. 用户如果要在**自己的数据库**上用，强烈建议从**测试库**或**只读账号**开始，按最小必要原则授权到表级，不要用管理员账号。
4. 用户传入的值一律走 `params` 的 `:命名参数`，不要拼进 SQL 字符串（防注入）。
5. 演示库若做写入测试，请用较大的 id（如 8001）并在结束后 DELETE 清理，保持数据整洁。

## 请求体结构

```json
{
  "meta": {
    "ds": "mysql", // 数据源：mysql / postgresql / oracle / ...
    "sc": "SELECT * FROM user", // 要执行的 SQL
    "pageNum": 1, // 可选：SELECT 分页页码
    "pageSize": 10 // 可选：每页条数
  },
  "params": {
    // 可选：为 sc 中的 :命名参数 传值
    "myId": 1001
  }
}
```

## 响应结构

查询（SELECT / SHOW / DESC）：

```json
{
  "meta": {
    "pageMode": true,
    "totalCount": 20,
    "offset": 0,
    "limit": 5,
    "thisCount": 5
  },
  "rows": [{ "id": 1, "name": "张三", "age": 30 }]
}
```

写操作（INSERT / UPDATE / DELETE）：

```json
{
  "info": { "affectedRows": 1, "insertId": 8001, "changedRows": 0 },
  "meta": { "affectedRows": 1 },
  "rows": []
}
```

错误（SQL 错误或权限拒绝，从数据库层原样透传）：

```json
{
  "code": "API_GATEWAY_SERVER_ERROR",
  "message": "DELETE command denied to user 'demo_user1'@'...' for table 'area'"
}
```

## 演示库已知事实（实测）

- MySQL 8.0.34，库名 `demodb1`，14 张表（含 `user` 用户表、`area`
  全国行政区划 4.4 万行、 `dw_*` 数仓维度/事实表、`ecom_*` 电商、`ods_*`
  分层等）。仅 `user` 表可写。
- PostgreSQL 13.1，库名 `demodb1`，装有 PostGIS 3.0.2 / pgRouting 3.1.0 /
  pg_cron / hstore，整库为只读事务（可查询、可用 PostGIS 空间函数，不可写）。
- `SHOW TABLES`、`DESC`、`information_schema`、多表 JOIN、聚合、PostGIS 函数（如
  `ST_Distance`、`ST_MakePoint`）均可执行。

## 可直接运行的示例

查询（分页）：

```bash
curl -sS -X POST "https://open.apisql.cn/api/demo-area/\$sudb" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -H "Authorization: Bearer $APISQL_DEMO_KEY" \
  --data-binary '{"meta":{"ds":"mysql","sc":"SELECT * FROM user","pageNum":1,"pageSize":10}}'
```

命名参数条件查询：

```bash
curl -sS -X POST "https://open.apisql.cn/api/demo-area/\$sudb" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -H "Authorization: Bearer $APISQL_DEMO_KEY" \
  --data-binary '{"meta":{"ds":"mysql","sc":"SELECT id,name,age FROM user WHERE age > :minAge ORDER BY age DESC","pageNum":1,"pageSize":5},"params":{"minAge":30}}'
```

切换到 PostgreSQL + PostGIS 空间计算：

```bash
curl -sS -X POST "https://open.apisql.cn/api/demo-area/\$sudb" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -H "Authorization: Bearer $APISQL_DEMO_KEY" \
  --data-binary '{"meta":{"ds":"postgresql","sc":"SELECT name, ROUND((ST_Distance(ST_MakePoint(lon::float8,lat::float8)::geography, ST_MakePoint(113.665412,34.757975)::geography)/1000)::numeric,0) AS km FROM area WHERE level=1 AND lon IS NOT NULL ORDER BY km LIMIT 5"}}'
```

写入（仅演示库 user 表，测试后请清理）：

```bash
curl -sS -X POST "https://open.apisql.cn/api/demo-area/\$sudb" \
  -H "Content-Type: application/json;charset=UTF-8" \
  -H "Authorization: Bearer $APISQL_DEMO_KEY" \
  --data-binary '{"meta":{"ds":"mysql","sc":"INSERT INTO user(id,name,age) VALUE(:myId,:myName,:myAge)"},"params":{"myId":8001,"myName":"小明","myAge":18}}'
```

## 用在用户自己的 apiSQL 上

只需替换三处，请求结构和行为完全一致：

- **接口地址**：换成用户自己的网关地址与接口路径
- **数据源名 `ds`**：换成用户在 apiSQL 里配置的数据源名
- **API Key**：换成用户自己的 key

了解更多：[apiSQL 官网](https://www.apisql.cn) ·
[在线云平台](https://open.apisql.cn) · [官方文档](https://docs.apisql.cn)