pg-lock-xray

One line: npx pg-lock-xray prisma/migrations (or bunx pg-lock-xray prisma/migrations): catch ACCESS EXCLUSIVE PostgreSQL migration lock hazards before production.

+-------------------------------------------------------------+
|  migration.sql  -->  lock classifier  -->  severity report   |
|       |                      |                               |
|       +---- --fix --> CONCURRENTLY / NOT VALID rewrites      |
+-------------------------------------------------------------+

Install

Bun / npm:

bunx pg-lock-xray ./migrations
npx pg-lock-xray ./migrations

# or install in your project / globally
bun add -d pg-lock-xray
npm i -D pg-lock-xray

JSR:

bunx jsr add @kanchingyg/pg-lock-xray
npx jsr add @kanchingyg/pg-lock-xray

Cargo (Rust native binary):

cargo install --git https://github.com/kanchingyg/pg-lock-xray

The core engine is Rust (src/lib.rs, src/main.rs, src/mcp.rs): static lock rules, zero-downtime rewrite hints, and sqlOrPath containment under migrations/, prisma/, supabase/, or sql/. TypeScript under src/*.ts is included for npx / bunx / JSR usage and MCP bridge helpers.

Related MCP server: locksmith

Quick start

npx pg-lock-xray ./migrations
bunx pg-lock-xray ./migrations
npx pg-lock-xray --fix ./sql/0001_init.sql --dry-run
npx pg-lock-xray --fix ./sql/0001_init.sql --allow-write
npx pg-lock-xray --mcp

What it catches

MCP & Ollama

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "pg-lock-xray": {
      "command": "npx",
      "args": ["-y", "pg-lock-xray", "--mcp"]
    }
  }
}

Call MCP tool rewrite_zero_downtime with { "sqlOrPath": "...", "model": "llama3.2", "baseUrl": "http://127.0.0.1:11434" }.

Flags

MCP Tools Reference

Editor and Agent Integration

Cursor (.cursor/mcp.json)

{
  "mcpServers": {
    "pg-lock-xray": {
      "command": "npx",
      "args": ["-y", "pg-lock-xray", "--mcp"]
    }
  }
}

Claude Code CLI

claude mcp add pg-lock-xray -- npx -y pg-lock-xray --mcp

Programmatic Usage (JSR / TypeScript)

import * as bridge from "jsr:@kanchingyg/pg-lock-xray/bridge";

Runtime Safety and Guardrails

• Stdio frame isolation: When --mcp is active, hijackStdoutForMcp() redirects accidental console.log calls to stderr so JSON-RPC 2.0 frames on stdout never corrupt.

• Read-only by default: Mutating tools (mutates: true) are blocked in --dry-run mode and require explicit --allow-write authorization.

• Loop breaker: Repeated identical (toolName, args) invocations are hashed with SHA-256 and halted after 3 consecutive repeats to prevent runaway agent loops.

• Context budget truncation: Tool outputs are middle-truncated (60% head / 40% tail) scaled to the probed local model n_ctx (Ollama /api/show, llama.cpp /props, vLLM /v1/models).

• Secret redaction and path normalization: AWS keys (AKIA*, ASIA*), bearer tokens, and sk-* keys are scrubbed before returning tool output, and Windows drive paths (C:\...) translate cleanly to /mnt/c/... when WSL mode is enabled.

License

MIT