Database debugging · MCP server
Debug database issues with your AI coding agent.
QueryIO is an open-source PostgreSQL MCP server that helps coding agents investigate application bugs with database evidence: inspect a record, see related rows, and verify a diagnosis with bounded, read-oriented SQL.
Currently supports PostgreSQL only.
npx -y queryio setupNode.js 20+ · No global install needed
Pick your agent
Set QUERYIO_DATABASE_URL in the environment that starts your agent. The wizard configures one or more agents with project or global scope and previews changes before writing. It does not store credentials or provision PostgreSQL. Setup details · Verify your connection
Read-only · bounded · redacted · audited
See it work
Paid invoice. Suspended workspace. Why?
Follow an agent from the billing code to a paid invoice and its linked records, then through a SQL check that reveals the duplicate invoice keeping the workspace suspended.
32-second illustrated walkthrough · PostgreSQL · No audio. Use fullscreen for small text.
Read the demo walkthrough
- The agent reads the billing code: any open invoice more than 14 days past due keeps a workspace suspended.
- inspect_row returns paid invoice 90017, its suspended organization, and its past-due subscription.
- A targeted SQL query finds invoice 90018 for the same period and $49 amount, still open and 23 days overdue.
- The agent diagnoses the duplicate invoice as the blocker and recommends voiding it and reactivating the workspace. QueryIO does not apply the fix.
How it works
- 01
Set up QueryIO
terminal$ npx -y queryio setup # Choose your agents # Review and confirm
The wizard configures your selected coding agents, previews changes before writing, and checks PostgreSQL connectivity when QUERYIO_DATABASE_URL is set. Choose project or global scope.
- 02
Inspect a record
inspect_row{ "table": "public.invoices", "key": { "id": 90017 } } # ← paid invoice, linked # org + subscriptioninspect_row fetches a record by its full primary key and bounded samples of immediate declared foreign-key relationships, in both directions, in one MCP call.
- 03
Verify with targeted SQL
querySELECT id, status, amount_cents FROM public.invoices WHERE org_id = 142 AND period_start = '2026-09-05'; # ← bounded, read-onlyThe agent uses your code to interpret the records, then checks its diagnosis with read-oriented SQL. Here, a second invoice is still open for the same billing period.
Why QueryIO
Starting with SQL
SQL accessThe agent writes the lookups that connect a symptom to related records.
- Find the record behind the bug.
- Look up its relationships in the schema.
- Write joins or follow-up queries to gather related rows.
schema → SQL → records → follow-up SQLQueryIO
inspect_row + SQLStart with the failing record and related evidence in one MCP call.
- Inspect a user, invoice, or project by its primary key.
- Get bounded samples of rows linked by declared foreign keys.
- Use application code and targeted SQL to verify the diagnosis.
record → inspect_row → targeted SQLBoth workflows use SQL. QueryIO adds the initial relationship lookups through inspect_row, so the agent can compare state across tables before choosing its next query. Samples are not exhaustive or ordered by recency; use SQL to confirm missing data or investigate relationships without declared foreign keys.
What it does
Inspect a record
inspect_row fetches one row by its full primary key and samples of rows one declared foreign key away, in one MCP call.
Follow linked rows
Incoming and outgoing relationships, up to 5 rows per relation and 25 relations by default. Check has_more and skipped or failed relations.
Verify with SQL
query accepts one read-oriented SELECT, WITH, VALUES, TABLE or SHOW statement per call, including joins and aggregates.
Understand the schema
list_tables and describe_tables return columns, keys, indexes and planner stats without scanning tables.
Bounded results
query defaults to 100 returned rows and a 32 KiB result budget. Long values are shortened with a size marker.
Redact sensitive values
Exact column-name matches, such as password, token or api_key, return [redacted]. Aliases and expressions can bypass redaction.
Read-only execution
Investigation tools run in READ ONLY transactions and roll back afterward. Database permissions still determine what functions can do.
Server-side timeouts
Postgres cancels statements after 5 seconds and lock waits after 1 second.
Audit operations
Local audit logging records tool metadata by default, without row values. Logging failures do not stop an investigation.
Numeric budgets and timeouts are configurable. Returned records enter your agent’s context. Read the security guidance and resource limits before connecting sensitive data.
Benchmark
An AI agent ran five tasks against a seeded SaaS database with raw psql or QueryIO, with DBHub as a reference: 25 runs, every answer graded by hand. Three tasks were about specific records; two counted across many rows.
- Database calls
- 16 → 13
- Median, record-level tasks, psql → QueryIO
- Database output
- 25 KB → 16 KB
- Median, record-level tasks, psql → QueryIO
- Correct answers
- 100%
- Every arm, graded by hand
In each record-level task, a record lookup in at least one run surfaced the fact that explained the problem: a missing membership, a duplicate invoice, and an API key that was never revoked.
What it didn't show
- We set a target in advance: about 30% fewer calls or less output. Averages missed it: 17% fewer calls and 21% less output on record-level tasks.
- On the counting tasks, QueryIO used more output on average, not less.
- It is a small study: two runs per task, one model.
- We measured bytes of database output, not model tokens.
- The QueryIO runs used a command-line wrapper, not the MCP server.
Get started
Investigate the record behind the bug.
Connect PostgreSQL, give your coding agent a record ID and a symptom, and start investigating.
Set up QueryIO