Pg Client

Schema Inspection

Data Exploration

Diagram Generation

Database Health & Stats

Supabase / RLS

Apache AGE Graph Queries

Connection Profiles

Connection Options

Every command accepts:

• -p <profile> — use a saved profile
• --dsn <connection_string> — direct DSN
• Or set DATABASE_URL / PG_DSN environment variable

Output Formats

-f table (default), -f json, -f csv, -f vertical

Examples

# Save connection profiles
python3 "$PG_CLIENT" profile-add local "postgresql://user:pass@localhost:5432/mydb"
python3 "$PG_CLIENT" profile-add supabase "postgresql://postgres.xxxx:[email protected]:6543/postgres" --supabase
python3 "$PG_CLIENT" profile-add rag "postgresql://bridge:secret@localhost:5432/bridge"

# List tables
python3 "$PG_CLIENT" tables -p local

# Describe a table
python3 "$PG_CLIENT" describe users -p supabase

# Run a query
python3 "$PG_CLIENT" query "SELECT * FROM users LIMIT 10" -p local
python3 "$PG_CLIENT" q "SELECT count(*) FROM orders" -p local -f json

# Run from a .sql file
python3 "$PG_CLIENT" query report.sql -p local

# Insert/Update with transaction safety
python3 "$PG_CLIENT" exec "INSERT INTO users (name, email) VALUES ('Leo', '[email protected]')" -p local
python3 "$PG_CLIENT" exec "UPDATE users SET active=true WHERE id=1 RETURNING *" -p local --returning

# Explain a query
python3 "$PG_CLIENT" explain "SELECT * FROM orders WHERE total > 100" -p local

# Search across text columns
python3 "$PG_CLIENT" search users "john" -p local

# Random sample
python3 "$PG_CLIENT" sample orders -p local -n 5

# Dump table
python3 "$PG_CLIENT" dump users -p local -f csv
python3 "$PG_CLIENT" dump users -p local -f json -n 100

# ER Diagram generation
python3 "$PG_CLIENT" erd -p local                                      # Print to stdout
python3 "$PG_CLIENT" erd -p local -o ./diagrams/                       # Save to folder (auto-names as db_erd.md)
python3 "$PG_CLIENT" erd -p local -o ./schema.md                       # Save to specific file (.md wraps in code block)
python3 "$PG_CLIENT" erd -p local -o ./schema.mmd                      # Save raw Mermaid (no markdown wrapper)
python3 "$PG_CLIENT" erd -p local --tables "users,orders,products"     # Only specific tables + their FK relationships

# Database health
python3 "$PG_CLIENT" size -p local
python3 "$PG_CLIENT" activity -p supabase
python3 "$PG_CLIENT" vacuum -p local
python3 "$PG_CLIENT" slow -p local

# RLS policies (Supabase)
python3 "$PG_CLIENT" rls -p supabase
python3 "$PG_CLIENT" rls --table profiles -p supabase

# Apache AGE graph queries
python3 "$PG_CLIENT" graphs -p rag
python3 "$PG_CLIENT" graph-schema my_graph -p rag
python3 "$PG_CLIENT" graph my_graph "MATCH (n) RETURN n LIMIT 10" -p rag
python3 "$PG_CLIENT" graph my_graph "MATCH (a)-[r]->(b) RETURN a.name, type(r), b.name LIMIT 20" -p rag
python3 "$PG_CLIENT" graph my_graph "CREATE (n:Person {name: 'Leo', role: 'dev'}) RETURN n" -p rag

Workflow

When the user says /pg-client, parse $ARGUMENTS:

1. If contains a known command — run it directly.
2. If just a table name — run describe on it.
3. If a question about the DB — translate to SQL and run query.
4. If mentions "graph" — use the graph commands.
5. If mentions "supabase" — check for RLS too.
6. Always show output and execution time.
7. For mutations, confirm the SQL before executing.

Security Notes

• Profiles with passwords are stored at ~/.claude/skills/pg-client/profiles.json
• Passwords are masked in profiles output
• exec command uses transactions — rolls back on error
• Never run DROP/TRUNCATE without user confirmation