pgtool_skill

Overview

This skill provides PostgreSQL database exploration and debugging using a JSON-first CLI called pgtool. It is designed for agents and developers who need fast, structured inspection of schemas, tables, relationships, and query results. It requires a .pgtool.json config file in the project root to connect to the database.

How this skill works

All operations must be executed through the pgtool-cli wrapper in the project; do not use psql directly. The tool returns consistent JSON responses for success and error conditions and exposes commands to list schemas, tables, describe table structures, sample rows, count rows, search metadata, inspect indexes/constraints, show relationships, run queries, and explain plans. If pgtool-cli reports an error or limitation, surface the error to the user and stop; do not fall back to other tools.

When to use it

• When you need a quick, structured inventory of schemas, tables, columns, and relationships.
• When you want sample rows or exact row counts without writing custom SQL.
• When debugging query performance with explain plans or examining index coverage.
• When searching for columns or tables by name or pattern across the database.
• When running short, limited SELECT queries or DML with RETURNING via a safe CLI.

Best practices

• Always run database operations via the pgtool-cli script provided in the project.
• Include LIMIT on SELECT queries to avoid fetching large data sets.
• Use parameterized WHERE clauses or pgtool's query pattern to minimize SQL injection risk.
• Check for and surface JSON-formatted error codes (e.g., CONFIG_NOT_FOUND, CONNECTION_FAILED) to users.
• When pgtool reports an error, stop and report it rather than falling back to other DB clients.

Example use cases

• Explore a newly connected database: run pgtool schemas → overview → tables → describe to map the schema.
• Investigate data issues: describe a table, sample rows, then run explain on a problematic query.
• Find where a column appears: use pgtool search <pattern> to list matching tables and columns.
• Verify index and constraint coverage before optimizing queries: indexes <table> and constraints <table>.
• Get exact row counts for reporting or sizing: pgtool count <table>.