使用说明

PostgreSQL MCP服务器

用于PostgreSQL数据库管理和分析的模型上下文协议（MCP）服务器。此服务器提供了用于探索数据库模式、执行查询、分析性能和监视数据库健康状况的全面工具。

安装

npm install -g postgres-mcp-server

或者直接使用npx运行：

npx postgres-mcp-server

配置

使用配置每个服务器 PG_* 环境变量。后缀(_1, _2, _DEV, _PROD，…）可以是任何字符串——服务器通过以下内容的存在来检测 PG_NAME_*.

PG_NAME_1="prod"
PG_HOST_1="prod.example.com"
PG_PORT_1="5432"
PG_USERNAME_1="user"
PG_PASSWORD_1="pass"
PG_DATABASE_1="mydb"
PG_SSL_1="true"
PG_DEFAULT_1="true"
PG_ACCESS_MODE_1="readonly"
PG_DB_ACCESS_MODES_1="analytics:full,staging:rw"

环境变量参考：

变量	必填	描述
`PG_NAME_{n}`	是	服务器名称（用于标识服务器）
`PG_HOST_{n}`	是	PostgreSQL服务器主机名
`PG_PORT_{n}`	否	端口号（默认值： `"5432"`)
`PG_USERNAME_{n}`	是	数据库用户名
`PG_PASSWORD_{n}`	否	数据库密码
`PG_DATABASE_{n}`	否	默认数据库（默认值： `"postgres"`)
`PG_SCHEMA_{n}`	否	默认架构（默认： `"public"`)
`PG_SSL_{n}`	否	SSL模式： `true`, `false`, `require`, `prefer`, `allow`, `disable`
`PG_DEFAULT_{n}`	否	设置为 `true` 使其成为启动时的默认服务器
`PG_CONTEXT_{n}`	否	此服务器的AI上下文/指导（见下文）
`PG_ACCESS_MODE_{n}`	否	服务器范围访问模式： `readonly` / `full` （覆盖 `POSTGRES_ACCESS_MODE`)
`PG_DB_ACCESS_MODES_{n}`	否	每个数据库访问模式覆盖： `dbname:mode,dbname:mode` （例如。 `analytics:full`)

服务器的AI上下文

PG_CONTEXT_{n} 为AI代理提供如何与每个服务器交互的指导。上下文在中返回 list_servers 和 get_current_connection 因此，AI代理可以相应地调整其行为。

PG_CONTEXT_DEV="Development environment. Safe to run any queries. Contains test data only."
PG_CONTEXT_STAGING="Staging with production-like data. Use LIMIT clauses. Avoid bulk operations."
PG_CONTEXT_PROD="PRODUCTION DATABASE - CRITICAL GUIDELINES:
- Read-only queries strongly preferred
- Always use LIMIT (max 1000 rows)
- Avoid full table scans on large tables (users, orders, events)
- Peak hours: 9am-5pm EST - minimize heavy queries
- Main schemas: 'app' (application data), 'analytics' (reporting)
- Contact DBA before any DDL operations"

访问模式配置

访问模式控制是否允许写入操作。按以下优先级在三个级别进行配置：

优先： 数据库级别>服务器级别>全局>默认(full)

# Global default for all servers (optional)
POSTGRES_ACCESS_MODE="readonly"   # full | readonly

# Server-level override (recommended for production)
PG_ACCESS_MODE_1="readonly"

# Per-database override (most specific). Format: dbname:mode,dbname:mode
PG_DB_ACCESS_MODES_1="production:readonly,analytics:full,staging:rw"

支持的值：

full / rw / readwrite --允许所有SQL操作
readonly / ro / read-only --只允许SELECT和read操作

克劳德代码CLI

claude mcp add-json postgres_dbs --scope user '{
  "command": "npx",
  "args": ["-y", "@tejasanik/postgres-mcp-server"],
  "env": {
    "PG_NAME_1": "prod",
    "PG_HOST_1": "prod.example.com",
    "PG_PORT_1": "5432",
    "PG_USERNAME_1": "user",
    "PG_PASSWORD_1": "pass",
    "PG_DATABASE_1": "mydb",
    "PG_SSL_1": "true",
    "PG_DEFAULT_1": "true",
    "PG_ACCESS_MODE_1": "readonly",
    "PG_DB_ACCESS_MODES_1": "analytics:full,staging:rw"
  }
}'

克劳德桌面版

添加 claude_desktop_config.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["@tejasanik/postgres-mcp-server"],
      "env": {
        "PG_NAME_1": "prod",
        "PG_HOST_1": "prod.example.com",
        "PG_PORT_1": "5432",
        "PG_USERNAME_1": "user",
        "PG_PASSWORD_1": "pass",
        "PG_DATABASE_1": "mydb",
        "PG_SSL_1": "true",
        "PG_DEFAULT_1": "true",
        "PG_ACCESS_MODE_1": "readonly",
        "PG_DB_ACCESS_MODES_1": "analytics:full,staging:rw"
      }
    }
  }
}

Codex CLI

添加 ~/.codex/config.toml:

[mcp_servers.postgres]
command = "npx"
args = ["-y", "@tejasanik/postgres-mcp-server"]

[mcp_servers.postgres.env]
PG_NAME_1 = "prod"
PG_HOST_1 = "prod.example.com"
PG_PORT_1 = "5432"
PG_USERNAME_1 = "user"
PG_PASSWORD_1 = "pass"
PG_DATABASE_1 = "mydb"
PG_SSL_1 = "true"
PG_DEFAULT_1 = "true"
PG_ACCESS_MODE_1 = "readonly"
PG_DB_ACCESS_MODES_1 = "analytics:full,staging:rw"

可用工具

服务器和数据库管理

`list_servers`

列出所有已配置的PostgreSQL服务器。返回服务器名称、主机、端口和连接状态。首先使用此功能发现可用服务器。

参数：

filter （可选）：按名称或主机筛选服务器（不区分大小写的部分匹配）

退货：

servers：服务器信息数组（名称、isConnected、isDefault、defaultDatabase、defaultSchema）
currentServer：当前连接的服务器名称（或空）
currentDatabase：当前连接的数据库（或空）
currentSchema：当前架构（或null）

注：为了安全起见，主机和端口被故意隐藏在响应之外。

`list_databases`

列出特定PostgreSQL服务器中的数据库。始终提供服务器名称以避免混淆。

参数：

serverName （必需）：要从中列出数据库的服务器的名称。使用 list_servers 查看可用服务器。
filter （可选）：按名称筛选数据库（不区分大小写的部分匹配）
includeSystemDbs （可选）：包括系统数据库（template0、template1）。默认值：false
maxResults （可选）：要返回的最大数据库数（默认值：50，最大值：200）

退货：

serverName：查询的服务器名称
databases：数据库信息数组（名称、所有者、编码、大小）
currentDatabase：此服务器上当前连接的数据库（或为空）

`switch_server_db`

切换到不同的PostgreSQL服务器，并可选地切换到特定的数据库和模式。

参数：

server （必填）：要连接的服务器的名称
database （可选）：要连接的数据库的名称（使用服务器的defaultDatabase或“postgres”）
schema （可选）：要使用的默认架构（使用服务器的defaultSchema或“public”）

退货：

success：切换是否成功
message：成功消息
currentServer：连接的服务器的名称
currentDatabase：连接的数据库的名称
currentSchema：当前架构的名称
context：（如果已配置）连接服务器的AI上下文/指导

`get_current_connection`

返回当前数据库连接的详细信息，包括服务器、数据库、模式、访问模式、用户和AI上下文。

参数： 无

退货：

isConnected：当前是否连接到数据库
server：当前服务器名称
database：当前数据库名称
schema：当前架构名称
accessMode：“只读”或“满”
user：当前连接的数据库用户名
context：（如果已配置）当前服务器的AI上下文/指导

模式和对象探索

`list_schemas`

列出当前PostgreSQL数据库中的所有数据库模式。

参数：

includeSystemSchemas （可选）：包括系统架构
server, database, schema （可选）：一次性连接覆盖

`list_objects`

列出指定架构中的数据库对象。

参数：

schema （必需）：用于列出对象的架构名称
objectType （可选）：要列出的对象类型（表、视图、序列、扩展名、全部）
filter （可选）：按名称筛选对象
server, database, targetSchema （可选）：一次性连接覆盖

`get_object_details`

提供有关数据库对象的详细信息，包括列、约束、索引、大小和行数。自动检测目标是表、视图、物化视图还是序列，并相应地调整响应。退货 exists: false 在找不到物体的早期。

参数：

schema （必需）：包含对象的架构名称
objectName （必填）：对象名称
objectType （可选）：对象的类型(table, view, matview, sequence, extension).自动检测自 pg_class.relkind 当省略时。
server, database, targetSchema （可选）：一次性连接覆盖

退货（因检测到的种类而异）：

exists：是否找到了该对象。
detectedKind：检测到的实际类型(table / view / matview / sequence).
columns, constraints （包括。 check_clause 用于检查约束）， indexes, size, rowCount：关系。
definition：用于视图和物化视图。
sequenceDetails：用于序列（开始、最小/最大、缓存、最后一个值）。

`describe_table`

v3单调用表摘要。 取代~5呼叫舞蹈 get_object_details + COUNT(*) + LIMIT 5 + pg_stats.返回列（带空%，与pg_stats的比率不同）、主键、输出的外键（此表→ 其他），外键传入（其他→ 此表）、所有具有定义的索引、表大小、行数估计值和行样本。

参数：

table （必需）：不合格的表名。
schema （可选）：默认值 'public'.
sample_size （可选）：要获取的样本行数（默认值为5；0表示跳过）。
profile_columns （可选）：要分析的列（默认值：最多20列）。
server, database, override_schema （可选）：一次性连接覆盖。

`find_dependents`

漫步 pg_depend 递归地查找依赖于目标的每个数据库对象——视图、外键、函数、物化视图、索引、规则。 使用前 DROP CASCADE 了解爆炸半径。每个受抚养人都会被送回公寓 depth 从目标（1=直接，2=取决于深度-1，…）。集合 truncatedAtDepth: true 如果达到递归极限。

参数：

name （必填）：对象名称。
kind （可选）： table/view/matview/sequence/index/function/procedure/type/extension/schema （默认值 table).
schema （可选）：默认值 'public'.
max_depth （可选）：递归限制（1-10，默认值5）。
server, database, override_schema （可选）：一次性连接覆盖。

查询执行

`execute_sql`

在数据库上执行SQL语句。支持分页和参数化查询。只读模式阻止写入操作。

参数：

sql （必需）：要执行的SQL语句。使用 $1, $2等等，用于参数化查询。
params （可选）：用于参数化查询的参数数组（例如。， [123, "value"]).防止SQL注入。不支持 allowMultipleStatements.
maxRows （可选）：返回的最大行数（默认值：1000，最大值：100000）。与...一起使用 offset 用于分页。
offset （可选）：分页时要跳过的行数（默认值：0）。
allowLargeScript （可选）：设置为true可绕过部署脚本的100KB SQL长度限制。
includeSchemaHint （可选）：包括查询中引用的表的架构信息（列、主键、外键）。
allowMultipleStatements （可选）：允许多个用分号分隔的SQL语句。返回每个带行号的语句的结果。
transactionId （可选）：在活动事务中执行。从以下地址获取此信息 begin_transaction.
maxEstimatedRows （可选）：查询预算飞行前检查。如果计划器估计的行数超过此值，则查询将被拒绝而不执行。仅适用于SELECT。
maxEstimatedCost （可选）：查询预算飞行前检查。如果计划员估计的成本高于此，则查询将被拒绝而不执行。仅适用于SELECT。
server, database, schema （可选）：一次性连接覆盖。在不更改主连接的情况下，在其他服务器/数据库/架构上执行。不能与一起使用 transactionId.

退货：

rows：结果行（分页）
rowCount：结果中的总行数
fields：列名
executionTimeMs：查询执行时间（毫秒）
offset：当前偏移
hasMore：是否有更多行可用
outputFile：（仅当输出太大时）具有完整结果的临时文件的路径
schemaHint：（当includeSchemaHint=true时）引用表的架构信息：
- tables：包含列、主键、外键和行数估计值的表模式数组

注：大输出会自动写入临时文件，并返回文件路径。这可以防止在处理大型结果集时出现令牌浪费。

`execute_sql_file`

执行a .sql 文件系统中的文件。可用于运行迁移脚本、模式更改或数据导入。支持来自Liquibase、Flyway和SQL Server迁移等各种工具的SQL文件。

参数：

filePath （必填）：绝对或相对路径 .sql 要执行的文件
useTransaction （可选）：将执行包裹在事务中（默认值：true）。如果任何语句失败，所有更改都将回滚。
stopOnError （可选）：在第一个错误时停止执行（默认值：true）。如果为false，则继续处理其余语句并收集所有错误。
stripPatterns （可选）：在执行之前从SQL中删除的模式数组。可用于剥离工具特定的分隔符（例如Liquibase的 /，SQL Server的 GO).
stripAsRegex （可选）：如果为真，则处理 stripPatterns 作为正则表达式；如果为false，则作为文本字符串（默认值：false）。
validateOnly （可选）：如果为true，则解析并验证文件而不执行（默认值：false）。返回所有语句的预览。

退货：

success：是否所有语句都已成功执行
filePath：已解析的文件路径
fileSize：文件大小（字节）
totalStatements：文件中的可执行语句总数
statementsExecuted：成功执行的语句数
statementsFailed：失败语句的数量
executionTimeMs：总执行时间（毫秒）
rowsAffected：受所有语句影响的行总数
errors：（当stopOnError=false时）错误详细信息数组：
- statementIndex：哪个语句失败（从1开始）
- sql：失败的SQL（截断为200个字符）
- error：错误消息
rollback：是否执行了回滚
validateOnly：（当validateOnly=true时）设置为true
preview：（当validateOnly=true时）语句数组预览：
- index：报表索引（从1开始）
- lineNumber：文件中的行号
- sql：SQL语句（截断为200个字符）
- type：检测到的语句类型（SELECT、INSERT、UPDATE、DELETE、CREATE等）

限制： 最大文件大小：50MB。支持PostgreSQL特定的语法，包括美元引号字符串和块注释。

示例：

# Preview a file without executing
execute_sql_file({ filePath: "/path/to/migration.sql", validateOnly: true })

# Strip Liquibase delimiters (literal "/" on its own line)
execute_sql_file({ filePath: "/path/to/liquibase.sql", stripPatterns: ["/"] })

# Strip SQL Server GO statements (regex pattern)
execute_sql_file({
  filePath: "/path/to/sqlserver.sql",
  stripPatterns: ["^\\s*GO\\s*$"],
  stripAsRegex: true
})

# Strip multiple patterns
execute_sql_file({
  filePath: "/path/to/migration.sql",
  stripPatterns: ["/", "GO", "\\"]
})

`preview_sql_file`

预览SQL文件而不执行它。类似于 mutation_preview 但对于SQL文件。按类型显示语句计数，并显示潜在危险操作的警告。以前用这个 execute_sql_file 了解迁移会带来什么。

参数：

filePath （必填）：绝对或相对路径 .sql 要预览的文件
stripPatterns （可选）：在解析之前从SQL中剥离的模式（与execute_SQL_file相同）
stripAsRegex （可选）：如果为true，则将模式视为正则表达式（默认值：false）
maxStatements （可选）：预览中显示的最大语句数（默认值：20，最大值：100）

退货：

filePath：已解析的文件路径
fileSize：文件大小（字节）
fileSizeFormatted：人类可读的文件大小（例如，“15.2KB”）
totalStatements：文件中的可执行语句总数
statementsByType：按语句类型细分（例如。， { "CREATE": 5, "INSERT": 10, "ALTER": 2 })
statements：语句预览数组（最多maxStatements）：
- index：报表编号（从1开始）
- lineNumber：文件中的行号
- sql：SQL语句（截断为300个字符）
- type：语句类型（SELECT、INSERT、CREATE等）
warnings：一系列危险操作警告：
- DROP语句
- TRUNCATE声明
- 不带WHERE子句的DELETE/UPDATE
summary：人类可读的摘要（例如，“文件包含17条语句：10条INSERT，5条CREATE，2条ALTER”）

例子：

preview_sql_file({ filePath: "/path/to/migration.sql" })
// Returns:
// {
//   "filePath": "/path/to/migration.sql",
//   "fileSize": 15234,
//   "fileSizeFormatted": "14.9 KB",
//   "totalStatements": 17,
//   "statementsByType": { "CREATE": 5, "INSERT": 10, "ALTER": 2 },
//   "statements": [...],
//   "warnings": ["Statement 15 (line 142): DROP statement detected - will permanently remove database object"],
//   "summary": "File contains 17 statements: 10 INSERT, 5 CREATE, 2 ALTER"
// }

`mutation_preview`

预览INSERT、UPDATE或DELETE语句的效果，而无需执行它们。显示受影响的估计行和将被修改的行示例。对于在运行破坏性查询之前验证它们至关重要。

参数：

sql （必需）：要预览的INSERT、UPDATE或DELETE语句
sampleSize （可选）：要显示的样本行数（默认值：5，最大值：20）

退货：

mutationType：突变类型（插入、更新、删除）
estimatedRowsAffected：预计受影响的行数
sampleAffectedRows：将被修改的行示例（用于UPDATE/DELETE）
targetTable：表格正在修改中
whereClause：查询中的WHERE子句（如果存在）
warning：如果没有WHERE子句（所有行都受影响）或用于INSERT预览，则显示警告消息

例子：

mutation_preview({ sql: "DELETE FROM orders WHERE status = 'cancelled'" })
// Returns: { mutationType: "DELETE", estimatedRowsAffected: 150, sampleAffectedRows: [...5 rows...] }

`mutation_dry_run`

基于交易的突变模拟。 在事务中实际执行INSERT/UPDATE/DELETE，捕获真实结果，然后回滚，这样就不会有任何结果。比 mutation_preview 因为它捕获了实际的约束违规、触发效果和确切的行数。

不可回滚操作： 包含明确内容的声明 NEXTVAL() 或 SETVAL() 是跳过以防止序列值被永久消耗。对于跳过的语句 EXPLAIN 而是提供查询计划。

参数：

sql （必需）：用于模拟运行的INSERT、UPDATE或DELETE语句
sampleSize （可选）：要返回的样本行数（默认值：10，最大值：20）

退货：

mutationType：突变类型（插入、更新、删除）
success：试运行是否成功执行
skipped：如果 true，语句被跳过（包含不可回滚的操作）
skipReason：为什么跳过声明
rowsAffected: 实际受影响的行数
beforeRows：更改前的行示例（用于UPDATE/DELETE）
affectedRows：更改后的行示例（用于INSERT/UPDATE）或已删除的行
targetTable：表格正在修改中
whereClause：WHERE子句（如果存在）
executionTimeMs：执行时间（毫秒）
error：如果失败，请提供详细的PostgreSQL错误信息：
- message：错误消息
- code：PostgreSQL错误代码（例如，'23505'表示唯一违规）
- detail：详细的错误描述
- hint：修复错误的提示
- constraint：导致错误的约束名称
- table, column, schema：相关数据库对象
nonRollbackableWarnings：关于副作用的警告：
- operation：操作类型（序列、真空等）
- message：警告信息
- mustSkip：如果 true，跳过操作；如果 false，只是一个警告
warnings：一般警告（例如，没有WHERE子句）
explainPlan：从EXPLAIN查询计划（用于跳过NEXTVAL/SETVAL的DML语句）

例子：

mutation_dry_run({ sql: "INSERT INTO users (email) VALUES ('test@test.com')" })
// On success: { success: true, mutationType: "INSERT", rowsAffected: 1, affectedRows: [{id: 5, email: "test@test.com"}] }
// On failure: { success: false, error: { code: "23505", constraint: "users_email_key", detail: "Key already exists" } }

// With explicit NEXTVAL (skipped):
mutation_dry_run({ sql: "INSERT INTO users (id) VALUES (nextval('users_id_seq'))" })
// Returns: { success: true, skipped: true, skipReason: "NEXTVAL increments sequence...", explainPlan: [...] }

`dry_run_sql_file`

基于事务的SQL文件模拟运行。 实际执行事务中的所有语句，捕获真实每个语句的结果（行数、行号错误、违反约束），然后进行ROLLBACK，这样就不会出现任何问题。非常适合在部署前测试迁移。

不可回滚操作： 以下操作将自动执行跳过（未执行）：

真空、集群、再索引同时进行：无法在事务中运行
同时创建索引：无法在事务中运行
创建/删除数据库：无法在事务中运行
NEXTVAL（）、SETVAL（）：将永久消耗序列值

对于跳过的DML语句（插入/更新/删除/选择NEXTVAL/SETVAL） EXPLAIN 提供了查询计划，因此您仍然可以看到查询会做什么。

参数：

filePath （必填）：绝对或相对路径 .sql 文件
stripPatterns （可选）：在执行之前从SQL中剥离的模式（例如。， ["/"] Liquibase）
stripAsRegex （可选）：如果为true，则将模式视为正则表达式（默认值：false）
maxStatements （可选）：结果中包含的最大语句数（默认值：50，最大值：200）
stopOnError （可选）：在第一个错误时停止（默认值：false-继续显示所有错误）

退货：

success：是否所有语句都成功执行（跳过的语句不算作失败）
filePath：已解析的文件路径
fileSize：文件大小（字节）
fileSizeFormatted：人类可读的文件大小
totalStatements：文件中的报表总数
successCount：成功发言的次数
failureCount：失败语句的数量
skippedCount：跳过的语句数（不可回滚的操作）
totalRowsAffected：所有语句中受影响的行总数
statementsByType：按语句类型细分（例如。， {"CREATE": 5, "INSERT": 10})
executionTimeMs：总执行时间
statementResults：每条语句的结果数组：
- index：报表编号（从1开始）
- lineNumber：文件中的行号
- sql：SQL语句（截断）
- type：语句类型（SELECT、INSERT、CREATE等）
- success：语句是否成功
- skipped：如果 true，语句被跳过（不可回滚操作）
- skipReason：为什么跳过声明
- rowCount：受影响/返回的行
- rows：示例行（用于选择或返回）
- executionTimeMs：语句执行时间
- error：如果失败，则显示详细的PostgreSQL错误（字段与 mutation_dry_run)
- warnings：此声明的警告
- explainPlan：从EXPLAIN查询计划（用于跳过的DML语句）
nonRollbackableWarnings：有关无法完全回滚的操作的警告：
- operation：类型（序列、真空、集群等）
- message：警告信息
- mustSkip：如果 true，跳过操作；如果 false，只是一个警告
- statementIndex, lineNumber：文件中的位置
summary：人类可读摘要
rolledBack：始终 true -确认更改已回滚

例子：

dry_run_sql_file({ filePath: "/path/to/migration.sql", stripPatterns: ["/"] })
// Returns:
// {
//   "success": false,
//   "totalStatements": 15,
//   "successCount": 12,
//   "failureCount": 2,
//   "skippedCount": 1,
//   "statementResults": [
//     { "index": 1, "lineNumber": 1, "type": "CREATE", "success": true },
//     { "index": 5, "lineNumber": 23, "type": "INSERT", "success": false,
//       "error": { "code": "23505", "constraint": "users_pkey", "detail": "Key already exists" } },
//     { "index": 8, "lineNumber": 45, "type": "SELECT", "success": true, "skipped": true,
//       "skipReason": "NEXTVAL increments sequence...", "explainPlan": [...] },
//     ...
//   ],
//   "nonRollbackableWarnings": [
//     { "operation": "SEQUENCE", "message": "INSERT may consume sequence values...", "mustSkip": false },
//     { "operation": "SEQUENCE", "message": "NEXTVAL increments sequence...", "mustSkip": true }
//   ],
//   "summary": "Dry-run of 15 statements: 12 succeeded, 2 failed, 1 skipped (non-rollbackable). All changes rolled back.",
//   "rolledBack": true
// }

何时使用 dry_run_sql_file 对比 preview_sql_file:

特点	`preview_sql_file`	`dry_run_sql_file`
速度	快（仅解析）	慢（实际执行）
检测语法错误	基本	PostgreSQL实际错误
检测约束违规	否	是
检测触发效应	否	是
准确的行数	否（估计值）	是（实际）
显示错误详细信息	否	是（代码、约束、提示）
消耗序列	否	否（跳过NEXTVAL/SETVAL）
显示跳过操作的查询计划	不适用	是（解释）

`batch_execute`

并行执行多个SQL查询。返回按查询名称键入的所有结果。在一次调用中高效地获取多个独立的数据。

参数：

queries （必填）：要执行的查询数组（最多20个）：
- name：此查询的唯一名称（用作结果中的关键字）
- sql：要执行的SQL查询
- params （可选）：查询参数
stopOnError （可选）：在第一个错误时停止（默认值：false，继续所有查询）

退货：

totalQueries：批处理中的查询总数
successCount：成功查询的次数
failureCount：失败的查询数
totalExecutionTimeMs：总执行时间（毫秒）
results：查询结果按名称键入的对象：
- success：查询是否成功
- rows：结果行（如果成功）
- rowCount：返回的行数
- error：错误消息（如果失败）
- executionTimeMs：单个查询执行时间

例子：

batch_execute({
  queries: [
    { name: "user_count", sql: "SELECT COUNT(*) FROM users" },
    { name: "order_total", sql: "SELECT SUM(total) FROM orders" },
    { name: "recent_signups", sql: "SELECT COUNT(*) FROM users WHERE created_at > NOW() - INTERVAL '7 days'" }
  ]
})
// Returns all three results in parallel, keyed by name

交易控制

`begin_transaction`

启动一个新的数据库事务。返回与一起使用的transactionId execute_sql, commit_transaction，或 rollback_transaction.

参数： 无

退货：

transactionId：此交易的唯一ID
status：“已开始”
message：交易使用说明

`commit_transaction`

提交一个活动事务，使所有更改永久化。

参数：

transactionId （必填）：返回的交易ID begin_transaction

`rollback_transaction`

回滚活动事务，撤消其中所做的所有更改。

参数：

transactionId （必填）：返回的交易ID begin_transaction

示例-交易用途：

1. Call begin_transaction to get a transactionId
2. Call execute_sql with transactionId for each statement
3. Call commit_transaction to save changes, OR rollback_transaction to undo

`explain_query`

获取SQL查询的执行计划。

参数：

sql （必填）：SQL查询说明
analyze （可选）：执行查询以获取实时时间
buffers （可选）：包括缓冲区使用统计信息
format （可选）：输出格式（文本、json、yaml、xml）
hypotheticalIndexes （可选）：模拟索引（需要hypg扩展）
server, database, schema （可选）：一次性连接覆盖（见下文）

连接覆盖（一次性执行）

大多数查询执行工具支持 一次性连接覆盖 允许在不改变主连接的情况下在不同的服务器/数据库/模式上执行查询的参数。这有助于：

在单个工作流中查询多个数据库
对副本运行读取查询，同时保持与主副本的主连接
比较不同服务器之间的模式

支持的工具： execute_sql, explain_query, list_schemas, list_objects, get_object_details, describe_table, find_dependents, execute_sql_file, mutation_preview, mutation_dry_run, dry_run_sql_file, batch_execute, lock_check, detect_migration_state, column_profile, generate_seed_data, find_blocking_queries, kill_query, export_to_sql_file

替代参数：

server （可选）：在此服务器上执行，而不是在当前服务器上执行
database （可选）：在此数据库上执行，而不是在当前数据库上执行
schema （可选）：仅为此执行将search_path设置为此架构

重要提示：

查询完成后，主连接保持不变
连接覆盖不能用于事务(transactionId)
覆盖连接使用单独的连接池，并驱逐LRU
最多10个缓存覆盖池，每个池限制为2个连接
所有池的总连接数限制为50

示例：

# Query another database without switching
execute_sql({
  sql: "SELECT * FROM users LIMIT 10",
  database: "analytics_db"
})

# Query a different server entirely
execute_sql({
  sql: "SELECT COUNT(*) FROM orders",
  server: "reporting",
  database: "warehouse"
})

# List schemas on a different server
list_schemas({
  server: "production",
  database: "myapp"
})

# Compare table structure across environments
get_object_details({
  schema: "public",
  objectName: "users",
  server: "staging"
})

连接池管理：

覆盖连接得到有效管理：

池被缓存并重复用于对同一服务器/数据库的重复查询
当达到限制（10）时，LRU驱逐会删除最旧的池
每次查询后都会正确释放连接
全局连接限制可防止资源耗尽

性能分析

`get_top_queries`

根据执行时间报告最慢的SQL查询。

参数：

limit （可选）：要返回的查询数（默认值：10）
orderBy （可选）：按total_time、mean_time或调用排序
minCalls （可选）：要包含的最小呼叫数

要求： pg_stat_statements 扩展

`analyze_workload_indexes`

分析数据库工作负载并推荐最佳索引。

参数：

topQueriesCount （可选）：要分析的顶级查询数
includeHypothetical （可选）：包括假设指数分析

`analyze_query_indexes`

分析特定的SQL查询并推荐索引。

参数：

queries （必填）：要分析的SQL查询数组（最多10个）

DDL安全与迁移

`lock_check`

对SQL语句进行静态分析，以确定它所需的PostgreSQL锁级别，是否强制重写整个表，以及基于目标表当前大小的估计持续时间。了解锁的语义 ALTER TABLE 变体， CREATE/DROP INDEX （并发vs非并发）， VACUUM, CLUSTER, REFRESH MATERIALIZED VIEW以及更多。返回以下警告 ACCESS EXCLUSIVE 锁定繁忙的生产表和具体建议（例如，使用 CREATE INDEX CONCURRENTLY, NOT VALID + VALIDATE CONSTRAINT等等）。

参数：

sql （必填）：要分析的DDL语句。
estimate_duration （可选）：查找目标表大小以估计持续时间。默认 true.
server, database, schema （可选）：一次性连接覆盖。

`safe_alter_table`

转换高级意图将其转化为多步骤零停机DDL配方。每个步骤都有自己的SQL、预期的锁级别和注释。用管道输送结果 scriptSql 通过 dry_run_sql_file 进行验证，然后通过 execute_sql_file({ useTransaction: false }) 用于生产推广(CONCURRENTLY 操作不能在事务内运行）。

支持的意图：

add_not_null_column_with_default --在翻转NOT NULL之前进行回填。
add_not_null — NOT VALID 然后 VALIDATE CONSTRAINT.
add_foreign_key — NOT VALID 然后 VALIDATE.
add_check — NOT VALID 然后 VALIDATE.
create_index — CREATE INDEX CONCURRENTLY （采用分配指数法： btree / hash / gist / spgist / gin / brin).
drop_index — DROP INDEX CONCURRENTLY.

参数：

intent （必填）： { kind, ... } --请参阅上面的意图列表。

`detect_migration_state`

在数据库中查找迁移工具跟踪表（Liquibase、Flyway、Alembic、Prisma、Knex、Sequelize、Django、Rails、Goose、TypeORM）。返回检测到的工具、保存其状态的模式和表、应用的迁移计数以及最新版本。使用此第一在建议更改之前，了解数据库是否由迁移工具管理。

参数：

schemas （可选）：要探测的模式（默认：所有非系统模式）。
server, database, schema （可选）：一次性连接覆盖。

跨数据库操作

`export_to_sql_file`

将模式（DDL）和/或数据从连接的数据库导出到 .sql 文件。标头横幅记录时间戳和源服务器别名（隐藏主机/端口）。以前用这个 transfer_objects 或者用于生成迁移脚本。

参数：

filePath （必填）：通往 .sql 文件。必须以结尾 .sql.
mode （可选）： 'append' （默认--用分隔条保留现有内容）或 'overwrite'.
what （必填）：以下之一：
- { kind: 'objects', objects: [{ kind, name, schema? }, ...] } --显式列表的DDL，按依赖关系进行拓扑排序。
- { kind: 'data', tables, where?, orderBy?, limit? } --表的INSERT语句。
- { kind: 'schema_dump', schema?, include_data? } --完整模式，可选数据。
- { kind: 'query_result', sql, target_table } --SELECT结果作为INSERTs发送到目标表中。
confirm_overwrite （可选）：当 mode='overwrite' 文件在60秒前被修改，set true 以确认。脚枪防护装置。
server, database, schema （可选）：一次性连接覆盖。

`transfer_objects`

将DDL和/或数据从一个配置的服务器/数据库传输到另一个（同一服务器、不同的数据库或完全远程）。两个端点都必须配置为服务器(PG_NAME_*)；不接受ad-hoc连接字符串（安全）。如果目标的有效访问模式为 readonly表之间的FK约束以如下形式发出 ALTER TABLE 在表后附加语句以处理表间依赖循环。

参数：

from, to （必填）： { server, database?, schema? } 源和目标端点。
objects （必填）： '*' （源架构中的所有对象）或数组 { kind, name, schema? }.
include （可选）： 'ddl' / 'data' / 'both' （默认）。
if_exists （可选）： 'skip' / 'replace' / 'error' （默认--快速失败）。
dry_run （可选）：生成SQL而不应用。与...一起使用 output_file.
output_file （可选）：写入生成的SQL的路径 dry_run: true.

`schema_diff`

计算两个值之间的DDL增量 { server, database, schema } 端点。将对象返回给创建（在源而非目标中），丢弃（目标而非来源），以及修改（两者都有，但DDL不同），加上一个 migrationSql 脚本将目标随着来源来源是真理的来源。

参数：

source, target （必填）： { server, database?, schema? }.

数据生成和分析

`column_profile`

每列单遍配置文件：空%、不同计数、带频率的前K个值、最小值/最大值和类型感知统计数据（数值为avg/stddev，文本为长度分布，时间为范围）。用途 TABLESAMPLE BERNOULLI 对于大于的桌子 sample_threshold （默认1M行）以限制延迟。

参数：

table （必填）， schema （可选，默认 'public').
columns （可选）：要分析的特定列（默认值：最多30列）。
sample_percent （可选）：默认值 10.
sample_threshold （可选）：默认值 1_000_000 排。
top_k （可选）：每列的Top-K值（默认值 10，最大值 25).
server, database, override_schema （可选）：一次性连接覆盖。

`generate_seed_data`

为表生成模式感知的假种子数据。尊重 NOT NULL, UNIQUE/PK（带冲突后缀的重试）、枚举类型（循环标签）、默认值、文本长度限制和FK列（跳过或填充——由调用者选择）。为数值、文本、布尔值、uuid、日期/时间戳、bytea、JSON、inet、cidr、macaddr生成类型适当的值。

参数：

table （必填）， schema （可选，默认 'public').
count （必填）：1至100000。
column_values （可选）：每列SQL值覆盖，例如。 { country: "'US'", priority: '1' }.引用为PG文字。
skip_fks （可选）：默认值 false.
apply （可选）：直接应用于数据库（默认 true)或仅返回SQL(false).
server, database, override_schema （可选）：一次性连接覆盖。

操作工具

`find_blocking_queries`

在友好树中显示当前阻止的会话（拦截器→ 阻塞）使用 pg_stat_activity ⨝ pg_blocking_pids()。返回每个会话的pid、用户、数据库、应用程序名称、状态、当前查询、状态时间，以及 wait_event。用于诊断减速并选择候选对象 kill_query.

参数：

include_idle （可选）：默认值 true.
limit （可选）：默认值 50.
server, database, schema （可选）：一次性连接覆盖。

`kill_query`

通过PID取消或终止后端会话。在发出信号之前返回目标会话的快照。

参数：

pid （必填）：后端PID发出信号。
mode （必填）： 'cancel' （柔软-- pg_cancel_backend，中断当前语句）或 'terminate' （硬-- pg_terminate_backend，杀死整个后端）。
confirm （必填）：必须 true脚枪防护装置。
server, database, schema （可选）：一次性连接覆盖。

注：如果目标服务器的有效访问模式为 readonly.

健康监测

`analyze_db_health`

执行全面的数据库健康检查，包括：

缓冲区缓存命中率：检查缓存效率
连接健康状况：监控连接使用情况
无效索引：检测损坏的索引
未使用的索引：标识未使用的索引
重复索引：查找冗余索引
真空健康：监视死元组比率
序列限制：警告序列接近极限
约束验证：检查未验证的约束

用法示例

连接到服务器并列出数据库

1. Use list_servers to see available servers
2. Use list_databases with serverName="dev" to see databases in the dev server
3. Use switch_server_db with server="dev", database="myapp" to connect

探索数据库架构

1. Use list_schemas to see all schemas
2. Use list_objects with schema="public" to see tables
3. Use get_object_details with schema="public", objectName="users" to see table structure

分析查询性能

1. Use explain_query with your SQL to see the execution plan
2. Use get_top_queries to find slow queries
3. Use analyze_query_indexes to get index recommendations

健康检查

1. Use analyze_db_health to run all health checks
2. Review warnings and critical issues
3. Take action on recommendations

执行SQL迁移文件

1. Use execute_sql_file with filePath="/path/to/migration.sql"
2. By default, runs in a transaction - all changes rolled back on error
3. Set stopOnError=false to continue on errors and get a full report
4. Set useTransaction=false for DDL statements that can't run in transactions

特性

连接错误时自动重新连接

服务器会自动处理过时的数据库连接。当发生连接错误时（例如，服务器处于非活动状态、连接重置、超时），服务器将：

检测连接错误
使过时的连接无效
使用存储的服务器/数据库/架构自动重新连接
请重试该操作一次

这对于以下情况特别有用：

闲置的暂存/开发服务器
连接超时的云数据库
网络中断

支持的错误模式包括： Connection terminated, ECONNRESET, ETIMEDOUT, server closed the connection unexpectedly，以及PostgreSQL错误代码，如 57P01 （admin_shutdown）， 08003 （connection_does_not_exist）等。

隐藏连接详细信息

主机URL、端口和凭据永远不会在工具响应中公开。只有服务器名称（别名）可见，防止意外暴露基础设施详细信息。

响应中的连接上下文

所有工具响应都包括 connection 显示操作在哪个服务器、数据库和架构上运行的对象：

{
  "rows": [...],
  "connection": {
    "server": "production",
    "database": "myapp",
    "schema": "public"
  }
}

多语句执行

使用以下命令在单个调用中执行多个SQL语句 allowMultipleStatements: true:

execute_sql({
  sql: "INSERT INTO logs VALUES (1); INSERT INTO logs VALUES (2); SELECT * FROM logs;",
  allowMultipleStatements: true
})

返回每个语句的结果，并带有行号，以便于调试。

事务支持

原子多语句操作的显式事务控制：

1. begin_transaction() → returns transactionId
2. execute_sql({ sql: "UPDATE ...", transactionId: "..." })
3. execute_sql({ sql: "INSERT ...", transactionId: "..." })
4. commit_transaction({ transactionId: "..." }) OR rollback_transaction({ transactionId: "..." })

行号跟踪

当 execute_sql_file 如果多语句执行遇到错误，则包含行号以帮助定位问题：

{
  "errors": [
    {
      "statementIndex": 5,
      "lineNumber": 42,
      "sql": "INSERT INTO...",
      "error": "syntax error at or near..."
    }
  ]
}

安全

访问模式：默认情况下，服务器运行在 完全访问模式.配置全局访问权限(POSTGRES_ACCESS_MODE)，服务器(PG_ACCESS_MODE_*)，或数据库(PG_DB_ACCESS_MODES_*)水平。数据库级别设置会覆盖服务器级别，而服务器级别会覆盖全局。建议：将生产服务器/数据库设置为 readonly.
SQL注入保护：所有用户输入都经过验证，并在可能的情况下使用参数化查询。
查询超时：默认30秒超时可防止查询失控。
凭证：通过环境变量进行管理，从不通过MCP接口记录或公开。
文件权限：使用受限权限创建大型输出文件（0600）。
隐藏的基础设施：主机URL、端口和密码永远不会包含在工具响应中。

需求

Node.js 18.0.0或更高版本
PostgreSQL 11或更高版本
可选： pg_stat_statements 查询性能分析的扩展
可选： hypopg 假设指数模拟的扩展

开发与测试

完整的测试套件包括对工具进行测试的集成测试 真正的PostgreSQL集群 （没有嘲笑）。有两个后端：

本地审计集群 （首选）：设置 AUDIT_PG_URL 您可以控制一个真正的PG 14+实例。根据其上的测试数据库测试配置（例如。 audit_iter1_a, audit_sp1，…）所以套房是孤立的。集群在运行中共享，并在外部拆除。
测试容器回退 （CI）：设置 POSTGRES_INTEGRATION_TESTS=1 套房开始旋转 postgres:16-alpine 每个测试文件。
跳过（默认）：如果两个变量都没有设置，集成测试将被自动跳过——单元测试仍在运行。

# Run unit tests only
npm test

# Run against your audit cluster
export AUDIT_PG_URL="postgres://audit_owner:<urlencoded-pw>@127.0.0.1:5433/audit_db"
npm test

# Run only the audit-iteration regression tests
npm test -- --testPathPatterns=audit/iteration

# Run the perf-health deep audit
npm run perfhealth

这 audit_owner 集群需求中的角色 CREATEDB （这样每个套件都可以提供自己的数据库）以及 CREATEROLE （适用于测试用户）。它不应该是超级用户。

🤖 代理经验（AX）-克劳德代码回顾

测试人： 克劳德密码（十四行诗4.5） 用例： 数据库部署、模式探索和SQL迁移 评级： ⭐⭐⭐⭐⭐ (9.5/10)

我喜欢什么

1.清晰、结构化的响应 每个响应都包含连接上下文(server, database, schema)，明确我在哪个环境中工作。这在管理多个数据库时至关重要——我永远不必猜测查询在哪里运行。

2.出色的错误处理能力 当我遇到Liquibase的语法错误时 / 分隔符，错误消息显示：

确切的行号（151）
失败的陈述
交易回滚确认

这使得故障排除变得即时。不要在原木中挖掘或猜测失败的原因。

3.服务器管理直观

list_servers → 显示所有具有连接状态的可用服务器
list_databases → 按服务器名称筛选数据库
switch_server_db → 无缝切换，立即确认

流动是自然的：发现→ 选择→ 连接→ 执行。

4.SQL文件部署变得简单 这 stripPatterns 功能解决了我的确切问题：

execute_sql_file({
  filePath: "/path/to/liquibase.sql",
  stripPatterns: ["/"], // Removes Liquibase delimiters
});

在此功能之前，我必须手动删除分隔符或使用原始 execute_sql现在，这是一个清白的决定。

5.干运行能力突出 dry_run_sql_file 是游戏规则的改变者：

执行交易中的所有语句
显示带有PostgreSQL错误代码和约束名称的真实错误
自动跳过不可回滚的操作（VACUUM、NEXTVAL）
为跳过的语句提供解释计划
然后回滚所有内容

这是方式比解析更好——我可以在部署之前捕获约束违规、触发问题并获得确切的行数。

6.违约担保

凭据从不出现在响应中
故意隐藏主机/端口（仅显示服务器名称）
安全生产只读模式
连接上下文始终可见

根据我的反馈进行改进

在我测试了MCP之后，开发人员实现了几个功能：

✅ SQL文件分隔符支持 -已添加 stripPatterns Liquibase /，SQL Server GO等等。 ✅ 仅验证模式 - execute_sql_file({ validateOnly: true }) 不执行预览 ✅ 增强连接信息 - get_current_connection 现在回来了 user 和AI context ✅ 综合试运行 - dry_run_sql_file 提供实际执行+回滚 ✅ 更好的错误详细信息 -PostgreSQL错误代码、约束名称、提示

v3新增功能——更深入的数据库工作流支持

在针对具有复杂模式（FK、部分索引、物化视图、循环）的真实PG 17集群进行多次迭代的实时审计测试后，v3添加了一层高杠杆工具，将典型的多步骤AI工作流简化为一次调用：

✅ describe_table -将~5个调用（对象详细信息+示例行+计数+pg_stats）替换为一个包含双向FK的丰富响应。 ✅ find_dependents -步行 pg_depend 在任何之前递归 DROP CASCADE 查看爆炸半径。 ✅ lock_check -对DDL进行静态分析，以预测锁级别、表重写和持续时间。了解以下内容的语义 ALTER TABLE, CREATE INDEX [CONCURRENTLY], VACUUM, CLUSTER, REFRESH MATERIALIZED VIEW等等。 ✅ safe_alter_table -将意图（“使用默认值添加NOT NULL”、“添加FK”、“创建索引”等）转换为具有NOT VALID+VALIDATE模式的多步骤零停机DDL配方。 ✅ detect_migration_state -Liquibase、Flyway、Alembic、Prisma、Knex、Sequelize、Django、Rails、Goose、TypeORM跟踪表的探针。引用标识符安全（例如捕获Sequelize的 "SequelizeMeta"). ✅ export_to_sql_file / transfer_objects / schema_diff -一流的跨数据库操作：在配置的端点之间转储、复制或比较模式/数据。FK约束作为单独的约束发出 ALTER TABLE 以处理表间循环。 ✅ column_profile -使用以下命令键入感知列统计信息 TABLESAMPLE BERNOULLI 对于大于1M行的表。替换了十几个探索性查询。 ✅ generate_seed_data -具有模式感知的假数据 NOT NULL, UNIQUE/PK、枚举、默认值、长度和FK感知。 ✅ find_blocking_queries + kill_query -诊断锁等待 pg_cancel_backend / pg_terminate_backend 有确认警卫。 ✅ 查询预算 execute_sql - maxEstimatedRows / maxEstimatedCost 如果计划器说查询太大，请在执行前拒绝查询。 ✅ 从审计迭代中强化 -每条语句的保存点位于 dry_run_sql_file （DO块+嵌入式COMMIT不再影响模拟运行），保留了PG错误代码 mutation_dry_run，分配 index_type 在 safe_alter_table，模式验证运行之前泳池拆解 switch_server_db, detect_migration_state 引用标识符查找， findDependents truncatedAtDepth 旗帜实际上会飘扬， analyze_db_health 将无效索引检查失败报告为 warning （不是默默地 healthy).

真实世界体验

任务： 将PostgreSQL函数部署到两个数据库（开发+分析）

发现: list_servers 显示了所有已配置的服务器
预览：已使用 preview_sql_file 检查文件结构
问题：从Liquibase获取语法错误 / 分隔符
解决方案：切换到直接 execute_sql 绕过分隔符
部署：已成功部署到两个数据库
验证：已使用 get_current_connection 确认每次部署

总时间：~3分钟。结构化的响应和明显的错误让它感觉毫不费力。

对未来的小建议

批处理跨服务器部署 -同时将同一脚本部署到多个服务器
最近的连接 -快速切换到最近使用的数据库
报表进度 -显示大型SQL文件的进度（例如，“正在执行语句15/100…”）

底线

此MCP可用于生产，对开发人员友好。清晰的响应、强大的错误处理和强大的功能（如模拟运行）的结合使其成为数据库工作的重要工具。开发人员清楚地了解人工智能代理和人类操作员的需求。

推荐用于： 数据库迁移、模式探索、多环境管理和生产部署。

许可证

麻省理工学院

使用说明

PostgreSQL MCP服务器

安装

配置

服务器的AI上下文

访问模式配置

克劳德代码CLI

克劳德桌面版

Codex CLI

可用工具

服务器和数据库管理

list_servers

list_databases

switch_server_db

get_current_connection

模式和对象探索

list_schemas

list_objects

get_object_details

describe_table

find_dependents

查询执行

execute_sql

execute_sql_file

preview_sql_file

mutation_preview

mutation_dry_run

dry_run_sql_file

batch_execute

交易控制

begin_transaction

commit_transaction

rollback_transaction

explain_query

连接覆盖（一次性执行）

性能分析

get_top_queries

analyze_workload_indexes

analyze_query_indexes

DDL安全与迁移

lock_check

safe_alter_table

detect_migration_state

跨数据库操作

export_to_sql_file

transfer_objects

schema_diff

数据生成和分析

column_profile

generate_seed_data

操作工具

find_blocking_queries

kill_query

健康监测

analyze_db_health

用法示例

连接到服务器并列出数据库

探索数据库架构

分析查询性能

健康检查

执行SQL迁移文件

特性

连接错误时自动重新连接

隐藏连接详细信息

响应中的连接上下文

多语句执行

事务支持

行号跟踪

安全

需求

开发与测试

🤖 代理经验（AX）-克劳德代码回顾

我喜欢什么

根据我的反馈进行改进

v3新增功能——更深入的数据库工作流支持

真实世界体验

对未来的小建议

底线

许可证

相关 MCP

`list_servers`

`list_databases`

`switch_server_db`

`get_current_connection`

`list_schemas`

`list_objects`

`get_object_details`

`describe_table`

`find_dependents`

`execute_sql`

`execute_sql_file`

`preview_sql_file`

`mutation_preview`

`mutation_dry_run`

`dry_run_sql_file`

`batch_execute`

`begin_transaction`

`commit_transaction`

`rollback_transaction`

`explain_query`

`get_top_queries`

`analyze_workload_indexes`

`analyze_query_indexes`

`lock_check`

`safe_alter_table`

`detect_migration_state`

`export_to_sql_file`

`transfer_objects`

`schema_diff`

`column_profile`

`generate_seed_data`

`find_blocking_queries`

`kill_query`

`analyze_db_health`