Skip to content
Conduit

skill

pg-lock-xray

Static PostgreSQL migration lock scanner with zero-downtime SQL rewrites and MCP tools

kanchingyg/pg-lock-xraycommunitylistedunreviewed
Use skill

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/kanchingyg/pg-lock-xray itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 28, 2026

pg-lock-xray

ci npm JSR JSR Score Rust license

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.

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

PatternRisk
CREATE INDEX without CONCURRENTLYACCESS EXCLUSIVE lock blocking writes
CREATE INDEX USING hnsw without CONCURRENTLYpgvector blocking index build
ADD CONSTRAINT ... FOREIGN KEY without NOT VALIDLong table validation lock
Volatile DEFAULT on ADD COLUMNFull table rewrite

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

FlagPurpose
--allow-writeEnable rewrite_zero_downtime file writes
--dry-runShow diff / run tools without writing
--mcpJSON-RPC MCP server on stdio
--wsl-pathsNormalize paths for WSL agents

MCP Tools Reference

ToolMutatesDescription
scan_sql_locksfalseAnalyze SQL migration files or directories and classify ACCESS EXCLUSIVE, SHARE, and table-rewrite lock hazards.
rewrite_zero_downtimetrueRewrite blocking DDL statements into CONCURRENTLY and NOT VALID zero-downtime patterns (writes require --allow-write).
explain_lock_hazardfalseReturn lock mode matrix details and blocked query types for a specific PostgreSQL DDL statement.

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

↑↓ navigate openesc close