agentsql

README

AgentSQL

生态收录：Glama

已收录于 MCP 官方 Registry，可直接在 MCP Registry 搜索 AgentSQL 接入。

AgentSQL（中文品牌名：智盾，控制台显示为「AgentSQL 智盾控制台」）是面向 AI Agent 的数据库安全网关与生产级 MCP Server：让模型发出的每条 PostgreSQL/MySQL 请求在到达数据库前，经过身份认证、SQL 解析、授权与规则评估、受控执行、结果脱敏和审计。

v0.6.0 加入治理控制台、审批单次执行和 Vastbase G100 的受限只读适配；v0.7.0 加入独立的 MCP 2026-07-28 入口与任务级临时只读授权；v0.8.0 加入异人审批；v0.9.0 为新申请加入 1–10 次结果预算、管理审计投递状态和策略离线预检。v1.0.0 收紧列策略的失败关闭，并加入可选的 Agent 与人员双身份 HTTP MCP 验证。v1.1.0 将双身份扩展到审批与 B5 会话，并加入委托令牌单独撤销。v1.2.0 增加可选的 MCP OAuth 受保护资源入口。v1.3.0 增加默认关闭的 MySQL 8.0/8.4 单表 InnoDB SELECT 列授权子集。v1.4.0 在 PostgreSQL metadata 部署中共享控制台密码和 LDAP 登录尝试预算，并验证双网关审计故障恢复。自 v0.5.0 起代码采用 Apache-2.0，历史 v0.4.0 发布物仍按其原许可使用。

v1.5.0 对达梦、金仓和 Vastbase 的指定实例深入验证真实 MCP 客户端、权限撤销、断库恢复及审计。v1.6.0 在相同指定实例和受控只读子集内补齐故障关闭。v1.7.0 为瀚高 9.0.10 企业版 PG 模式增加独立 highgo 类型及有界只读路径，并为金仓 V9R1C10 PG 模式补充证书校验与凭据轮换。v1.8.0 在指定 Vastbase G100 Build 9 PG 模式实例验证 verify-full、证书和账号轮换、MCP 双客户端、脱敏与审计；主备高可用和完整生产支持仍未验收，见发布说明。v1.9.0 增加 Dify / MCP Inspector 接入说明、复用 Agent 与数据源的目标 SQL 离线解释及真实调用审计定位；见发布说明。

**验证范围：**v1.0.0 的列策略、人员委托及真实客户端结果见验收记录；v1.1.0 的审批与 B5 双身份结果见验收记录；v1.2.0 的 OAuth 互通结果见验收记录；v1.3.0 的 MySQL 列授权边界见验收记录；v1.4.0 的共享登录预算与双节点恢复见验收记录；v1.5.0 的三款国产数据库指定子集深度验证见验收记录；v1.6.0 的故障关闭与恢复证据见验收记录；v1.7.0 的瀚高和金仓证据见正式发布验收；v1.8.0 的 Vastbase TLS 范围见本版验收；v1.9.0 接入向导改进见本版验收。厂商结论只覆盖指定实例、模式及合成数据。以下命令须以 GitHub Release、签名及镜像匿名拉取验收为准。

AI Agent → LLM / MCP Client → AgentSQL 网关 → PostgreSQL / MySQL
                                  │
                                  └─ 鉴权 · 授权 · 规则 · 审批 · 脱敏 · 审计

核心特性

• 双 MCP 承载：本机 stdio 与 Streamable HTTP /mcp，提供 8 个基础数据库工具；默认开启的 PostgreSQL B5 会话/计划事务另提供 8 个工具。
• 默认拒绝的安全链路：API Key 认证、Agent 能力档位、对象/列授权、SQL AST 规则与 fail-closed 错误处理。
• 受控读写：只读保护、危险 SQL 拦截、Explain 风险评估、超时、连接/QPS/结果行数限制和人工审批。
• 基础数据保护：列级脱敏提供四种算法——六类 mask 部分遮蔽、九类均可用的带专用密钥 HMAC hash 指纹、无需密钥且把非空值统一替换为 *** 的 block 整值阻断，以及仅用于 number / date、通过数值分桶或日期截断保留粗粒度分布且无需密钥的 range。数据源口令另由 32 字节 AGENTSQL_SECRET 加密保存。
• 可追溯运维：默认零配置 SQLite；可选 PostgreSQL 15+ 控制面（PostgreSQL 18 为基准，metadata 与 audit 可分库）；支持审计导出（面向机器的 JSONL，以及 Excel/WPS 可直接打开、带公式注入防护的中文 CSV）、审批决策闭环、Prometheus 指标与健康/就绪探针。
• 安全事件通知：按决策过滤并以 Webhook 或 Syslog 旁路外发；默认关闭、默认不含 SQL，通知失败不影响审计与 SQL 决策。
• 内嵌 Web 控制台：总览、审计、演示台、Agent、数据源、权限、规则、审批、脱敏规则、用户、角色、租户管理及首次接入向导。
• v0.9.0 受控查询加固：新任务 Key 默认一次结果预算（最多 10 次）、原子扣减；总览展示本租户分库管理审计投递积压；权限页提供只给出拒绝或未知的 SQL 离线预检。
• v1.0.0 安全边界：有列策略的 SELECT 不退回表级放行；可选的 HTTP MCP 人员令牌逐请求验证并与 Agent Key、租户、任务授权绑定。
• v1.1.0 双身份闭环：委托审批单只能由原用户和 Agent 单次执行；B5 会话与计划绑定人类用户、Agent 和租户；新签发的委托令牌可单独撤销。
• v1.2.0 MCP OAuth：可选的 /mcp/oauth 受保护资源入口使用外部 OIDC/OAuth 授权服务器签发的资源专用访问令牌，并逐次绑定独立 Agent Key、用户映射、租户与本地权限；支持范围见发布说明。
• v1.3.0 MySQL 列授权：显式开启后，MySQL 8.0/8.4 指定 InnoDB 基表的受限单表 SELECT 使用独立只读业务账号与 PROCESS-only 元数据账号、表 ID 和 metadata lock 证明列权限；不扩大为所有 MySQL SELECT。
• v1.4.0 多网关登录预算：PostgreSQL metadata 部署对密码和 LDAP 登录使用共享的 60 秒 10 次预算；数据库故障返回 503，预算耗尽返回 429，SQLite 单实例仍使用本地预算。

生态与兼容

AgentSQL 作为数据库中立的安全网关，当前原生支持 PostgreSQL 与 MySQL。v0.6.0 新增 Vastbase G100 的指定版本只读子集；国产数据库的指定实例与协议路径验证范围见下表。

数据库	适配状态	说明
海量数据 Vastbase G100	🔵 指定版本受控只读	G100 V3.0 Build 9、PG 模式、单实例合成表：独立 vastbase 类型、强制只读连接、单表有界 SELECT、表授权、手机号脱敏、MCP 审批单次执行及持久审计实测；v1.8.0 补充 verify-full、证书及密码轮换和 Inspector/Dify 双客户端验证。临时许可仅用于隔离验收，HA、其他 Build 和生产负载未测；见本版验收。
中电科金仓 KingbaseES	🟢 PG 协议基础闭环实测通过	仅 V9R1C10、PG 模式、单实例合成表：可写 license 卷启动、ksql CRUD/分页/标识符、pgx/v5 $1 绑定 + SCRAM、只读角色拒写 42501、受控 SELECT allow + 手机号脱敏 + 列血缘 + R006 注释拒绝 + allow/deny 审计实测通过；见真库验证记录
瀚高 HighGo	🔵 指定版本受控只读	独立 highgo 类型：9.0.10 企业版 PG 模式、单实例合成表的有界 SELECT、表授权、脱敏、MCP 双客户端、权限撤销、故障关闭及持久审计通过；见验收记录
IvorySQL	已实测	社区版协议路径已实测通过
openGauss 社区版	指定版本协议路径已实测	openGauss 7.0.0-RC3 社区版；GaussDB 商业版未实测，不能继承此结论
TiDB	适配中	执行计划（EXPLAIN）适配实现中
OceanBase	适配中	执行计划（EXPLAIN）适配实现中
TDSQL for PostgreSQL	待目标环境验证	PG 协议候选；商业版未实测，不能用 OpenTenBase 结果替代
TDSQL for MySQL	待目标环境验证	MySQL 协议候选；商业版未实测，不与 TDSQL for PostgreSQL 混同
OpenTenBase	适配中	执行计划兼容修复实现中
崖山数据库 YashanDB	🔵 受控只读	标准 parser 与窄 SELECT 路径已接通；独立客户端 23.4.7.100 的真库流水线测试通过 SELECT、列血缘、R010、手机号脱敏和三条测试审计；HTTP/MCP 与持久化审计未测
达梦数据库 DM	🟢 指定实例防护链路实测通过	DM8 Pack3、COMPATIBLE_MODE=0：v0.7.0 有界真库复验了 HTTP MCP 查询、列血缘、R010 表策略、手机号脱敏和持久化审计；R006 注释在解析阶段失败关闭，多行分页/JOIN/函数/系统目录未测，写入未放开
PolarDB for PostgreSQL	协议路径已实测	指定 PG 15 社区镜像复用 db_type=postgres；非商业服务认证
PolarDB-X	旧官方镜像有界实测	2.0.1 单容器复用 db_type=mysql，两阶段 EXPLAIN 已适配；当前完整拓扑与商业服务待终验

"已实测"仅指对应版本、镜像/拓扑与用例，非数据库厂商官方认证；"适配中 / 待实测 / 待厂商环境"为进行中的工作，不代表当前版本已支持。欢迎各数据库厂商联系开展兼容性认证与合作：请通过交流群、仓库 Discussion 或邮件 87326549@qq.com 联系我们。

**金仓 V9 绿色边界：**仅限上述 PG 模式、单实例合成表的只读受控基础闭环；实际 license 到期日未确认。v1.7.0 验证了同一 V9R1C10 PG 模式隔离实例的 verify-full、错误 CA/主机名拒绝、证书和账号密码轮换，以及 MCP 脱敏与审计。V9 Oracle 模式、原生驱动、V8、多行/深度分页、JOIN、聚合/函数、复杂表达式、类型 OID、系统目录、EXPLAIN、HA/故障切换、备份恢复、B2 列级授权及生产负载未测。显式 GRANT CREATE SESSION 被拒；会话能力经 LOGIN + CONNECT 验证。非厂商认证或生产支持承诺；详见真库验证记录和验收记录。

**HighGo 支持边界：**仅限上述 9.0.10 企业版、PG 模式、单实例合成表的明确 schema、非恒真 WHERE、LIMIT 单表 SELECT。TLS、连接池故障切换、扩展类型/OID、其他模式及版本、生产负载、B2/B5 未验证；不代表厂商认证或完整生产支持。

**崖山客户端授权与运行：**已获厂家口头授权（C 客户端再分发），仓库无书面授权文件。v0.5.1 的 Linux 发行包与 GHCR 镜像构建使用独立客户端 23.4.7.100，并校验匹配架构的 SHA-256；正式资产须通过双架构内容与运行库检查后发布。自行从源码构建时需取得同版客户端、启用 yashan 构建标签并配置 LD_LIBRARY_PATH；缺少驱动或运行库时明确失败关闭。既有真库验证限于独立客户端的参数绑定、只读 SELECT、写入拒绝及指定流水线场景，详见 YashanDB 驱动说明。

首批金仓 + 瀚高的证据边界、复现 SQL 与待厂商项见联合案例验证记录；公众号与技术群文案见社区运营口径。

5 分钟快速开始

以下三条路径都默认只在宿主机回环地址监听。自动安装器生成的是持久使用的管理员密码，不是一次性口令；远程访问请使用 SSH 本地转发，例如 ssh -L 7780:127.0.0.1:7780 user@server，不要直接向公网暴露 7780。

1. Linux 裸机一行安装（推荐）

v0.4.0 起提供 linux/amd64 与 linux/arm64 两种原生 glibc 包：uname -m 为 x86_64 / amd64 时使用 amd64 包，为 aarch64 / arm64 时使用 arm64 包。两者均要求 glibc 2.28+ 且 systemd 为 PID 1；安装器会自动选择本机架构、校验发布包外层与包内哈希，并安装为 systemd 服务。musl / Alpine 与 CentOS 7 仍不支持：

curl -fsSL https://github.com/cuipengdba/agentsql/releases/download/v1.9.0/install.sh | sudo sh -s -- install --version v1.9.0

管道和 CI 的非 TTY 输出不会显示自动生成的管理员密码；root 可在 /etc/agentsql/agentsql.env 查看。交互终端会在首次创建凭据时显示一次，也可显式加 --show-password。离线环境同时取得 tarball 与同名 .sha256 后，校验、解压并从包根安装：

以下是 v1.9.0 的 amd64 资产名示例；v0.4.0 起 arm64 主机使用同版本的 -linux-arm64 资产名。

sha256sum -c agentsql-v1.9.0-linux-amd64.tar.gz.sha256
tar -xzf agentsql-v1.9.0-linux-amd64.tar.gz
cd agentsql-v1.9.0-linux-amd64
sudo ./install.sh install

2. Docker 一行启动

脚本默认拉取 GitHub 最新稳定 Release 对应的精确 GHCR tag；该 tag 是 linux/amd64 + linux/arm64 多架构镜像，Docker 会自动匹配运行架构。脚本生成权限为 0600 的 .env，使用 agentsql-data 命名卷，并固定绑定回环地址：

curl -fsSL https://raw.githubusercontent.com/cuipengdba/agentsql/v1.9.0/scripts/quickstart.sh -o quickstart.sh && sh quickstart.sh --version v1.9.0

GHCR 包必须由发布者设为 public，以上命令才能在未登录环境匿名拉取。先核对 v1.9.0 精确 tag 的公开状态与双架构 manifest；Docker 会从 manifest list 自动选择 linux/amd64 或 linux/arm64：

docker pull ghcr.io/cuipengdba/agentsql:v1.9.0

等价的单条 docker run 如下；随机值只通过当前 shell 环境传入，不写进命令行参数：

export AGENTSQL_SECRET="$(openssl rand -base64 24)" AGENTSQL_ADMIN_USER=admin AGENTSQL_ADMIN_PASSWORD="$(openssl rand -base64 18)"
docker run -d --name agentsql --restart unless-stopped --security-opt no-new-privileges:true -p 127.0.0.1:7780:7780 -e AGENTSQL_SECRET -e AGENTSQL_ADMIN_USER -e AGENTSQL_ADMIN_PASSWORD -v agentsql-data:/var/lib/agentsql ghcr.io/cuipengdba/agentsql:v1.9.0

3. 本地 Live Demo（一条命令，无需源码）

这套自包含环境只连接合成的 PostgreSQL/MySQL 演示数据，不连接真实数据库。无需克隆源码、无需编辑配置或构建镜像，只需下载一个 compose 文件并启动：

mkdir agentsql-demo && cd agentsql-demo
curl -fsSL -o docker-compose.yml https://raw.githubusercontent.com/cuipengdba/agentsql/v1.9.0/deploy/quickstart/docker-compose.yml
docker compose up -d

等待约 1–2 分钟，四个容器就绪后打开 http://127.0.0.1:17880：登录页已自动填好演示账号，直接点「登录」即可。「演示台」内置 5 个真实剧本：列授权 + 脱敏、列授权缺失、对象越权、DDL 越权、写操作转人工。彻底清理：

docker compose down -v

Demo 凭据均为固定演示值、写在 compose 中，仅用于本地体验，切勿连接真实数据。完整说明见 5 分钟快速上手 与 Live Demo 指南。

其他安装方式（源码构建、离线与审计环境）

需要审计每一步、修改 Compose 配置或从源码构建时，可继续使用原有流程。Docker Compose 默认只启动 AgentSQL，元数据和审计写入命名卷 agentsql-data 中的 /var/lib/agentsql/agentsql.db：

cp examples/docker/.env.example .env
openssl rand -base64 24   # 填入 AGENTSQL_SECRET，输出恰好 32 个 ASCII 字节
openssl rand -base64 24   # 填入 AGENTSQL_ADMIN_PASSWORD
docker compose up -d --build
docker compose ps

PowerShell 可分别执行两次以下命令并填写两个变量：

$bytes = [byte[]]::new(24); $rng = [System.Security.Cryptography.RandomNumberGenerator]::Create(); $rng.GetBytes($bytes); [Convert]::ToBase64String($bytes); $rng.Dispose()

访问 http://127.0.0.1:7780。Compose 也只在宿主机回环地址暴露端口。需要可观测性栈时，先在环境中设置自行生成并保存的随机值，再运行：

docker compose --profile observability up -d --build

完整说明见 可观测性示例。AGENTSQL_SECRET 必须与 agentsql.db 成对备份；直接更换 SECRET 会让既有数据源口令无法解密。生产控制面可将 metadata 与 audit 分别放入独立的 PostgreSQL 15+ 数据库，完整迁移、最小权限和回滚流程见 部署指南。

源码二进制构建按 go.mod 需要 Go 1.26、cgo、C 编译器和 glibc 兼容环境；本地 make build 使用 PATH 中的 Go，须先确认版本。当前 Makefile 与正式发布脚本默认使用 Go 1.26.9；普通构建直接使用仓库已有的内嵌控制台产物，不需要 Node.js。

以下源码构建示例仅生成本机可执行文件。自行构建的文件没有经过正式发布资产的签名与分发验收：

make build VERSION=v1.9.0
./bin/agentsqlctl init-config -o config.yaml
export AGENTSQL_SECRET="$(openssl rand -base64 24)"
export AGENTSQL_ADMIN_USER='admin'
export AGENTSQL_ADMIN_PASSWORD="$(openssl rand -base64 24)"
./bin/agentsql serve -c config.yaml

Windows PowerShell：

./bin/agentsqlctl.exe init-config -o config.yaml
$bytes = [byte[]]::new(24); $rng = [System.Security.Cryptography.RandomNumberGenerator]::Create(); $rng.GetBytes($bytes); $env:AGENTSQL_SECRET = [Convert]::ToBase64String($bytes); $rng.Dispose()
$env:AGENTSQL_ADMIN_USER = 'admin'
$passwordBytes = [byte[]]::new(24); $passwordRng = [System.Security.Cryptography.RandomNumberGenerator]::Create(); $passwordRng.GetBytes($passwordBytes); $env:AGENTSQL_ADMIN_PASSWORD = [Convert]::ToBase64String($passwordBytes); $passwordRng.Dispose()
./bin/agentsql.exe serve -c config.yaml

agentsqlctl check-config -c config.yaml 只校验配置，不要求凭据；agentsqlctl migrate -c config.yaml 会校验 SECRET 后执行元数据库迁移。

v0.5 审计报表支持 CSV、JSONL、纯 Go 生成的 PDF，以及包含四类载荷和逐文件 SHA-256 manifest.json 的 ZIP：

./bin/agentsqlctl audit report -c config.yaml --format archive --out audit-compliance.zip
./bin/agentsqlctl audit verify-archive --in audit-compliance.zip

归档校验只证明包内一致性，不替代数字签名、外部时间戳、WORM 或 SIEM 保留。

MCP 接入

先在控制台创建 Agent、配置数据源和授权策略，并保存只显示一次的 asql_... API Key。

stdio

{
  "mcpServers": {
    "agentsql": {
      "command": "/absolute/path/to/agentsql",
      "args": ["mcp", "--config", "/absolute/path/to/config.yaml"],
      "env": {
        "AGENTSQL_SECRET": "<YOUR_32_BYTE_SECRET>",
        "AGENTSQL_API_KEY": "<YOUR_AGENTSQL_API_KEY>"
      }
    }
  }
}

Streamable HTTP

兼容 MCP 本地端点为 http://127.0.0.1:7780/mcp；非本机部署必须在前面配置 HTTPS 反向代理。

{
  "mcpServers": {
    "agentsql-http": {
      "url": "http://127.0.0.1:7780/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_AGENTSQL_API_KEY>"
      }
    }
  }
}

网关始终提供 8 个基础 MCP 工具：list_datasources、list_schema、explain_query、query、execute_write、request_approval、get_approval_result、execute_approved。v0.4.0 默认开启的 PostgreSQL B5 会话/计划事务还会注册 open_session、close_session、get_session_status、begin_transaction、execute_transaction_statement、commit_transaction、rollback_transaction、get_transaction_status 8 个工具；显式关闭 mcp.sessions.enabled 后只保留基础工具。

v0.7.0 接入变化

• 支持 MCP 2026-07-28 的客户端可使用独立的 http://127.0.0.1:7780/mcp/2026-07-28。每次请求重新验证 Agent API Key、租户及 QPS，要求版本 Header、Mcp-Method、适用时的 Mcp-Name 与请求体元数据一致；无需旧版 initialize 或传输会话。该入口只提供基础工具，暂不提供 B5 会话/计划事务工具；旧 /mcp 和 stdio 继续可用。请求示例见 MCP 接入指南。
• 控制台「临时只读授权」可由同时具有策略管理和查询执行权限的管理员，给一个 Agent、一个数据源、一条精确匹配的简单 SELECT 签发最长 24 小时的任务 Key，并可撤销。Key 只显示一次、只能调用 query，不能扩大原 Agent 的权限；原有规则、脱敏和进入 SQL 流水线的审计继续适用。见 任务级临时只读授权。
• 「接入向导」增加 Agent 状态、数据库连接和策略存在性预检。预检不执行 SQL，策略存在不等于 SQL 已获授权；兼容入口 /mcp 已在真实 Dify 与 Inspector 客户端核对允许、拒绝和审计，新入口仍以 SDK 协议测试为证据。升级到 v0.7.0 前可用该版 agentsqlctl migrate --check 只读报告 schema 版本，退出码 0 为当前、2 为待迁移、1 为错误；备份及显式迁移步骤见 部署指南。

v0.8.0 任务授权与兼容性变化

• 任务 Key 现在由申请人提交精确 SQL、Agent、数据源和到期时间，另一位同租户审批人核对 SQL 后批准或拒绝；批准后原申请人一次性领取。旧直接签发 API 返回 HTTP 410，v0.7.0 已签发的 Key 继续按有效期与撤销规则生效。
• 授权 ID 关联申请、审批、签发以及进入 SQL 流水线后的允许或拒绝审计。metadata/audit 分库时管理审计先在 metadata 库的 outbox 可靠排队，再投递到 audit 库；应监控积压。
• Dify 1.17.1 真实工作流和 MCP Inspector 2.11.0 已完成指定链路复核，两个 MCP HTTP 入口的工具 schema 通过 Inspector 严格检查。升级前成套备份数据库与配对 AGENTSQL_SECRET，操作见 v1.0.0 发布说明。

功能矩阵

能力	当前代码	说明
MCP stdio / Streamable HTTP	支持	HTTP 使用 Bearer API Key；stdio 绑定单个 Agent Key
MCP 2026-07-28 无状态 HTTP	v0.7.0	独立路径 /mcp/2026-07-28，旧入口保持可用；新路径不注册 B5 工具
任务级临时只读授权	v0.7.0	限 Agent、数据源、精确 SQL 与最长 24 小时；只允许 query，可撤销
任务授权异人审批与领取	v0.8.0	SQL 仅审批详情向有权审批者展示；原申请人一次性领取 Key
接入预检与迁移版本检查	v0.7.0	向导预检不执行 SQL；migrate --check 只读且不替代备份、真实请求验收
Agent 与数据源管理	支持	API Key 仅创建/轮换时返回明文，库内保存哈希
PostgreSQL / MySQL SQL 解析	支持	结构化 AST 判定，不依赖文本正则代替解析
表级与列级授权	支持	默认拒绝；特殊 JOIN/通配语义见“已知限制”
只读、危险语句、限流与 Explain 风险规则	支持	四态结果：allow / deny / approve / warn
受控查询与写入	支持	超时、连接上限、结果截断与错误脱敏
人工审批	支持	建单、管理员决定、Agent 查询结果
列级脱敏	支持	九类型按能力矩阵使用 mask / hash / block / range；range 仅用于 number / date，以数值分桶或日期截断保留粗粒度分布且无需密钥
表.列感知脱敏与安全兜底	支持	规则支持全局列、表.列、模式.表.列三档作用域，按来源表/来源列精确命中；JOIN 裸列、SELECT *、CTE 外层等无法确定列归属且可能涉及受保护表时 fail-closed 固定阻断为 ***，不可关闭。PostgreSQL 留空模式匹配任意模式，MySQL 留空模式表示当前库
SQLite / PostgreSQL 控制面、审计导出与仪表盘	支持	SQLite 默认零配置；PostgreSQL 可使用独立 metadata/audit 库
Webhook / Syslog 通知外发	支持	live-only、best-effort；默认仅 deny/error，审计库仍是权威记录
Web 管理控制台	支持	可用 console_enabled: false 完全不挂载管理面
大屏实时事件流	支持	SSE，默认开启，最多 100 条并发管理端连接

数据库兼容矩阵

v1.9.0 代码的注册表覆盖 8 大类、29 款数据库（8 款关系型 + 21 款 NoSQL / 向量）。瀚高 HighGo 已作为独立的限定只读类型计入；金仓 KingbaseES V9 另列为指定实例 PG 协议路径，不计入 29 款；分类表共 30 行。🟢 表示解析、授权、受控执行、脱敏、审计链路在所述范围通过；🔵 受控只读＝连接、元数据、只读查询子集；🔷 连接级＝ping、版本、Schema、只读预览；🟡 待验证＝等厂商环境。指定实例闭环不代表完整生产支持。

类别	数据库	适配状态	边界说明
关系型	PostgreSQL 14–18	🟢 已适配 · 完整防护	全链路实测通过
	MySQL 8.0	🟢 已适配 · 完整防护	全链路实测通过
	Oracle 23ai	🔵 已适配 · 受控只读	连接 / 元数据 / 只读查询子集
	达梦 DM8	🟢 指定场景闭环	Pack3、COMPATIBLE_MODE=0：v1.5.0 完成客户端与权限撤销；v1.6.0 补齐审计故障、锁等待超时、取消与恢复复验；见验收记录
	崖山 YashanDB	🔵 已适配 · 受控只读	标准 parser 接通，真库流水线通过
	SQL Server 2025	🔵 已适配 · 受控只读	连接 / 元数据 / 只读查询子集
	Vastbase G100	🔵 指定版本受控只读	V3.0 Build 9 PG 模式的有界 SELECT、表授权、脱敏、持久审计、客户端、权限撤销与停库恢复实测；v1.6.0 补齐故障关闭复验，v1.8.0 验证 verify-full、证书及凭据轮换和双客户端真调用；正式主备、其他 Build 与生产负载未测，见验收记录。
	瀚高 HighGo	🔵 指定版本受控只读	独立 highgo 类型：9.0.10 企业版 PG 模式、单实例合成表的有界 SELECT、客户端、权限撤销、审计与故障关闭；见验收记录
	金仓 KingbaseES V9（另列）	🟢 指定场景闭环	V9R1C10 PG 模式：v1.5.0 完成客户端、权限撤销与网络隔离恢复；v1.6.0 补齐故障关闭复验，不计入 29
键值	Redis	🔷 已适配 · 连接级	ping / 版本 / Schema / 只读预览
	Valkey	🔷 已适配 · 连接级	复用 Redis 适配
	Memcached	🔷 已适配 · 连接级	ping / 版本 / Schema / 只读预览
文档	MongoDB	🔷 已适配 · 连接级	ping / 版本 / Schema / 只读预览
	Couchbase	🔷 已适配 · 连接级	同口径
	CouchDB	🔷 已适配 · 连接级	同口径
宽列	Cassandra	🔷 已适配 · 连接级	ping / 版本 / Schema / 只读预览
	ScyllaDB	🔷 已适配 · 连接级	同口径
	HBase	🔷 已适配 · 连接级	同口径
图	Neo4j	🔷 已适配 · 连接级	ping / 版本 / Schema / 只读预览
	JanusGraph	🔷 已适配 · 连接级	同口径
	NebulaGraph	🔷 已适配 · 连接级	同口径
时序	InfluxDB	🔷 已适配 · 连接级	ping / 版本 / Schema / 只读预览
	Prometheus	🔷 已适配 · 连接级	同口径
	TimescaleDB	🔷 已适配 · 连接级	同口径
OLAP	ClickHouse	🔷 已适配 · 连接级	ping / 版本 / Schema / 只读预览
	Apache Doris	🔷 已适配 · 连接级	同口径
	StarRocks	🔷 已适配 · 连接级	同口径
向量	Milvus	🔷 已适配 · 连接级	ping / 版本 / Schema / 只读预览，不代表完整向量检索
	Qdrant	🔷 已适配 · 连接级	同口径
	Weaviate	🔷 已适配 · 连接级	同口径

NoSQL / 向量目前是连接级、低阶支持；只读预览不代表完整查询、检索或服务端安全能力。21 款注册类型、默认端口及 HBase/Couchbase 的实际连接端口边界见 NoSQL 支持范围。DM8、金仓、Vastbase 的指定实例在 v1.5.0 通过受控只读查询、真实 MCP 客户端、权限撤销、断库恢复、脱敏和持久审计；v1.6.0 在同一范围通过独立审计库故障、锁等待超时、客户端取消、数据库端终止及恢复复验，仍不声明完整生产支持。DM8 的 R006、多行分页、JOIN、函数和系统目录未验证，写入未放开。Oracle 仍限于既有有界证据。YashanDB 真库流水线测试已通过 SELECT、列血缘、R010、表列定向手机号脱敏及三条测试审计；该测试的认证、策略、审计存储端口为测试夹具，HTTP/MCP、持久化审计和最小权限账号与流水线的组合未测，见 DM/Oracle 方言边界及 YashanDB 方言边界。所有实测仅基于指定容器镜像与合成用例，并非数据库厂商官方认证；协议兼容不等于安全语义相同。所有数据库请求须经 AgentSQL 网关，并使用专用最小权限账号；解析、授权或能力事实不明时一律 fail-closed。详情见 SECURITY.md。

控制面存储另计：SQLite 默认零配置，可 combined 存储；PostgreSQL 15+ 可 combined 或独立 metadata / audit 库（PG18 为基准）。使用 agentsqlctl migrate-sqlite-to-postgres 可从 SQLite 迁至单库或独立双库。

已知限制与安全边界

• 脱敏按全局列、表.列、模式.表.列三档作用域在结果层匹配：能唯一归属到物理表的顶层直接投影列按来源表/来源列精确命中；PostgreSQL/MySQL 已验证的函数/表达式、聚合、CAST、UNION、CTE 与视图引用等派生输出，在能证明同源时按规则处理，来源不明而可能涉及受保护列时固定阻断为 ***。这不是完整 DLP；数据库函数与视图内部语义、统计侧信道及绕过网关的直连仍需数据库最小权限、列级授权、安全视图与审批共同约束。
• hash 是不可逆指纹，不是加密，也不能解密还原。它在业务数据库返回结果后计算，不下推到数据库内的 JOIN/WHERE；确定性会暴露相等关系和频率，共享同一 key 还会带来跨库关联风险。
• block 不输出原值字符、长度或等值关系，但仍保留结果集行列形状、行数、列名、是否有结果，并因空值原样返回而暴露该格为空/NULL；它不是匿名化。block 在数据库执行后处理，不减少数据库读取，也不阻止数据库侧使用原值做 WHERE/JOIN/GROUP BY，只阻止结果单元对外返回。其固定 *** 是不透明字符串，不保证数值、日期或 JSON 的 schema 兼容。
• PostgreSQL 有列策略的 SELECT（含多表 JOIN、自连接、谓词和通配投影）必须走 B2 列绑定路径；B2 不可用时执行前失败关闭。MySQL 8.0/8.4 只在显式开启并完成双账号登记的单表 InnoDB SELECT 子集进入独立列授权路径；其余有列策略的 MySQL 查询执行前拒绝。Vastbase 等仍无等价列级绑定证明。没有列策略时仍由表策略约束。
• AllowedTables 中的 * 或 schema.* 表示管理员显式授予匹配表的全部列；此时精确列白名单不再收紧。单表使用精确列白名单时，应显式列出投影列。
• PostgreSQL 的 B2 列级授权出厂默认开启；普通 schema-qualified 基表使用免扩展的 CATALOG_CLOSED_V1，原生 binder 仅用于可选增强。MySQL 不进入 B2 PostgreSQL 路径。
• B5 跨请求逻辑会话与 PostgreSQL 计划事务出厂默认开启；MySQL 跨请求事务不支持，配置 mcp.transactions.mysql: true 会拒绝启动。每个 operation 仍只允许一条顶层 SQL，并受预检计划和会话安全边界约束。

本地测试模式

AGENTSQL_INSECURE=1 永久只表示“允许公开测试凭据”：它可在本地开发/测试中放行长度正确的公开示例 SECRET 和非空弱管理员口令，但仍拒绝空 SECRET、非 32 字节 SECRET 与空管理员口令。它不会关闭认证、安全规则或 fail-closed 行为，生产环境不得设置。

文档与社区

• 五分钟快速上手
• 使用手册
• MCP 接入指南
• 任务级临时只读授权（v0.7.0）
• v0.7.0 发布说明与验收记录
• v0.7 运维手册
• 敏感列发现与脱敏草稿
• Webhook / Syslog 通知外发与安全配置
• 部署、PostgreSQL 控制面、升级、备份与 systemd
• 本地 Live Demo、定期重置与公开部署安全清单
• 产品与工程规范
• 安全策略与私密漏洞报告
• 变更记录
• Issue 反馈
• 商业授权与企业版合作

请不要在公开 Issue 中提交真实密钥、口令、连接串或未修复漏洞细节；未修复漏洞请按 SECURITY.md 走私密渠道。

加入社区（微信）

交流群 #2	交流群 #3	公众号	个人微信
扫码进群	扫码进群	扫码关注	扫码加好友

交流群 #1 已超过 200 人，无法扫码加入：请先添加作者个人微信（崔鹏），备注「AgentSQL」，由群主拉你进群。 群二维码 7 天内有效；若过期请添加个人微信或关注公众号获取最新入群方式。

构建与贡献

go vet ./...
go test -race -count=1 ./...
make build VERSION=v1.9.0

pg_query_go 要求 cgo；不要使用 CGO_ENABLED=0 或 Alpine/musl 构建。提交改动前请阅读 SPEC，为行为变化补测试，并保持 tests/corpus 决策语料不被无意改写。

许可、商业授权与商标

**许可更换声明：**v0.4.0 及更早版本的既有源码、tag 和发布包保持其发布时适用的原许可，继续按原许可使用，不重打 tag、不重发资产；自 v0.5.0 起，开源版本切换为 Apache License 2.0（含 NOTICE 文件），并提供独立的 商业授权说明。Apache-2.0 允许闭源集成、SaaS 商用与再分发。需要商标使用许可、企业模块、保修或 SLA 时，请参阅商业授权说明。AgentSQL（含中文名 “智盾”）名称与 Logo 的商标权保留；可以依许可证 fork 源码，但不得以 AgentSQL / 智盾名称或 Logo 冒充官方版本对外发行。商业授权与企业版合作：87326549@qq.com ｜ https://agentsql.cn 。

v0.5 人员认证（MFA / OIDC / LDAP）的配置、威胁边界和迁移说明见 身份认证指南。