English | 中文

pg-toolkit

The PostgreSQL Swiss Army knife for TypeScript developers.

One CLI to diagnose, inspect, diff, monitor, and generate types for your Postgres databases.

🔍 20+ health checks with scoring and auto-generated fix SQL 🔄 Schema diff that outputs ready-to-run migration SQL 🤖 AI-agent ready via MCP — plug into Claude, Cursor, or any MCP client

Quick Start

npx @indiekitai/pg-toolkit doctor postgres://localhost/mydb

🏥 Database Health Report — mydb
Overall Score: 82/100

✅ Cache Hit Ratio .............. 99.2%  (excellent)
⚠️  Unused Indexes .............. 3 found
✅ Connection Usage ............. 12/100
❌ Table Bloat .................. 2 tables need VACUUM
✅ Long Transactions ............ none
✅ Lock Contention .............. clear
⚠️  Vacuum Status ............... 1 table never vacuumed
✅ Slow Queries ................. p95 < 100ms

📋 Fix Script Generated → fix.sql (4 statements)

Commands

doctor — Diagnose, score, fix

Runs 20+ checks against your database, produces a 0–100 health score, and generates executable SQL to fix what it finds.

pg-toolkit doctor postgres://localhost/mydb
pg-toolkit doctor postgres://localhost/mydb --ci --threshold 70   # fail CI if unhealthy
pg-toolkit doctor postgres://localhost/mydb --output fix.sql      # save fixes
pg-toolkit doctor postgres://localhost/mydb --json                # machine-readable

inspect — See everything in your schema

Tables, views, functions, indexes, enums, triggers, constraints, RLS policies — all in one command.

pg-toolkit inspect postgres://localhost/mydb
pg-toolkit inspect --tables --indexes postgres://localhost/mydb
pg-toolkit inspect --summary postgres://localhost/mydb            # just counts

diff — Compare schemas, get migration SQL

Point it at two databases. Get ALTER, CREATE, and DROP statements to migrate one to the other.

pg-toolkit diff postgres://localhost/dev postgres://localhost/prod
pg-toolkit diff --safe postgres://localhost/dev postgres://localhost/prod   # no DROPs
pg-toolkit diff postgres://dev postgres://prod | psql postgres://prod      # apply directly

top — Live activity monitor

Like htop for your database. See active queries, locks, and connection stats in real time.

pg-toolkit top postgres://localhost/mydb
pg-toolkit top --refresh 1 --no-idle postgres://localhost/mydb
pg-toolkit top --snapshot --json postgres://localhost/mydb        # single snapshot

types — PostgreSQL → TypeScript

Generate TypeScript interfaces from your database schema.

pg-toolkit types postgres://localhost/mydb

Programmatic API

import { doctor, inspect, diff } from '@indiekitai/pg-toolkit';

const report = await doctor({ connectionString: 'postgres://localhost/mydb' });
console.log(report.overallScore); // 82
console.log(report.fixes);        // SQL fix statements

const schema = await inspect('postgres://localhost/mydb');

const migration = await diff(devUrl, prodUrl, { safe: true });
console.log(migration.sql); // ALTER TABLE ..., CREATE INDEX ...

AI Agent / MCP

All tools are available as an MCP server. Add this to your agent config:

{
  "mcpServers": {
    "pg-toolkit": {
      "command": "npx",
      "args": ["@indiekitai/pg-toolkit", "mcp"],
      "env": { "DATABASE_URL": "postgresql://localhost/mydb" }
    }
  }
}

Exposes pg_doctor, inspect_schema, diff_schemas, and pg_activity as MCP tools. Works with Claude, Cursor, Windsurf, and any MCP-compatible agent.

How it compares

Feature	pg-toolkit	pgcli	migra	prisma
Health checks + scoring	✅ 20+ checks	❌	❌	❌
Auto-generate fix SQL	✅	❌	❌	❌
Schema inspection	✅	✅ partial	❌	✅ introspect
Schema diff → SQL	✅	❌	✅	✅ migrate diff
Live activity monitor	✅	❌	❌	❌
TypeScript generation	✅	❌	❌	✅ built-in
MCP / AI-agent support	✅	❌	❌	❌
CI mode (exit codes)	✅	❌	✅	✅
Single npx command	✅	pip install	pip install	npm + config

pg-toolkit combines what used to require 3–4 separate tools into one npx call.

License

MIT