Inspect a PostgreSQL schema and return its full structure as JSON.

Call this before writing any query, JOIN, or EXPLAIN — it gives you exact table/column names and indexes so you don't guess.

Returns a JSON object:

• "columns": table_name, column_name, data_type, is_nullable, column_default

• "foreign_keys": which columns reference which tables (use for JOINs)

• "indexes": full CREATE INDEX definitions (check before running EXPLAIN)

Large schemas (100+ tables) return a lot of JSON — filter by table_name client-side rather than calling this multiple times.

Execute a SQL query against a PostgreSQL database and return rows as JSON.

Returns: {"rows": [...], "row_count": N}

Mode behaviour (per project in databases.json):

• readonly — only SELECT/WITH accepted; writes are blocked before reaching the DB.

• readwrite — all SQL allowed; use only on non-production projects.

Call describe_postgres_schema first to confirm table/column names. If row_count equals your LIMIT, there are likely more rows.

Run EXPLAIN (ANALYZE, BUFFERS, FORMAT JSON) on a query and return the plan.

The query executes to collect real timing; results are discarded — only the plan is returned. A statement timeout prevents runaway queries.

Returns: {"plan": []}

Use before running a slow or unfamiliar query on a large table. Check describe_postgres_schema first to see what indexes exist. Write queries are blocked.

List all configured database projects and their access modes.

Call this first when you don't know which project_id to use. Returns every project registered in databases.json, including which one is the default (used when project_id is omitted).

Returns a JSON object: { "default_project": "<project_id>", "projects": [ {"project_id": "", "mode": "readonly|readwrite", "is_default": true|false}, ... ] }

Return the top N most expensive queries from pg_stat_statements.

Best starting point for a performance audit — shows which query patterns cost the most cumulative time across the application.

Returns: {"rows": [{query, calls, total_exec_sec, mean_exec_sec, max_exec_sec, total_rows, shared_blks_hit, shared_blks_read}], "row_count": N}

Query text uses $1/$2 placeholders (pg_stat_statements normalises literals). Requires the pg_stat_statements extension (enabled by default on RDS, Cloud SQL, Supabase; otherwise: CREATE EXTENSION pg_stat_statements).