Skip to content

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 setup

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
  1. The agent reads the billing code: any open invoice more than 14 days past due keeps a workspace suspended.
  2. inspect_row returns paid invoice 90017, its suspended organization, and its past-due subscription.
  3. A targeted SQL query finds invoice 90018 for the same period and $49 amount, still open and 23 days overdue.
  4. 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

  1. 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.

  2. 02

    Inspect a record

    inspect_row
    {
      "table": "public.invoices",
      "key": { "id": 90017 }
    }
    
    # ← paid invoice, linked
    #   org + subscription

    inspect_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.

  3. 03

    Verify with targeted SQL

    query
    SELECT id, status, amount_cents
    FROM public.invoices
    WHERE org_id = 142
      AND period_start = '2026-09-05';
    
    # ← bounded, read-only

    The 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 access

The 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 SQL

QueryIO

inspect_row + SQL

Start 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 SQL

Both 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.

scopewhat that means
enforcedInvestigation tools use READ ONLY transactions and reject direct data changes. Use a dedicated role with narrow read permissions.
enforcedCredentials come only from QUERYIO_DATABASE_URL. Never from arguments or .env files.
not guaranteedQueryIO is not a sandbox. An agent with shell access can run psql on its own.
not guaranteedRedaction matches column names. A hand-written query can alias a column past it.
not guaranteedPrivileged roles, side-effecting functions, dblink or foreign data wrappers can affect data outside the read-only transaction.

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

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