Independent AI data Q&A agent
Sign in to AgentSQL's own UI, select a bound datasource, and ask a natural-language question. Review the SQL, result, and audit. SQLBot is not needed at runtime.
Native Q&A steps → v4.6.0
AI Q&A Agent
MCP Server security gateway
AgentSQL combines its own AI data Q&A agent with an independent MCP Server database security gateway. Ask in AgentSQL or connect an external MCP client: both paths enforce current identity and grants, SQL checks, controlled execution, result masking, and durable audit.
The native Go Q&A service and Web UI run without SQLBot. A fixed-version SQLBot execution path may optionally connect through the verified adapter; arbitrary SQLBot deployments are not drop-in compatible. v4.6.0 covers only the bounded paths in its release notes and has not been validated on the user's actual business system.
Starting from v0.5.0 Apache-2.0 Open Source · Go single binary delivery (glibc/cgo build) · Self-hosted · No third-party telemetry dependencies
AgentSQL itself interprets the question, selects currently authorized schema and generates SQL; its security core decides whether execution and result delivery are allowed.
Requests only enter the execution phase if allowed by the policy
Two-in-one product
Native Q&A agent and independent MCP Server
Both entry points share AgentSQL's security execution core. SQLBot is an optional integration, not a runtime dependency of native Q&A.
Independent MCP Server security gateway
External AI agents call MCP tools with a dedicated Agent Key. AgentSQL rechecks identity, grants, SQL, masking, and audit. SQLBot is an optional fixed-version adapter client.
MCP steps →Use both entry points together
Employees ask in the native UI while external agents query through MCP. Configure credentials and grants separately; share controlled execution and query audit.
Combined-use steps →AgentSQL native Q&A
AgentSQL owns the path from question to controlled result
The Q&A agent interprets questions and proposes SQL; the security gateway makes the final execution decision. v4.6.0 real-model and real-PostgreSQL acceptance covers only paths listed in the release notes.
Resolve current identity
Use current user, workspace, and datasource bindings to select permitted tables, columns, and business terms. Old sessions never inherit revoked grants.
Generate candidate SQL
The configured model interprets the question against authorized schema and generates SQL; a fixed local ONNX model helps select relevant tables. Users must still check business meaning.
Execute under policy
SQL is checked against parsing, table/column and bounded row rules, read-only limits, and resource budgets. Results are masked and durably audited; unsafe requests are rejected.
Deliver with current grants
Answers, reopened history, and exports recheck authorization. Revocation or model, database, storage, and audit failures do not release stale SQL or data.
Native Q&A UI
Chinese release screenshots and concept images, clearly separated
The first two images come from an isolated run of the official v4.5.0 package: the Q&A entry before datasource binding and empty model settings. The last two are labeled concept images with synthetic data, not product captures or additional acceptance evidence. The official release notes define real-model support.
Current capabilities
A capability matrix instead of a release-by-release list
Statuses describe verified v4.6.0 paths and limits. See the release notes and integration guides for deployment details.
| Capability | Status | Boundary |
|---|---|---|
| Independent AI data Q&A agent | Verified bounded path | Native Go/Web Q&A with local models and operator-registered PostgreSQL gateway aliases; no SQLBot runtime |
| MCP Server security gateway | Independently deployable | stdio and HTTP MCP; current identity, grants, controlled execution, masking, and durable audit on each request |
| SQLBot integration | Optional fixed baseline | Verified adapter calls AgentSQL MCP; arbitrary SQLBot environments are not automatically compatible |
| Basic assistant and page embed | Verified bounded path | One-source basic guest assistant and Type 4 page embed with origin and revocation limits |
| Type 1 advanced assistant | Verified bounded path | Fixed SQLBot Community v1.10.3, operator-registered third-party directory, single-user explicit row rule, and controlled PostgreSQL gateway alias; configure host certificate and origin as documented |
| Broader permissions and Community parity | Planned | Active role, multi-user, and non-empty whitelist rules plus remaining Community pages/APIs are outside this release's support claim |
Why you need a safety gate
Make the model’s database access constrained, explainable, and traceable
The SQL generated by the model is non-deterministic. AgentSQL puts identity, permissions, syntax, risk and execution control in one request link to reduce the following common risks.
Dangerous statement
Illusions may result in dangerous writing methods such as UPDATE / DELETE that lack WHERE; whether to intercept depends on the enabled rules, policies and Agent capability configuration.
Unauthorized access
The model may query unauthorized tables or columns and needs to be judged based on Agent, data source, object and column permissions before execution.
Sensitive data returned
Fields such as mobile phone number and email address may enter the model context in plain text and need to be coded according to the configuration before the results are returned.
It is difficult to assign blame afterwards
In the absence of request identity, SQL, rule hits, and decision records, it is difficult to restore why an access was allowed or denied.
Common Line of Defense:The security gateway cannot replace the minimum permissions, read-only accounts, security views and network isolation on the database side.
six-segment link
From identity to traces, tightening access step by step
QPS/connection limit is controlled by entrance and rules.
- 01
Authentication
Verify API Key, load Agent, data source and policy, and close if failed.
- 02
parse
AST is built according to PostgreSQL/MySQL dialect, and exceptions such as malformation/multiple statements are rejected according to rules.
- 03
Security check
Do a static check that does not touch the library first. Only when the static check is not rejected, establish a controlled connection and do dynamic checks such as read-only EXPLAIN/metadata.
- 04
decision making
press deny > approve > warn > allow is aggregated into release/alarm/interception/transfer to manual.
- 05
Execution and masking
Only allow/warn is executed to limit the connection, timeout and number of result rows, and the results are coded by column before returning.
- 06
leave traces
The allow/warn/deny/approve/error decision that enters the SQL pipeline is synchronously written into the application layer audit. Audit failures are fail-closed by design; tool layer pre-denials may not have persistent traffic auditing.
Reproducible demonstration
Demonstration and actual running screenshots
Live Demo only connects to the synthetic demo library, provides read-only or controlled playbooks and resets periodically; no real data, credentials, tokens or other secrets may be entered. Public Q&A is a simulation only; no live model is connected.
This is a non-production configuration. Read the demo safety notice before entering the console.
Open the Live Demo entrance Try simulated Q&A
Scene 1Read-only query release
The controlled read-only query returns 5 rows and generates an audit number.
Scene 2None WHERE write request rejected
No WHERE write request is ultimately denied; hits include deny-level R002, R010, DEMO_NON_SELECT, and approve-level R202 (R202 itself is not a deny rule).
Scene 3Sensitive result coding
The mobile phone number and email address are matched according to the final result list, and basic coding is performed before returning.
Scene 4Big result risk warning
R005 gives a warning for a no-LIMIT query that is estimated to be about 600 rows, and only returns the first 20 rows.
Scene 5Unauthorized object denied
Query for unauthorized internal_notes was rejected by R010 and not executed.
Scene 6audit evidence chain
The audit details record basic information, six time lines, SQL original text, normalized SQL, hit rules, and clearly mark blocked statements as not executed.
Real-time big screen
Put risk changes into observable views
Recent risk events are pushed in real time via authenticated SSE (/api/v1/stream), and polling is performed when disconnection occurs; KPIs, trends and distributions support manual and automatic refresh in about 30 seconds; Prometheus indicators can be connected to existing monitoring.
Audit and traces
Review the complete evidence chain from the decision list
Provides application layer audit list, combination filtering, evidence chain viewing and JSONL export to facilitate traceability and security analysis; PDF compliance report is in the roadmap. It is not a regulatory-level WORM, and it cannot prevent the database owner/superuser from directly changing the underlying data.
Core features
Full path for controlled database access
MCP dual entrance
Preserving stdio with stateful Streamable HTTP /mcp;Add independent MCP 2026-07-28 stateless HTTP entry /mcp/2026-07-28, re-authenticate each request. The new portal does not currently provide the B5 cross-request tool.
Deny by default
Combine API Key, Agent capability level, object/column authorization and AST rules; fail-closed by design when exceptions or key dependencies fail.
controlled literacy
Provides read-only protection, dangerous SQL interception, EXPLAIN risk, timeout, connection/QPS/result row limit and manual approval.
Result masking
The mobile phone number/email address is basically coded based on column name matching, which is not a complete DLP; the data source password is stored in AES-256-GCM encryption using a 32-byte key.
control surface
Default zero configuration SQLite, optional PostgreSQL 15+; PG18 is the baseline. Supports single database or independent metadata/audit dual databases and SQLite→PG migration. The independent audit database is an optional layout rather than the default.
Observables and consoles
Provides Prometheus metrics, health/readiness probes, Grafana dashboards, and an embedded web console.
Task-level temporary read-only authorization
The applicant submits an Agent, a data source and a simple SELECT that completely matches; another authorized user of the same tenant checks and approves. After approval, the applicant can receive a key for up to 24 hours at a time. Key can be revoked, and original object permissions, rules, masking and auditing are still in effect.
Access wizard
In the same process, select the Agent and data source, check the connection, generate Dify/Inspector keyless access instructions, interpret the target SQL offline, and locate the record with the audit ID of the real call. Preflight does not execute Agent SQL.
Version check before upgrade
agentsqlctl migrate --check Read-only reporting controls the schema status of the control library; production upgrades still require backing up the database and pairing keys, and then the migration account explicitly performs the migration.
Docs / Downloads
Choose a guide by usage mode
Native Q&A, the independent MCP gateway, and combined use each have setup steps and acceptance checks. The following guides provide configuration details.
Get started quickly
Use the local Live Demo to see the effect, and then access your database in the order of default rejection.
User manual
Press the console menu to learn about auditing, agents, data sources, permissions, rules, approval and masking boundaries.
MCP Access Guide
Select existing ones based on client capabilities /mcp, independent and stateless /mcp/2026-07-28 or stdio, view tools with reject boundaries.
More information
Deployment Guide · Current operation and maintenance manual · Offline delivery · SQLBot access · Type 1 setup · Online demo instructions
v4.6.0 provides Linux amd64/arm64 installation packages and multi-architecture images; the Live Demo entry only uses synthetic data.
GHCR multi-architecture pull (automatically matches amd64/arm64)
docker pull ghcr.io/cuipengdba/agentsql:v4.6.0One-click installation (Linux amd64/arm64)
curl -fsSL https://github.com/cuipengdba/agentsql/releases/download/v4.6.0/install.sh | sudo sh -s -- install --version v4.6.0linux/arm64 native glibc package is provided starting from v0.4.0 · x86_64 / amd64 or aarch64 / arm64 · glibc ≥ 2.28 · systemd · requires sudo/root
Compatibility
Database compatibility matrix
The matrix retains the database scope verified for v4.3.0; v4.6.0 does not expand production support claims. Each supported product, version and topology remains bound to its acceptance evidence.
8 categories / 30 models registeredopenGauss and HighGo HighGo have been included; another designated instance of KingbaseES KingbaseES V9 is listed for PG protocol verification
| Category | database | Adaptation status | Boundary description |
|---|---|---|---|
| Relational | PostgreSQL 14–18 | 🟢 Adapted · Complete protection | Passed the actual test of the whole link |
| MySQL 8.0 | 🟢 Adapted · Complete protection | Passed the actual test of the whole link | |
| Oracle AI Database 26ai Free | 🔵 Specify version controlled read-only | FREEPDB1, server 23.26.3.0.0: verified TCPS, opt-in bounded PLAN_TABLE checks, least-privilege HTTP MCP, R010, masking, revocation and isolated certificate rotation; wallets, mTLS, RAC, commercial editions and full production support remain unverified. | |
| Dameng DM8 | 🟢 Specify scene closed loop | Pack3, COMPATIBLE_MODE=0 verified TLS and bounded live read-only path | |
| YashanDB YashanDB | 🔵 Specify version controlled read-only | 23.4.1.109 Specified instance: least privilege HTTP MCP, R010, masking, dual client and independent persistent audit passed; TLS, active and backup and full production support not verified | |
| SQL Server 2025 Developer | 🔵 Specify version controlled read-only | 17.0.5015 Linux x86_64 single instance: strict TLS, isolated certificate rotation, SELECT/SHOWPLAN revocation, R010, masking, durable audit and outage recovery; Windows, Always On, read replicas and full production support remain unverified. | |
| openGauss Community Edition 7.0.0 LTS | 🔵 Specify version controlled read-only | Independent type, build 2397a86f specifies single instance: strict TLS, ordinary physical single table narrow SELECT, real MCP, R010, masking, approval, dual client, permission revocation and fault shutdown passed; GaussDB commercial version, primary and backup and full production support have not been verified | |
| Vastbase G100 | 🔵 Specify version controlled read-only | V3.0 Build 9 PG mode: Bounded single table SELECT, authorization, masking, MCP and persistent audit testing; v1.8.0 verifies TLS, certificate and credential rotation. Temporary license, untested for HA, other versions and production loads | |
| HighGo HighGo | 🔵 Specify version controlled read-only | Standalone highgo type; 9.0.10 Enterprise PG mode bounded SELECT, permissions, masks, clients and failed link pass-through | |
| KingbaseES KingbaseES V9 (separate list) | 🟢 Specify scene closed loop | V9R1C10 PG mode basic closed loop, not included in 30 | |
| key value | Redis | 🔵 Specify version controlled read-only | 8.2.9 TLS/ACL: exact keys and Hash fields; a two-data-node, three-Sentinel topology verifies bounded reads after failover, masking and audit. Cluster, writes and full production support remain unverified. |
| Valkey | 🔵 Specify version controlled read-only | 8.1.10 TLS/ACL: the same narrow key/Hash-field contract as Redis, independently verified on two data nodes and three Sentinels. Cluster, writes and full production support remain unverified. | |
| Memcached | 🔷 Adapted · Connection level | ping /version/schema/read-only preview | |
| Documentation | MongoDB | 🔵 Specify version controlled read-only | 7.0.45 three-member TLS replica set: approved-index bounded reads, exact collection/field grants, projection, masking, durable audit and primary change verified. Sharding, writes and full production support remain unverified. |
| Couchbase | 🔷 Adapted · Connection level | Same caliber | |
| CouchDB | 🔷 Adapted · Connection level | Same caliber | |
| wide column | Cassandra | 🔷 Adapted · Connection level | ping /version/schema/read-only preview |
| ScyllaDB | 🔷 Adapted · Connection level | Same caliber | |
| HBase | 🔷 Adapted · Connection level | Same caliber | |
| Figure | Neo4j | 🔷 Adapted · Connection level | ping /version/schema/read-only preview |
| JanusGraph | 🔷 Adapted · Connection level | Same caliber | |
| NebulaGraph | 🔷 Adapted · Connection level | Same caliber | |
| Timing | InfluxDB | 🔷 Adapted · Connection level | ping /version/schema/read-only preview |
| Prometheus | 🔷 Adapted · Connection level | Same caliber | |
| TimescaleDB | 🔷 Adapted · Connection level | Same caliber | |
| OLAP | ClickHouse | 🔵 Pinned controlled read | 26.8.31.2 TLS single node: explicit MergeTree columns, String equality conditions, and optional tighter query resource budgets. Least privilege, masking, durable audit, and two clients passed. Clusters, other versions, and full production support remain unverified. |
| Apache Doris | 🔷 Adapted · Connection level | Same caliber | |
| StarRocks | 🔷 Adapted · Connection level | Same caliber | |
| Vector | Milvus | 🔵 Pinned controlled read | 2.6.25 TLS standalone: exact collection/field grants, single-vector COSINE search, and optional authoritative tenant equality filters; source-aware masking and durable audit. Other versions, clusters, and full production support remain unverified. |
| Qdrant | 🔷 Adapted · Connection level | Same caliber | |
| Weaviate | 🔷 Adapted · Connection level | Same caliber |
Complete protection: Parsing / Authorization / Controlled Execution / masking / Audit
Controlled read-only: Connection/Metadata/Read-only query subset
connection level:ping /version/schema/read-only preview
Each database claim is limited to its specified instance, protocol path, and acceptance record. Protocol compatibility or a successful connection is not vendor certification or blanket production support. Route business access through AgentSQL with least-privilege accounts. See the security boundaries and historical acceptance records.
Database ecosystem
Integrate by verified capability, not database count
The matrix above separates full-path protection, specified-version controlled reads, and connection-level support. Domestic databases, NoSQL, and vector stores remain bounded by exact versions, modes, and test scenarios. Recheck grants, failure behavior, and audit before a new deployment.
Database compatibility matrix · Security boundaries · Historical acceptance
Get started
Quick Start
It usually takes a few minutes to complete (subject to the network environment) when Docker and the dependent network are ready. GHCR tag will automatically match linux/amd64 or linux/arm64; the source code path is still subject to the repository README.
GHCRamd64 / arm64
# Docker selects the image for the current platform automatically
docker pull ghcr.io/cuipengdba/agentsql:v4.6.0
# Use the repository quickstart to generate credentials and start the demo
curl -fsSL https://raw.githubusercontent.com/cuipengdba/agentsql/v4.6.0/scripts/quickstart.sh -o quickstart.sh
sh quickstart.sh --version v4.6.0Default only binds
127.0.0.1:7780Live Demosynthetic data
# Copy the demo environment example and replace the placeholder credentials
cp examples/docker/demo.env.example demo/demo.env
# Start or reset the demo environment
bash ./demo/reset.sh
# Windows PowerShell
.\demo\reset.ps1use
docker-compose.demo.yml, visit http://127.0.0.1:17880Deployment tips:Default only binds loopback; do not submit
.env; SECRET and database should be backed up in pairs; do not expose 7780, 17880 or database ports to the public network.Security
Clarify the scope of capabilities and then design defense in depth
The following restrictions should be evaluated in conjunction with database permissions, network policies, backup and operational controls.
- Connection rangeOnly connections through the gateway are protected. Directly connected owner/superuser/DBA are not within the scope.
- Result maskingMask results using verified column provenance, conservatively blocking values when provenance cannot be proven. This is not complete DLP.
- Application auditThe audit leaves traces at the application layer, non-regulatory level WORM, and does not protect against high-privileged DBAs.
- JOIN authorizationTable authorization always applies. Supported PostgreSQL B2 paths also verify provable projection-column provenance and reject unproven cases; this does not extend to every dialect.
- Wildcard permissions
*/schema.*These are broad grants and require care. Applicable table/column policies, rules and database privileges still constrain actual results. - Column name lookbackVerified expression, aggregate, CAST, set-operation and CTE paths track protected sources. Unknown view or function internals are not fully proven; non-null values whose safety cannot be established are conservatively blocked.
- SQL/Transaction BoundariesB2 column-level authorization for PostgreSQL, old
/mcpThe portal's B5 cross-request logical session and scheduled transactions are enabled by factory default; the new stateless portal does not provide B5 tools. MySQL does not enter the B2 PostgreSQL path and does not support B5 cross-request transactions. Only one top-level SQL is still allowed per operation, subject to preflight plans and session security boundaries. - mission authority boundariesTemporary Key only applies to a simple SELECT that matches exactly; it does not grant permission to write or bypass Agents, objects, rules, and database accounts.
- Approval boundariesSQL will not be automatically executed when the approval is passed; the original Agent can be called with the approval order number within the validity period
execute_approvedOnce. Re-verify identities, policies and data sources before execution, and will not automatically retry when rejected or the result is unknown. - Demo environmentThe public Demo uses only synthetic data and read-only or controlled scenarios. It does not connect to real business databases.
- Deployment boundariesThe read-only two-gateway topology, OAuth/OIDC and tenant governance have acceptance evidence in specified environments. Arbitrary replica counts, HA for stateful transactions and unverified vendor production support are not promised.
Future scope
Advance capabilities without repeating every release on the homepage
Detailed changes and acceptance records remain in GitHub Releases. Current support follows the capability matrix above and the v4.6.0 release notes.
- v4.7.0 plannedActive role, multi-user, and non-empty whitelist rules
- v4.8.0 plannedRemaining Community pages/APIs and wider connector parity
FAQ
FAQ
How does it relate to MCP?
It is itself an MCP Server; MCP is the standard protocol for model communication with external tools/data.
Can't the model be connected to the database without MCP?
Yes, applications can also use self-developed APIs, database agents or server-side managed credentials to connect; AgentSQL provides a unified identity, policy, controlled execution and audit entrance for MCP, not the only connection method.
How does AgentSQL Q&A relate to SQLBot?
AgentSQL has its own Go Q&A agent, Web UI, and model orchestration; it does not require SQLBot. SQLBot is an optional integration that can route database execution through the verified AgentSQL MCP security gateway adapter. This does not imply full SQLBot feature parity; see the v4.6.0 release notes.
How is the performance?
Static determination is at the millisecond level; in the benchmark of in-memory fake executor, 20 workers / 200,000 samples, stripping the real database network and execution time, the gateway CPU path P99 is about 1.81 ms. This number is not the end-to-end query delay. The real delay depends on the connection, EXPLAIN, database execution and audit storage.
Can individuals and companies use it?
The current release is licensed under Apache-2.0. Read the repository's LICENSE and NOTICE for the conditions of use, modification and distribution.
What databases/clients are supported?
Please see aboveCompatibility matrix, which lists the business database, control plane, MCP transport, host and deployment scope.
Community / Contact
Follow the public account or contact the author directly
Follow the WeChat official account to learn about PostgreSQL/AgentSQL and database security technology, or add the author's personal WeChat account and note "AgentSQL".
