@yawlabs/postgres-mcp

Cancel or terminate a backend

pg_kill

Destructive

Cancel a running query or terminate a backend connection by PID. Use to stop problematic queries when pg_health shows active_queries or locks.

Instructions

Cancel a running query (SIGINT-equivalent) or terminate a backend connection (SIGTERM-equivalent) by PID. Find the PID via pg_health active_queries or pg_inspect_locks. Requires ALLOW_WRITES=1 since this changes database session state. The role in DATABASE_URL must have permission - cancelling another user's query needs the pg_signal_backend role or superuser. Note: pg_signal_backend does NOT cover superuser-owned backends - only a superuser can signal another superuser's session. Cancel is graceful; terminate is forceful. signaled=true means postgres SENT the signal, not that the target stopped: a session that is idle (or idle in a transaction) ignores a cancel, so re-check with pg_health and use terminate for an idle session. signaled=false means postgres found no backend with that PID; the note field carries its own warning (e.g. 'PID 123 is not a PostgreSQL backend process'). A permission denial is NOT a false: postgres raises, so the call returns an error with SQLSTATE 42501 that says what the role lacks.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`pid`	Yes	Backend PID to signal.
`mode`	No	`cancel` aborts the current query; `terminate` closes the connection entirely.	cancel

Output Schema

TableJSON Schema

Name	Required	Description
`pid`	Yes	Echoed back from the request.
`mode`	Yes	Echoed back, after the safer 'cancel' default is applied.
`note`	Yes	On `signaled: false`, postgres's own warning explaining why -- act on this, not on the boolean.
`signaled`	Yes	What pg_cancel_backend / pg_terminate_backend returned: true once the signal is SENT, not once it has taken effect.

Schema Changelog

Changes observed during successful MCP inspections.

Changed2 schema fields changedv0.13.4Sep 19, 2026

changedOutput schema / properties / note / description

Previous value: -"On `signaled: false`, postgres's own NOTICE explaining why -- act on this, not on the boolean."New value: +"On `signaled: false`, postgres's own warning explaining why -- act on this, not on the boolean."

changedOutput schema / properties / signaled / description

Previous value: -"What pg_cancel_backend / pg_terminate_backend returned."New value: +"What pg_cancel_backend / pg_terminate_backend returned: true once the signal is SENT, not once it has taken effect."

Changed2 schema fields changedv0.12.0Aug 28, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

changedOutput schema / (root)

Previous value: -nullNew value: +{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "additionalProperties": false,
+  "properties": {
+    "mode": {
+      "description": "Echoed back, after the safer 'cancel' default is applied.",
+      "enum": [
+        "cancel",
+        "terminate"
+      ],
+      "type": "string"
+    },
+    "note": {
+      "description": "On `signaled: false`, postgres's own NOTICE explaining why -- act on this, not on the boolean.",
+      "type": "string"
+    },
+    "pid": {
+      "description": "Echoed back from the request.",
+      "type": "number"
+    },
+    "signaled": {
+      "description": "What pg_cancel_backend / pg_terminate_backend returned.",
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "pid",
+    "mode",
+    "signaled",
+    "note"
+  ],
+  "type": "object"
+}

First observedv0.7.0Jul 29, 2026

TDQS

A4.9/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description goes far beyond annotations by explaining signal semantics (SIGINT vs SIGTERM), the meaning of signaled=true vs signaled=false, the fact that signaled=true only means the signal was sent and not that the target stopped, and the SQLSTATE 42501 permission-denied behavior. It also clarifies that pg_signal_backend does not cover superuser-owned backends, a critical operational nuance.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is long but every sentence carries essential operational information for a destructive action. It is front-loaded with the core action and then methodically covers discovery, prerequisites, permission details, signal semantics, response interpretation, and error behavior. No filler or redundancy is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

This is a destructive tool with non-obvious response semantics and permission requirements. The description fully covers what an agent needs to call it safely and interpret results correctly, including edge cases like idle sessions, superuser-owned backends, and permission-denial error behavior. The presence of an output schema makes the absence of return-value documentation acceptable, and the description compensates by explaining the meaning of key fields.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the baseline is 3, but the description adds meaningful value beyond the schema: it explains how to obtain the pid from specific sibling tools and clarifies the behavioral difference between mode='cancel' (graceful) and mode='terminate' (forceful). This enriches both parameters without repeating their schema definitions verbatim.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb ('Cancel' or 'terminate') applied to a backend by PID, clearly defining the tool's scope. It distinguishes itself from sibling read-only tools by explicitly being a signal operation and even points to siblings for PID discovery. The title and description align without being a mere tautology.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives explicit when-to-use guidance: find the PID via pg_health active_queries or pg_inspect_locks, requires ALLOW_WRITES=1, and requires appropriate role permissions. It also gives a conditional directive—if a session is idle, use terminate instead of cancel—which is precise actionable guidance for choosing between modes and alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.