Using the TUI
The TUI is quarry's full-screen interface. Open it in any of these ways:
quarry --tui postgres://me@localhost/app # or -T
quarry # no target: starts on the connection listFrom the REPL, \tui opens it on the current connection.
Two keys get you everywhere: Ctrl+P opens the command palette, which lists every action by name, and F1 lists every shortcut (type to filter it).
The layout
- Header: your tabs, each with a close button, then + for a new query tab. On the right, the theme (click to change it) and the command palette.
- Explorer (left): connections, databases, schemas, tables, views, functions and columns. Ctrl+B hides it.
- Main area: the active tab. A query tab has an editor on top and results below.
- Status bar: the mode (
EDITOR,RESULTS,EXPLORER, orNORMAL/INSERTin vim mode), the connection and database (click to open Connections), badges for an open transaction (TX),READ-ONLY,sshandTLS, hints for the keys you can use now, your position in the results, and the time.
Move focus with F6 (explorer → editor → results) or a click. Resize the explorer or the editor/results split by dragging the border between them (or Ctrl+↑ / ↓ for the split).
The icons come from a Nerd Font. Without one, set icons = "unicode"; see Icons.
Connecting
Ctrl+O opens Connections, a list of your saved connections. Each shows its type and address; a check mark means it's already open.
- Enter or a click connects. Choosing one that's already open takes you to it instead of opening it twice.
- n (or + New connection) opens a short form. Paste a URL, or pick the type and fill in host, port, user, password and database. Give it a name under Save as to save it in your config; leave the name empty to connect just this once. The password is never saved.
- d deletes a saved connection. Esc goes back, then closes.
You can have several connections open at once. Each gets its own tree in the explorer, and each tab belongs to one connection. Every connection uses two sessions, one for your queries and one for the explorer and table views, so the explorer keeps working while a long query runs. Ctrl+X on a connection in the explorer disconnects it.
Writing and running queries
Type SQL in the editor, then run it with the ▶ Run button on the editor's border, or a key:
| Key | Runs |
|---|---|
| Ctrl+Enter (also Ctrl+E, Alt+Enter) | The selection, or the statement under the cursor |
| F5 or Ctrl+Shift+Enter | Everything in the editor |
| F7 / Shift+F7 | Explain / explain analyze |
| Esc, Ctrl+C or ■ Stop while running | Cancel at the server |
Statements run in order and stop at the first error. Each statement that returns rows gets its own result tab; switch with [ and ] or a click. The Messages tab (m) logs what happened, with row counts, notices and errors. After an error, the failing position is marked in the editor.
The editor completes as you type: keywords, tables after FROM, columns of the tables in the statement, joins, functions. Ctrl+Space asks for it, and you can pick with the mouse too. It also has bracket matching, auto-closing quotes and brackets, undo and redo, and Ctrl+/ to toggle comments. Alt+F formats the whole buffer.
Prefer vim keys? Set vi = true: see vim mode.
Special commands that describe the database (\dt, \d users, \l, \df, \s, …) also work in the editor; their output lands in the results grid. \llm asks a model to write SQL; see Asking a model for SQL.
Query consoles for a database
A query tab can belong to one database (or, on PostgreSQL, one schema), like a console in an IDE. Select a database, schema, or anything inside one in the explorer and press c (or Ctrl+T while the explorer has focus). The new tab is named after it, and its border shows where it runs, for example local-mysql ▸ shop.
In that tab:
- Queries run in that database, so you can write
select * from userswithoutshop.users. quarry switches the session there before each run (USE shopon MySQL; on PostgreSQL the schema goes first on thesearch_path). If the switch fails, nothing runs. - Completion suggests that database's tables and columns first.
- New tabs you open from it start in the same place.
Tabs on the same connection can work in different databases side by side. Another PostgreSQL database can't be switched to in the same session, so a console for one opens its own connection, named like local-postgres/analytics, and reuses it next time.
On MySQL, every query tab remembers the database it was opened in, so running a console in shop doesn't move your other tabs.
The results grid
The grid handles large results: rows appear as they arrive, and a query stops fetching at 200,000 rows (the Messages tab says so).
| Key | Does |
|---|---|
| h j k l or arrows | Move (Shift extends the selection) |
| g / G, 0 / $ | First / last row, first / last column |
| v / V | Select a block / whole rows |
| Enter or double-click | View the cell, with JSON pretty-printed, and the whole row |
| y / Y | Copy the selection as TSV / copy rows with a header |
| /, n, N | Search the results |
| < > = | Narrow, widen or auto-fit the column |
| Ctrl+X | Export to a file |
Export writes the rows in the grid to a file, choosing the format from the extension: .csv, .tsv, .json, .jsonl, .md, .html, .sql (INSERT statements) or .txt.
The palette also has Copy results as CSV / JSON / Markdown / SQL INSERT, which copy the whole result to the clipboard. y and Y copy just the selection.
The explorer
| Key | Does |
|---|---|
| Enter on a table or view | Browse its rows in a table view |
| Enter on a function | Show its definition |
| c | A query console for the database or schema you're in |
| s | Structure: columns, indexes, foreign keys, referencing tables, constraints, triggers, DDL |
| i | Insert the name into the editor |
| g then s i u d c x n | Write a SELECT, INSERT, UPDATE, DELETE, CREATE, DROP or COUNT for this table into an editor. Nothing runs until you run it. |
| / | Filter the tree |
| r | Reload the schema |
| n | Open Connections |
The current database is highlighted. On MySQL, the other databases load when you open them (or when you type thatdb. in the editor), and then complete too. On PostgreSQL the explorer also lists the server's other databases; Enter on one switches the connection to it, c opens a console on it. System schemas are hidden. The schema reloads by itself after statements such as CREATE, ALTER and DROP.
Ctrl+G jumps to any table by fuzzy name, across all open connections.
Other tabs
| Tab | Opened with | Shows |
|---|---|---|
| Query | Ctrl+T, the + button | Editor and results |
| Table | Enter on a table | Rows, page by page, with filters, sorting and edits |
| Structure | s in the explorer | Columns, indexes, keys, constraints, triggers, DDL |
| Explain | F7 | The plan as a tree, with bars for cost or time, and details per node |
| Activity | Palette → Server activity | Live sessions on a PostgreSQL or MySQL server, refreshed every 2 s. K kills one. |
| History | Ctrl+R | Past statements; type to filter, Enter (or click it twice) opens one in a new tab |
Close a tab with Ctrl+W, its close button, or a middle click. Move between tabs with Alt+← / →, Alt+1…9, or a click.
Using the mouse
The mouse works everywhere unless you set mouse = false:
- Click to focus a pane, pick a tab or result set, place the cursor, select a cell, open a tree item, or press a button (tab close, +, ▶ Run, the theme and palette buttons, the connection in the status bar).
- Drag to select text in the editor or cells in the grid, or drag a border to resize the explorer or the editor/results split.
- Scroll the editor, grid, messages and any list. In lists (palette, completion, History, Explain) the wheel moves the selection.
- Dialogs: click an item or button to choose it; click outside a dialog to close it.
- Middle click a tab to close it; double-click a cell to view it; click a column header in a table view to sort.
Keys and customising
- Key bindings and vim mode: rebind the app-wide keys under
[keys], and edit SQL with vim keys. - Keyboard shortcuts: every key, including the ones inside each pane.
- Themes: Ctrl+Y previews themes live.
transparent = truelets a translucent terminal show through.
Favourites and files
- Ctrl+S in a query tab saves the selection (or the whole editor) as a favourite query. Saved favourites appear in the palette.
- Open SQL file… and Save editor to file… are in the palette.
Transactions
Run BEGIN in the editor to start a transaction; the TX badge appears. Commit transaction and Rollback transaction are in the palette, or type COMMIT / ROLLBACK. Quitting with an open transaction asks first, and the transaction is rolled back.
Things to know
- The TUI doesn't restore your tabs or editor text between runs. Only the theme is remembered.
- Quitting asks for confirmation if a query is running, a transaction is open, or a table view has unapplied edits.
--theme,--iconsand--no-colorapply to the TUI too. After\tui, the TUI keeps the REPL's theme.row_limit,table_format,timingand the pager settings apply to the REPL, not the TUI.