Query language & MCP

This page is the database browser’s reference: how to walk records, the query language, and the MCP server a coding agent uses.

invoice show id, total, customer_id.name as customer where total >= 500 limit 20

Follow a record

Open a record to see its fields and every row elsewhere that points at it, counted (zero included). Follow a reference or a reverse relationship; each step keeps its filter, and Back restores the view you left.

The address carries the walk, so a copied URL opens the same place:

What	Address
A record	/{connection}/{table}/~{id}
A composed page	/{connection}/@{page}~{id}
A list, as its query	/demo/invoice%20total%20%3E%20500

Apps use their own canonical addresses.

A json/jsonb column (or SQLite JSON) is laid out by its shape: objects as fields, arrays of records as tables. In a grid a JSON cell names its shape ({ id, name, +3 }); click it, or press Enter, to open the document. Documents are read-only in editors; change one with SQL.

Query language

The table comes first; conditions, columns, sort and limit follow.

customer active = true sort credit_limit desc
invoice invoice_date = last 30 days
employee title contains manager show first_name, last_name
customer country_code in (AU, NZ) and email is not empty

Intent	Spelling
Compare	=, !=, <, <=, >, >=
Match text	contains, startswith, endswith (case-insensitive where supported)
Match a set	in (AU, NZ), not in (AU, NZ)
Check null	is empty, is not empty
Combine	and, or, parentheses
Choose columns	show or select
Order	sort or order by
Filter	conditions directly, or after where / filter

Dates: today, yesterday, this week, last month, last 30 days, next 7 days; previous 30 days is the window just before last 30 days.

Paths are checked against the catalog and values are bound parameters, so a misspelled column is an error, not an empty result. SQL shows the compiled query.

Group and measure

Measures come before by, then up to three grouping keys:

invoice count by status
invoice count, sum total as billed by month invoice_date sort billed desc limit 12
invoice where total > 100 count by customer_id.country_code.name as country
customer count distinct country_code as countries by active

Measures: count, count column, count distinct column, sum, avg, min, max. Date buckets: day, month, quarter, year.

SQL and schema tools

The browser also has raw SQL, explain, schema lint, value search and schema export. An App has none of them: it serves its declared resources through its own rooms, and the standalone browser is the tool for the rest.

npx tablewalk mydata.sqlite --export md
npx tablewalk mydata.sqlite --lint --fail-on high

MCP for coding agents

npx tablewalk --mcp --config ./tablewalk.json

{
  "mcpServers": {
    "tablewalk": {
      "command": "npx",
      "args": ["tablewalk", "--mcp", "--config", "/absolute/path/tablewalk.json"]
    }
  }
}

25 tools: 19 read-only, and 6 writes listed only when a connection is "writable": true.

Task	Tools
Orient	connections, schema_summary, tables, table
Locate and inspect	find, query, record, profile
Summarize	breakdown
Diagnose	sql, explain, lint, change_impact, diff
Prepare fixtures	order, fixture
Refresh or author	refresh, scaffold_app, validate_app
Write (writable only)	insert, update, delete, insert_graph, delete_graph, revert

• --tools explore, migrate or seed narrows the list (full is the default); a profile never grants writes. --output-schema advertises output shapes.
• Statements stop at 30 seconds (sql takes a lower timeout_ms) and when the client cancels. Totals and counts stop at 10,000 and say so.
• sql and explain refuse tablewalk’s own __tablewalk_ tables and the tablewalk_auth schema.
• Authenticated and named-source Apps are refused here; an App reaches an agent through App MCP.

Keyboard

Key	Does
/	Focus the query bar
⌘K	Command palette
Enter	Open the focused row (or JSON cell)
Space	Glance at the row without leaving the list
j / k	Next / previous record in the list you came from
Backspace, ⌘[	Walk back
?	Every key for the room you are in