pgport

pgport

pgport 让 Agent（或在终端中的你）能够向 PostgreSQL 数据库提问，同时完全无法更改数据库。它接受连接字符串，运行一条只读查询，并返回 行。任何不是一条普通 SELECT 或 WITH ... SELECT 语句的内容，都会在离开进程前被拒绝；实际执行的语句则会在显式的只读事务中运行。

它不捆绑数据库驱动程序。pgport 在底层会调用 psql 命令行客户端，因此需要实时获取结果的机器必须在 PATH 中包含 psql。如果没有 psql，或没有连接字符串，服务仍会启动并列出其工具；只有查询 本身会报告问题。

安装

npx @reneturcios/pgport query postgres://user@localhost:5432/mydb "SELECT 1"

或者运行容器镜像：

docker run -i ghcr.io/cloudcorprecords/pgport

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

CLI

# Run one read-only query; rows print as JSON
pgport query postgres://alice@localhost/shop "SELECT id, name FROM products ORDER BY id"

# See what tables exist and which columns each one has
pgport schemas postgres://alice@localhost/shop

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

pgport --version

退出代码：成功时为 0；查询、连接字符串或 psql 本身失败时为 1（错误信息会指出原因）；用法错误时为 2。

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

只读防护

只有满足以下所有条件，查询才会被接受：

• 去除开头的空白和注释后，第一个关键字是 SELECT 或 WITH。
• 查询必须是单条语句：分号后只要还有非空白内容，就会终止处理。
• 字符串字面量之外不能出现 INSERT、UPDATE、DELETE、DROP、ALTER、CREATE、 TRUNCATE、GRANT、REVOKE、COPY 或 VACUUM 中的任何一个完整单词。扫描前会将单引号字面量清空，因此 SELECT 'delete me' 是完全有效的查询；但字面名称为 update 的列不行——防护机制宁可拒绝不常见的名称，也不会被绕过。

接受的查询会通过 psql -v ON_ERROR_STOP=1 --csv 执行为 BEGIN TRANSACTION READ ONLY; <sql>; COMMIT;，并将 CSV 输出解析为行对象。值会以 psql 输出的字符串形式返回。

MCP 服务

同一个可执行文件支持两种用法。mcp 子命令会启动 stdio MCP 服务：

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

MCP 客户端配置：

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

工具

工具	输入	返回内容
query	sql（字符串，必填）——一条只读 SQL 语句	结果行组成的 JSON 对象数组，每个对象以列名为键。防护规则违规、缺少连接、缺少 psql 以及数据库错误都会作为工具错误返回，绝不会伪造行数据。

在 MCP 层，服务刻意不掌握你的架构信息：例如，可以直接向数据库提问：SELECT table_name FROM information_schema.tables；也可以使用 CLI 的 schemas 命令，将 information_schema.columns 的行按表归类为列列表。

开发

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

核心逻辑位于可注入的执行器接口之后，测试套件会通过该接口进行测试：连接字符串解析、防护机制、查询透传、错误传播和架构分组，均由模拟执行器覆盖。

许可证

MIT——参见 LICENSE。