Getting started
Start datarig
datarig # open the workspace
datarig my-profile # connect to a profile and open a console
datarig --config path/to/config.toml
Without a profile on the command line nothing connects until you pick one. The full list of options is on the command line page.
The welcome panel
With no connection profile yet, the workspace shows a welcome panel with four first steps: add
a connection, run a query, open the action menu, and open the keyboard help. Each is marked
once you have done it, however you did it. X hides the steps for good.
╭ Explorer ────────────╮╭ Welcome ─────────────────────────────────────────────╮
│ ＋ New connection ││ │
│▾ Connections 0 ││ datarig │
│ ││ Dive into any database, right from your terminal. │
│ No connection ││ │
│ profiles yet ││ No connection profiles yet. │
│ Press n to create ││ │
│ one, or paste a ││ First steps │
│ postgres:// or ││ [ ] n Add a connection │
│ mysql:// URL ││ [ ] Ctrl+E Run your first query │
│ ││ [ ] Space Space Open the action menu │
│ ││ [ ] Space ? Open the keyboard help │
│ ││ X Hide these steps │
│ ││ : Commands │
│ ││ q Quit │
│ ││ Paste a connection URL (postgres://, mysql://) │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
╰──────────────────────╯╰──────────────────────────────────────────────────────╯
│ Enter open · Tab next pane · : commands · Space ? help · q quit EN
Add a connection
Press n (or Enter) on the welcome panel, or Space c n anywhere, to open the profile
form. Fill in the host, port, user and database, or paste a connection URL such as
postgres://me@127.0.0.1:5432/app into it. Test connects once and shows the server
version, the latency and how the connection is encrypted. Saving writes the profile to the
config file; the password goes to the password store you chose, never into the file. See
Connections.
Connect and run a query
Ctrl+Oopens quick connect: type part of a profile’s name and pressEnter. A console tab on that connection opens.- Press
ito type (the editor has vim keys;Escgoes back to Normal mode). Ctrl+Eruns the statement under the cursor.Ctrl+Ccancels a running statement.- The result opens below the editor.
n(or]) and[in the grid move to the next and previous page;TabandF6move the focus between the panes.
A statement that may do harm (a DROP, an UPDATE without a real WHERE, …) asks first,
with Cancel focused. See Environments and safety.
Find your way
- Press
Spaceand wait: a popup lists the keys that may follow. F1orSpace ?opens the keyboard help for the current pane, with search.Space Spaceopens the action menu: what you can do with the selected thing, each with its key. A right click opens it too.:(outside text input) orCtrl+K(everywhere) opens the command line. It runs commands and finds every action by name.- The hint line at the bottom, the menus, the tips and the messages all name the same key for
an action: a key of your own when you bound one, else one that needs no function key
(
Space ?rather thanF1), except where that key types text (in insert mode the help isF1).
The workspace
╭ Explorer ────────────────────────────╮ 1 console 1 ×
│ ＋ New connection │╭ Query · console 1 ───────────────────────────────────────────────────────────────────────────────────────────────────╮
│▾ Connections 1 ││ local-pg / datarig 127.0.0.1:55432 Space c s switch connection │
│ ▾ ● local-pg ││ 1 -- datarig 🐘 Ctrl+E: run the statement under the cursor │
│ ▾ datarig default ││ 2▎SELECT * FROM shop.users WHERE id <= 8; │
│ ▸ analytics ││ 3 │
│ ▸ public ││ 4 SELECT u.name, o.status, o.total_amount │
│ ▸ shop ││ 5 FROM shop.orders o │
│ ││ 6 JOIN shop.users u ON u.id = o.user_id │
│ ││ 7 WHERE o.status = 'paid'; │
│ ││ 8 │
│ ││ 9 SELECT * FROM analytics.events; │
│ ││ 10 │
│ ││ 11 SELECT * FROM analytics.events ORDER BY created_at DESC; │
│ ││ 12 │
│ ││ 13 SELECT analytics.slow(30); │
│ ││ 14 │
│ ││ 15 SELECT $$a body; with a semicolon$$ AS dollar, 'it''s; fine' AS quoted; │
│ ││ 16 │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
│ ││ │
╰──────────────────────────────────────╯╰──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯
NORMAL local-pg │ Connected to local-pg │ i type · Ctrl+E run · Tab next pane · : commands · Space ? help · Space more EN
Tabs. Ctrl+T (or :tabnew) opens a new console, Ctrl+W closes the tab, Space 1 ..
Space 9 go to a tab, Ctrl+PageDown / Ctrl+PageUp (or g t / g T) to the next and
previous one.
Space t t(or:tabs,:ls,:buffers) lists the open tabs, the most recently used first with the previous one selected, then the tabs closed in this session. Type to filter by name, kind, connection, database or schema;Entergoes to a tab or brings a closed one back,Ctrl+Dcloses the selected tab.Space t ureopens the last closed tab.- Reorder tabs by dragging one with the mouse, with
Space t gand thenh/l(Enterkeeps,Escputs it back), withSpace t </Space t >, or with:tabmoveas in Vim (:tabmove 0first,:tabmovelast,:tabmove +1). The order is kept across restarts.
Panes. Space z zooms the focused pane (explorer, editor, results or inspector) to the
whole workspace and back, as tmux does (ZOOM in the status bar). Space b hides or shows the
explorer, Space < / Space > or a drag of its border resize it, and a drag of the results’
top border resizes them.
The action menu. A right click on an explorer node, the result grid, a tab or the editor
opens it at the pointer; Space Space, Shift+F10 or the Menu key open it next to the
selection, and Space t m under the active tab. It lists what you can do with the selected
thing, then with the pane, each with its key. An action that would act there but can’t now,
and has a reason to give, is shown dimmed with why in a few words (a read-only environment,
a table tab’s Save, paging that closed); the keys step over it, and a click on it says the
reason in full. Type to filter it;
when nothing in it matches, every action is searched.
The mouse. Besides the menu, the mouse works in the dialogs (the profile and tunnel forms,
the settings, confirmations, the password prompt, pick lists, quick connect, the command line).
A button or a row acts when it is pressed and released on it. The pointer only highlights; it
never moves the focus or the selection, so Enter in a confirmation still keeps. Text inputs
have no mouse selection. Under the pointer, the tab bar’s × turns red, tabs, result tabs,
paging arrows and plan view names light up, and a grid cell and the inspector entry of its
column light each other faintly.
Settings. Space , (or :settings) opens the settings screen; every setting there is also
:set <setting>=<value> (see the commands reference) and a key in the
config file. The UI is in English or Korean:
:set language=ko (or auto for the system locale).
Remapping keys. [keymap.<context>] tables in the config file bind keys to action ids, or
unbind them with "none"; see the keybindings reference.
Tips
By default a dim line about a key shows where the screen is empty anyway: the workspace without
tabs, an empty console, a result with nothing to show or still running, and the status bar’s
spare room. The key named is the one bound now, remapped keys included. The tips of a place
take turns as you move between tabs and panes and run queries, and they keep coming back; a key
you have already pressed comes up less often than the ones you have not (where a place has only
two tips, they simply alternate). [ui] tips (also on
the settings screen, or :set ui.tips=until_used) picks how they behave: "always" (the
default), "until_used" (a tip about a key you have pressed once is not shown again) or
"off". An action you ran three times from the action menu or the command line without its
key gets one status line naming its key, once. Nothing is sent anywhere; see
where datarig keeps its files.
What’s new
On the first start after an update, datarig shows what changed: the notes of every version
since the one you ran before, newest first (if you used a version from before 0.39.0, the notes
of the version you run now). A first start of a new install shows nothing. :whatsnew shows the
notes of every version any time. The notes come with the program, so this works offline and
nothing is fetched; they are the same as the What’s new page.
In the dialog, j/k scroll, Ctrl+D/Ctrl+U half a page, PageDown/PageUp a page,
g/G go to the top or the end, ]/[ to the next or previous version, and Esc closes.
[updates] whats_new = "off" (also on the settings screen, under Updates, or
:set updates.whats_new=off) stops it from showing by itself; :whatsnew still works. When a
newer release is out, the start after datarig learnt it shows a notice; see
Updates.
Quit
:q closes the tab (on the last tab, it quits). :qa or Ctrl+Q quits. When a tab holds an
uncommitted transaction, datarig asks first.
The workspace (tabs, their text, cursors, open folders) is saved and restored at the next start. A second datarig started while the first runs restores no tabs and writes none of the workspace files.
Try it against a test database
The repository’s dev/ directory has Docker Compose services for development. Start its
PostgreSQL (see the
development notes) and paste
postgres://datarig@127.0.0.1:55432/datarig into the new-connection form; the password is
datarig.