databridge-kit

databridge-kit

databridge-kit 是一个轻量级桥接工具，可连接 Agent（或终端）与一个已配置的 PostgreSQL 数据库。它可以执行一条 SQL 语句，并回答探索陌生数据库时经常会遇到的七个问题：有哪些表、视图、模式、触发器、索引、序列和存储过程。

这组工具与文档中预构建的、由配置定义的 Postgres 工具箱相对应：工具是固定的，连接字符串指向哪个数据库，就使用哪个数据库。项目不包含数据库驱动程序——语句通过 psql 命令行客户端执行，因此需要实时获取结果的机器必须在 PATH 中配置 psql。如果缺少 psql 或连接字符串，服务仍会启动并列出其工具；只有调用工具时才会报告问题。

安装

npx @reneturcios/databridge-kit list-tables postgres://user@localhost:5432/mydb

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/databridge-kit

容器默认启动 MCP 服务（见下文）。传入 CLI 参数即可将其用作 CLI。

CLI

# Run one SQL statement; rows print as JSON
databridge-kit execute-sql postgres://alice@localhost/shop "SELECT id, name FROM products ORDER BY id"

# Inspection commands; each prints its rows as JSON
databridge-kit list-tables postgres://alice@localhost/shop
databridge-kit list-views postgres://alice@localhost/shop
databridge-kit list-schemas postgres://alice@localhost/shop
databridge-kit list-triggers postgres://alice@localhost/shop
databridge-kit list-indexes postgres://alice@localhost/shop
databridge-kit list-sequences postgres://alice@localhost/shop
databridge-kit list-stored-procedures postgres://alice@localhost/shop

# Start the MCP server (connection string optional, see below)
databridge-kit mcp postgres://alice@localhost/shop

databridge-kit --version

退出码：成功时为 0；语句、连接字符串或 psql 本身出错时为 1（错误信息会说明具体原因）；用法错误时为 2。

连接字符串是标准的 PostgreSQL URL：postgres:// 或 postgresql://，包含主机、可选端口（默认值为 5432）、取自路径的数据库名称，以及用户信息中可选的用户名和密码。对于 mcp 命令，可以不在命令行中提供连接字符串，改为通过 DATABRIDGE_DATABASE_URL 环境变量传入（也可使用普通的 DATABASE_URL）。

语句和检查的工作方式

execute_sql 每次调用只接受一条语句。字符串字面量和注释中的分号不算语句分隔符，但如果存在第二条真正的语句，则会在任何内容到达数据库之前拒绝执行。不限制语句类型——这是一个通用桥接工具，因此能够访问它的调用方既可以写入，也可以读取；请只将其指向允许此类操作的数据库。

每个检查工具都会运行一条固定的目录查询：

工具	查询的目录
list_tables	information_schema.tables（基表）
list_views	information_schema.views
list_schemas	information_schema.schemata
list_triggers	information_schema.triggers
list_indexes	pg_indexes
list_sequences	information_schema.sequences
list_stored_procedure	information_schema.routines

语句通过 psql -v ON_ERROR_STOP=1 --csv -c <sql> 执行，并将 CSV 输出解析为行对象。返回的值是 psql 格式化后的字符串。

MCP 服务

同一个可执行文件提供两种使用方式。mcp 子命令会启动一个 stdio MCP 服务：

npx -y @reneturcios/databridge-kit mcp postgres://alice@localhost/shop

MCP 客户端配置：

{
  "mcpServers": {
    "databridge-kit": {
      "command": "npx",
      "args": ["-y", "@reneturcios/databridge-kit", "mcp"],
      "env": { "DATABRIDGE_DATABASE_URL": "postgres://alice@localhost/shop" }
    }
  }
}

工具

工具	输入	返回内容
execute_sql	sql（字符串，必填）——一条 SQL 语句	结果行组成的 JSON 数组，对象以列名为键。
list_tables	—	描述已配置数据源中基表的行。
list_views	—	描述已配置数据源中视图的行。
list_schemas	—	描述已配置数据源中模式的行。
list_triggers	—	描述已配置数据源中触发器的行。
list_indexes	—	描述已配置数据源中索引的行。
list_sequences	—	描述已配置数据源中序列的行。
list_stored_procedure	—	描述已配置数据源中存储过程（例程）的行。

连接缺失、psql 缺失、execute_sql 包含多条语句以及数据库错误，都会作为工具错误返回——绝不会伪造行数据。

开发

npm install
npm run build   # tsc -> dist/
npm test        # node test runner over test/*.test.ts, no network, no live database
npm run dev     # run the CLI from source via tsx

核心逻辑位于可注入的执行器接口之后，测试套件通过该接口进行测试：连接字符串解析、单语句检查、透传执行、错误传播，以及每个检查工具背后的准确目录 SQL，均由模拟执行器覆盖。

许可证

MIT — 详见 LICENSE。