Skip to main content
Glama
daix1999

db-connector

by daix1999
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

db-connector

为 AI Agent 设计的可插拔数据库连接器，以 stdio MCP server 对外提供。评判标准不是"人写代码方便"，而是"agent 调用顺手"：接口自描述、跨方言统一、结果结构化、失败可据以决定下一步。

底层是两层抽象的 Python 库（连接器能力全开，读写皆支持），安全与权限全部收敛在使用层（MCP server）。

文档：架构 · 模板与插件 · 读写分离与分级授权 · 操作审计 · 配置与环境变量 · FAQ / 排障 · CHANGELOG

一分钟理解

  • 三层：BaseConnector（统一契约）→ templates/<数据模型>（把原生能力映射成通用探查）→ connectors/<方言>（只填原语的插件）。加一种库 = 选模板 + 写插件，底座不动。

  • 一个进程挂多源：MySQL + Redis + MongoDB 共存，工具用 source 参数路由；族专属工具会校验目标源方言。

  • 读写分离分级授权：读默认放行；写按每源 grant（read → read+data → read+schema → read+destructive）+ 库白/黑名单控制；超过免确认上限的操作返回一次性确认令牌，agent 带令牌二次调用才执行；管理员级命令恒拒。

  • 双边界审计：connector 层记真实落库操作（含库直调），mcp 层记 agent 意图与被拒/待确认的调用，默认脱敏。

Related MCP server: mcp-mysql-explorer

支持的数据模型

模型

模板

已实现方言

代表库

关系

RelationalConnector

mysql

PostgreSQL, SQL Server, Oracle, SQLite, TiDB

列式/OLAP

ColumnarConnector

模板

ClickHouse, Doris, StarRocks

键值

KeyValueConnector

redis

Memcached, etcd

文档

DocumentConnector

mongodb

CouchDB, DynamoDB

检索

SearchConnector

模板

Elasticsearch, OpenSearch

图

GraphConnector

模板

Neo4j, NebulaGraph

时序

TimeSeriesConnector

模板

InfluxDB, QuestDB

向量

VectorConnector

模板

Milvus, Qdrant, pgvector

加新方言：见 docs/templates-and-plugins.md。

安装

pip install -r requirements.txt        # 关系型核心 + MCP
pip install ".[redis,mongo,mcp]"       # 按需装可选方言

作为库用

from dbconnector import connect
with connect("mysql", host="127.0.0.1", user="root", password="...", database="test") as db:
    db.query("SELECT * FROM t WHERE id=%s", (1,))
    with db.transaction() as tx:            # 块内每条语句都进审计
        tx.execute("UPDATE t SET x=%s WHERE id=%s", (2, 1))

Redis / Mongo 同理：connect("redis", ...) / connect("mongodb", ...)。

作为 MCP server（agent 入口）

一个进程按 DB_SOURCES（JSON）挂多源；工具带 source 参数路由。

  • 通用（跨方言）：sources / health / list_sources / describe_source / get_source

  • 决策预演：analyze（执行前静态预演风险/授权判定/建议，与执行同源、不连库、不发令牌；CLI 版 scripts/ops_analyze.py）

  • 关系族：query（只读）/ execute（写，按授权）

  • 键值族：redis_get / redis_scan / redis_command

  • 文档族：mongo_find / mongo_count / mongo_aggregate / mongo_write

配置示例（一个进程挂多环境，每个 access 引用权限档或内联；两旋钮 grant+confirm_from）：

// DB_SOURCES
[
  {"name":"mysql8-prod","dialect":"mysql","host":"127.0.0.1","port":3306,"user":"app","password":"...","database":"biz","access":{"grant":"read+destructive","confirm_from":"read+data","write_deny":["audit_log"]}},
  {"name":"redis","dialect":"redis","host":"127.0.0.1","port":6379,"database":"0","access":"readonly"},
  {"name":"mongo","dialect":"mongodb","host":"127.0.0.1","port":27017,"database":"app","access":"readonly"}
]

常用环境变量（完整清单见 docs/configuration.md）：

变量

作用

DB_SOURCES / DB_ACCESS_PROFILE_FILE / DB_ACCESS_PROFILES

多源 / 权限档（文件优先加载、内联覆盖）

DB_DIALECT / DB_HOST / DB_PORT / DB_USER / DB_PASSWORD / DB_DATABASE / DB_DSN

单方言兼容配置（老写法）

DB_ALLOW_WRITE / DB_MAX_ROWS

全局兜底：写权限 / 单次行数上限

DB_AUDIT / DB_AUDIT_LAYER / DB_AUDIT_LOG / DB_AUDIT_PARAMS

审计：总开关 / 分层 / 路径 / 是否记参数值

DB_CONFIRM_SECRET / DB_CONFIRM_TTL

确认令牌密钥 / 有效期(秒)

权限完整写法见 docs/permissions.md，审计见 docs/audit.md。在 千问办公 / Claude / Cursor 注册：把 mcp_config.example.json 合并进 MCP 配置（千问办公不允许 agent 自动注册 stdio MCP，需手动粘贴）。

命令行工具

脚本

用途

scripts/ops_analyze.py

操作决策预演（静态：风险级/授权判定/预览/建议），与执行同源、不连库、不发令牌

scripts/ops_review.py

复盘审计日志（--level/--min-level/--source/--decision/--group-by/--html）

scripts/smoke_test.py

关系型建库 + 全链路冒烟

python scripts/ops_analyze.py --source mysql8-prod --sql "UPDATE t SET x=1"     # 预演这条会怎么判
python scripts/ops_review.py --min-level WRITE_DATA --html report.html          # 复盘写操作并导出报表

测试

python tests/test_offline.py                         # 注册表/配置/结果
python tests/test_guard.py && python tests/test_guard_nosql.py
python tests/test_acl.py                            # 根层分级授权(所有模板共用)
python tests/test_analyzer.py                       # 操作决策分析(静态卡/放行写也记决策)
python tests/test_config_profiles.py                # 权限档 profile/文件加载
python tests/test_ops_review.py                     # 操作复盘(按风险级过滤/聚合)
python tests/test_audit.py                            # 脱敏/成功/拒绝/事务逐条
python tests/test_permissions.py --user root --password ...   # 分级授权+确认流(需容器)
python tests/test_mcp_stdio.py --user root --password ...     # 关系型真实端到端
python scripts/smoke_test.py --user root --password ... --database test

版本与许可

当前版本见 dbconnector.__version__；完整变更记录见 CHANGELOG.md。1.x/2.x 均向后兼容（DBConnector 别名、nosql 垫片、allow_write 映射、allow_escalation/confirm_above 旧配置自动翻译）。许可证：MIT。

常见问题（节选）

  • 写被拒/被要求确认？ 看该环境 access：level>grant 拒绝，confirm_from≤level≤grant 需确认令牌。analyze 可预演。

  • agent 干的活怎么查？ logs/db-connector-audit.jsonl，用 ops_review.py 复盘（默认只看写决策）。

  • 放行没被改配的写也记吗？ 记。每条写都落 layer=decision（见 docs/audit.md）。

  • 更多见 docs/faq.md。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers

  • Workspace MCP Server

    sudenlee
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables AI agents to query MongoDB databases and project management REST APIs through a universal MCP interface, providing read-time access to workspace data.
    -

  • mcp-mysql-explorer

    xsg22
    A
    license
    Not graded
    quality
    D
    maintenance
    MCP server that connects AI agents to MySQL databases for schema exploration, data querying, and SQL execution via natural language.
    2
    MIT

  • anydb-mcp

    officialalexeev
    A
    license
    Not graded
    quality
    D
    maintenance
    Zero-config MCP server that empowers AI agents to safely query SQL and NoSQL databases like PostgreSQL, MySQL, SQLite, MongoDB, and Redis.
    16 npm
    1
    MIT

  • mcp-server-db

    Nam088
    A
    license
    B
    quality
    B
    maintenance
    A universal MCP server enabling AI assistants to query and manage six database engines (Postgres, Redis, Elasticsearch, MySQL, MongoDB, LDAP) through 113+ tools with read-only safety and fault tolerance.
    100
    25 npm
    82
    MIT