Skip to content

Key bindings and vim mode ​

The TUI's keys work out of the box, and you can change them: the app-wide ones and the ones each pane uses for itself. You can also edit SQL with vim keys.

To see every key in quarry itself, press F1 and type to filter, for example run, ctrl or vim. Each rebindable action shows its name on the right. That name is what you write in the config.

Change a key ​

Add a [keys] table to ~/.config/quarry/config.toml (run quarry --default-config to see a commented example). Each line names an action and gives it one key or a list of keys:

toml
[keys]
run_statement = ["ctrl+enter", "ctrl+e"]   # several keys
run_all = "f9"                              # one key
themes = "alt+t"
quit = []                                   # no key (Quit stays in the command palette)

A line replaces all of that action's default keys. Actions you don't list keep their defaults.

How to write a key ​

Modifiers, then the key, joined with +. Case doesn't matter.

WriteFor
ctrl, alt, shiftModifiers, e.g. ctrl+shift+enter
a … z, 0 … 9, ?, /, …A character
enter, esc, tab, space, backspace, delete, insertNamed keys
up, down, left, right, home, end, pageup, pagedownMovement keys
f1 … f24Function keys

When keys collide ​

quarry sorts collisions out for you, so a new binding never silently breaks another:

  • Your binding wins over a default. If you bind run_all = "ctrl+r", Ctrl+R stops opening History. When an action is left without any key this way, quarry tells you when the TUI starts, and you can give it a new one.
  • Two of your own bindings on one key: one action keeps it and you get a warning naming both. The action that comes first in the list below wins.
  • Alt+1…9 always jump to tabs and can't be rebound.
  • Keys the editor uses itself (its actions under Editor, such as Ctrl+C or Ctrl+Y) keep their editor meaning while the editor has focus. An app-wide binding on one of them works everywhere else, and quarry warns you about it. Give the editor action another key and the app-wide one works in the editor too.
  • A pane's keys are its own. grid_copy = "c" changes c in the grid only; the explorer's c is untouched. Within one pane a key runs one action, and a table view counts as a grid. A key held by a Global action never reaches a pane, and quarry says so.
  • A character can't be an editor shortcut, since you type it there. Editor actions need Ctrl, Alt or a function key.
  • A plain character such as ? works only when you aren't typing in a text field, so it never gets in the way of your SQL.
  • An unknown action or key is skipped with a warning; the rest of [keys] still applies.

Warnings appear as notices when the TUI starts.

Actions you can rebind ​

Global ​

ActionDefault keysDoes
commandsCtrl+PCommand palette
helpF1, ?Keyboard shortcuts
connectionsCtrl+OConnections
new_queryCtrl+TNew query tab (in the explorer: for the selected database)
close_tabCtrl+WClose tab
next_tabAlt+→, Ctrl+PgDnNext tab
prev_tabAlt+←, Ctrl+PgUpPrevious tab
next_paneF6Focus the next pane: explorer, editor, results
prev_paneShift+F6Focus the previous pane
focus_explorerAlt+0Focus the explorer
toggle_explorerCtrl+BShow or hide the explorer
go_to_tableCtrl+GGo to a table
themesCtrl+YTheme picker
historyCtrl+RQuery history
quitCtrl+QQuit

Query tabs ​

ActionDefault keysDoes
run_statementCtrl+Enter, Alt+Enter, Ctrl+ERun the statement under the cursor, or the selection
run_allF5, Ctrl+Shift+EnterRun everything in the editor
cancelEsc, Ctrl+CCancel the running query
explainF7Explain
explain_analyzeShift+F7Explain analyze
format_sqlAlt+FFormat the SQL
save_favoriteCtrl+SSave the query as a favourite
exportCtrl+XExport results to a file
editor_smallerCtrl+↑Make the editor smaller
editor_largerCtrl+↓Make the editor larger

Editor ​

These apply while you type, and in vim's insert mode. vim's normal and visual modes keep their own keys.

ActionDefault keysDoes
editor_completeCtrl+SpaceCompletion (it also opens as you type)
editor_select_allCtrl+ASelect all
editor_copyCtrl+CCopy the selection
editor_cutCtrl+XCut the selection
editor_pasteCtrl+VPaste
editor_undoCtrl+ZUndo
editor_redoCtrl+Y, Ctrl+Shift+ZRedo
editor_duplicateCtrl+DDuplicate the line or selection
editor_commentCtrl+/, Ctrl+7Comment or uncomment
editor_line_upAlt+↑Move the line up
editor_line_downAlt+↓Move the line down
editor_delete_word_leftCtrl+Backspace, Ctrl+HDelete the word before the cursor
editor_delete_word_rightCtrl+DeleteDelete the word after the cursor

Results and grids ​

The results of a query, and the grid of a table view.

ActionDefault keysDoes
grid_upk, ↑Up
grid_downj, ↓Down
grid_lefth, ←Left
grid_rightl, →Right
grid_page_upPgUpPage up
grid_page_downPgDnPage down
grid_half_page_upCtrl+UHalf a page up
grid_half_page_downCtrl+DHalf a page down
grid_first_rowgFirst row
grid_last_rowGLast row
grid_first_column0, HomeFirst column
grid_last_column$, EndLast column
grid_columns_rightwA screen of columns right
grid_columns_leftbA screen of columns left
grid_next_cellTabNext cell
grid_prev_cellShift+TabPrevious cell
grid_selectvSelect a block of cells
grid_select_rowsVSelect whole rows
grid_view_cellEnterView the cell and its row
grid_copyyCopy cells as TSV
grid_copy_rowsYCopy rows with a header
grid_search/Search in the results
grid_search_nextnNext match
grid_search_prevNPrevious match
grid_narrow_column<Narrow the column
grid_widen_column>Widen the column
grid_fit_column=Fit the column to its content
grid_prev_result[Previous result set
grid_next_result]Next result set
grid_messagesmMessages
grid_to_editoriBack to the editor

Table view ​

On top of the grid's keys.

ActionDefault keysDoes
table_filterfFilter with a WHERE condition
table_filter_by_valueFFilter by the current cell's value
table_sortsSort by the column
table_edit_celle, F2Edit the cell
table_add_rowoAdd a row
table_delete_rowsD, DeleteMark rows for deletion
table_applyCtrl+SReview and apply staged changes
table_discarduDiscard staged changes
table_reloadr, F5Reload

Explorer ​

After the explorer_script key, the next key (s i u d c x n) picks the statement and is fixed.

ActionDefault keysDoes
explorer_upk, ↑Up
explorer_downj, ↓Down
explorer_expandl, →Expand
explorer_collapseh, ←Collapse, or go to the parent
explorer_toggleSpaceExpand or collapse
explorer_lastG, EndLast row
explorer_openEnterOpen a table, show a function, insert a column, switch database
explorer_consolecNew query tab for this database or schema
explorer_structuresTable structure
explorer_insert_nameiInsert the name into the editor
explorer_scriptgWrite a statement for the table, with s i u d c x n next
explorer_filter/Filter the tree
explorer_reloadr, F5Reload the schema
explorer_new_connectionnNew connection
explorer_disconnectCtrl+XDisconnect

Other tabs ​

ActionDefault keysDoes
structure_next_sectionTab, ]Structure tab: next section
structure_prev_sectionShift+Tab, [Structure tab: previous section
activity_pausep, SpaceActivity tab: pause or resume refreshing
activity_refreshrActivity tab: refresh now
activity_killKActivity tab: kill the selected session
text_copyyA definition or a table's DDL: copy the text
text_to_editoreA definition or a table's DDL: open it in a query tab

A few keys stay fixed: arrows and the other typing keys in the editor, Shift+arrows to select in a grid, scrolling in text and plan views, Esc, vim's keys, and the keys of dialogs. The grid actions apply to query results and table views. They're listed in Keyboard shortcuts. The hints in the status bar, in notices and in the empty editor follow your bindings.

Vim mode ​

Set vi = true under [main]. The REPL gets vi editing, and the TUI's SQL editor gets vim's modes:

  • Normal is where you start. The cursor is a block and the status bar says NORMAL.
  • Insert (i, a, o, …) is ordinary typing, with completion as you type. The cursor turns into a bar.
  • Visual (v) and visual-line (V) select text for an operator.

Esc goes back to normal mode. In normal mode, Esc moves to the results, as it does without vim. The app-wide keys (run, explain, tabs, palette) work in every mode.

KeysDo
h j k lLeft, down, up, right
w b eNext word, previous word, end of word
0 ^ $Line start, first non-blank, line end
gg GFirst line, last line (5G goes to line 5)
Ctrl+D / Ctrl+UHalf a page down / up
/ or ? + text, EnterSearch forward or backward for the text (Esc cancels)
n NThe next match in the search's direction / the other way, wrapping round the text
.Repeat the last change: dw, ciw with what you typed, 3dd, p, …
i a I AInsert before, after, at line start, at line end
o ONew line below / above
d c y > < + a motionDelete, change, yank, indent, dedent: dw, c$, y2j, >G
dd cc yy >> <<The same on whole lines
ciw, diw, yawChange, delete, yank a word (a includes the space after it)
x XDelete the character under / before the cursor
s SReplace the character / the line
D C YDelete / change to the end of the line, yank the line
r + a characterReplace the character under the cursor
JJoin the next line onto this one
p PPaste after / before. Whole lines go below / above.
u, Ctrl+RUndo, redo

A number in front repeats: 3j, 2dd, 5x. Yanks and deletes go to the system clipboard, so you can paste them elsewhere, and text copied elsewhere pastes with p.

A search is for the text as typed, not a pattern. All in lowercase it matches any case; with a capital letter in it, the case must match too.

Not supported: search as a motion (d/x), marks, macros, registers other than the clipboard, and : commands. A SQL editor's commands are a key away already (run, format, explain, save), so quarry leaves those to vim itself.

Released under the MIT licence.