copilot-datagate

📘 DataGate — 安全、适用于 AI 的数据网关

DataGate 是一个无头、安全且由策略驱动的网关，以可控、可预测且不允许自由 SQL 的方式向 AI 工具（如 GitHub Copilot）开放数据库。

DataGate 充当大模型与真实数据库之间的中间层：它不允许直接访问数据库，不开放任意查询，也不允许写入操作。 它专为只读、了解架构、多数据库且完全适用于大模型而设计。

🎯 主要目标

• 安全访问数据 — 通过数据库角色、策略引擎和受控查询构建器确保只读。
• 数据库抽象 — 模型不会生成 SQL：DataGate 会构建安全且经过验证的查询。
• 多数据库 — 可连接多个应用的不同数据库，就像无头 DBeaver 一样。
• 策略引擎 — 对表、列、筛选条件、限制和操作复杂度进行细粒度控制。
• 架构感知 — 自动加载数据库架构并应用安全规则。
• 真正的并发能力 — 异步且安全的架构，非常适合 Copilot 并行发起请求。
• 指标与审计 — 跟踪请求、耗时、错误和限制，便于调试和可观测性。
• 性能分析 — 提供进程内延迟分析（最小值/平均值/p50/p95/p99/最大值），用于持续监控性能。
• 抽象后端 — 为数据库后端提供通用的只读 trait，并为 PostgreSQL、MySQL/MariaDB 和 SQLite 提供具体实现。

🧩 主要功能

• 受控查询构建器 — select、search、aggregate 等语义操作，并自动进行验证。
• 类型化 MCP select — JSON 契约，只读执行并返回 JSON 行，包含策略、审计和已清理的错误；MCP 传输仍是后续步骤。
• 类型化 MCP search — 使用 ILIKE 在允许的列上进行语义搜索，并提供参数化查询、策略／速率限制／指标／审计，以及服务端输出限制。
• 类型化 MCP aggregate — 对允许的列执行 count、sum、avg、min 和 max，使用参数化筛选条件，不支持自由 SQL 或 GROUP BY。
• 版本化 MCP API — 为 API 版本和可用工具提供稳定的描述信息。
• MCP stdio 传输 — 通过策略安全路径执行握手、发现，以及 select、search 和 aggregate 调用。
• 高级筛选 — 支持模式（LIKE／ILIKE）、范围（BETWEEN）和全文搜索（to_tsvector + plainto_tsquery），并始终进行参数化处理和策略验证。
• 受控架构目录 — 经策略筛选的表、视图、索引、约束（PK/FK/UNIQUE/CHECK/EXCLUSION）、触发器、函数、过程和序列内省；仅在安全时提供 DDL 定义。
• 速率限制 — 防止模型陷入循环和执行过重的查询。
• 输出限制 — 响应始终有限、安全且结构化。
• 确定性错误 — 不泄露架构、不暴露 SQL、不返回堆栈跟踪。
• 结构化错误 — 稳定的信封，包含代码、通用消息和 retryable 指示。
• 外部配置 — 使用 TOML 文件配置策略、限制和命名配置文件（dev/staging/prod）。
• MCP 输入加固 — 验证 request_id，限制文本载荷和基数，以缩小 DoS／输入滥用的攻击面。
• 动态策略 — 无需重建 MCP 工具，即可原子替换活动策略，也可从 TOML 重新加载。

DataGate 不会暴露用于自由 SQL 查询的 MCP 函数：Agent 只发送结构化参数，这些参数会在构建参数化查询之前根据架构和策略进行验证。

公开错误使用代码 invalid_request、policy_denied、backend_unavailable 和 internal_error。SQL、堆栈跟踪、密码、筛选值和未经授权的对象名称不会越过 MCP 边界。

PostgreSQL 配置

PostgreSQL 凭据不会存储在配置文件或代码中。服务从运行时环境读取连接信息：

• 简洁模式：DB_URL
• 组件模式：DB_HOST、DB_PORT（默认值为 5432）、DB_USER、 DB_PASSWORD、DB_NAME
• PostgreSQL 选项：DB_OPTIONS，格式为 key=value&key=value
• 连接池：DB_MAX_CONNECTIONS 和 DB_ACQUIRE_TIMEOUT_SECS

SQLite 配置

要以只读模式使用 SQLite，请配置以下两种方式之一：

• 完整 URL：SQLITE_URL
• 文件路径：SQLITE_PATH

SQLite 连接池选项：

• SQLITE_MAX_CONNECTIONS
• SQLITE_ACQUIRE_TIMEOUT_SECS

MySQL/MariaDB 配置

要以只读模式使用 MySQL 或 MariaDB，请配置以下两种方式之一：

• 完整 URL：MYSQL_URL
• 组件模式：MYSQL_HOST、MYSQL_PORT（默认值为 3306）、MYSQL_USER、 MYSQL_PASSWORD、MYSQL_DATABASE

MySQL/MariaDB 连接池选项：

• MYSQL_MAX_CONNECTIONS
• MYSQL_ACQUIRE_TIMEOUT_SECS

多数据库后端选择

如需明确选择要启用的后端，请设置 DATAGATE_BACKEND：

• auto（默认）：优先级为 postgres -> mysql -> sqlite
• postgres
• mysql（或 mariadb）
• sqlite

当 DATAGATE_BACKEND 设置为特定后端时，DataGate 会要求提供相应的环境配置；否则会以明确的错误退出。

启动时的后端优先级：

1. PostgreSQL
2. MySQL/MariaDB
3. SQLite

列表中第一个已配置的后端会被启用。

可选的服务端速率限制使用 RATE_LIMIT_REQUESTS 和 RATE_LIMIT_WINDOW_SECS。限制会在策略、查询构建器和数据库之前按 request_id 应用；超出阈值的请求会收到 rate_limited，且不会生成 SQL。

查询构建器还会应用策略中可配置的最大预算 max_query_complexity：每列计 1，每个筛选条件计 2。超出预算的请求会在生成 SQL 之前被拒绝。

select 响应还受策略中的 max_output_bytes 限制：如果最终 JSON 载荷超出限制，DataGate 会以策略错误拒绝请求，且不会暴露 SQL 或内部细节。

指标层还会记录 select 工具的服务端计数器和延迟：请求总数/已接受数/已拒绝数、后端错误、内存中的 p95 延迟，以及 PostgreSQL 连接池快照（size、idle）。

应用日志支持两种格式：

• LOG_FORMAT=pretty（默认）
• LOG_FORMAT=json（结构化格式，适用于日志收集器）

最低日志级别可通过 LOG_LEVEL （trace|debug|info|warn|error）或 RUST_LOG 配置。

如果存在 DB_URL，则优先使用它，而不是各个组件。PostgreSQL 角色必须仅拥有读取权限；此外，每个连接都会设置 default_transaction_read_only = on。

通过 profile = "dev" 选择当前配置文件，并可在 [profiles.dev.policy] 中定义策略。如果没有命名配置文件，则仍支持旧格式 [policy]。声明了但不存在的配置文件会启用 deny-all 策略，且不会启动任何数据库操作。

发布的版本包含适用于 Linux x64/ARM64、Windows x64/ARM64 和 macOS Intel/Apple Silicon 的二进制文件，归档文件按平台命名，并提供 SHA256SUMS-* 文件以验证构建产物。

🛡️ 为什么选择 DataGate？

LLM 不应直接与数据库交互。 我们需要一个安全、可预测、受控、可审计、可扩展且支持多应用的层。DataGate 正是这样的层。

🔧 技术

• 语言：Rust
• 数据库：PostgreSQL、MySQL/MariaDB 和 SQLite（目前），未来支持其他数据库
• 协议：MCP (Model Context Protocol)
• 架构：异步、策略驱动、感知架构

🚀 项目状态

DataGate 正处于设计阶段。代码库包含初始结构、文档和技术路线图。

🧪 多后端集成测试

后端集成测试使用可选环境变量：

• DATAGATE_TEST_POSTGRES_URL
• DATAGATE_TEST_MYSQL_URL

设置某个变量后，相应测试会验证只读后端是否执行受控的 SELECT 并拒绝写入语句。 如果未设置变量，则会跳过测试，不会报错。

完整文档：

• Architecture.md — 设计原则和分层架构
• ROADMAP.md — 迈向 1.0 的详细路线图
• docs/configuration.md — 快速入门、后端、策略和操作
• docs/benchmarks.md — SQLite 本地基准测试和真实 PostgreSQL 基准测试
• docs/hardening.md — MCP/数据库边界的最终加固检查清单
• docs/http-transport-decision.md — MCP HTTP 远程传输的安全决策
• docs/editor-registry-evaluation.md — MCP Registry 要求和跨编辑器客户端评估
• docs/packaging.md — 打包渠道和制品的规范来源
• docs/postgres-mcp-comparison.md — 与其他 PostgreSQL MCP 服务的比较
• docs/registry-publication.md — MCP Registry 策略、跨编辑器安装和命名连接
• docs/mcp-registry-metadata.json — MCP 注册表/画廊候选元数据
• docs/release-candidate.md — 1.0 候选版本的标准和门槛
• docs/mcp-tools.md — MCP 工具的内部契约和规则
• CONTRIBUTING.md — 贡献、提交和分支规则
• SECURITY.md — 安全策略和漏洞报告

使用 MCP 从 VS Code 启动：

• 默认本地传输方式为 stdio
• 本地 stdio 的 mcp.json 模板位于 docs/mcp-tools.md 和 docs/configuration.md
• HTTP 远程传输不属于 1.0 默认配置，且需要单独的安全决策

📍 路线图（概要）

• 定义策略引擎
• 实现受控查询构建器（参数化 select）
• 确保连接只读
• 自动识别架构（PostgreSQL 内部目录）
• 审计日志基础功能（通过 AUDIT_LOG_PATH 写入 JSONL）
• MCP 工具（select、search、aggregate）
• 支持多种数据库（PostgreSQL、MySQL/MariaDB、SQLite）
• 初始企业级层（可观测性、加固、动态策略）
• 稳定 MCP API（版本化描述符；stdio 传输）
• MCP stdio 传输
• 基准测试
• 最终加固
• 1.0 候选版本

📄 许可证

Apache License 2.0