a database management tui for postgres
[!WARNING] rainfrog is currently in beta; the mysql and sqlite drivers are unstable.
the goal for rainfrog is to provide a lightweight, terminal-based alternative to pgadmin/dbeaver.
rainfrog has mainly been tested with postgres, and postgres will be the primary database targeted. mysql and sqlite are also supported, but they are currently unstable; use with caution, and check out the known issues section for things to look out for!
this software is currently under active development; expect breaking changes, and use at your own risk. it is not recommended to use this tool with write access on a production database.
after installing rust (recommended to do so via rustup):
cargo install rainfrog
arch linux users can install from the official repositories using pacman:
pacman -S rainfrog
if you are using termux, you'll need to install rust via their package manager:
pkg install rust
and then make sure to install with termux features (and disable default features):
cargo install rainfrog --features termux --no-default-features
nix-env -iA nixos.rainfrog
there is a simple install script that assists in downloading and unpacking a
binary from the release page to ~/.local/bin/
, which you might want to add to
your PATH
variable if it isn't already there. you'll need to select which
binary is appropriate for your system (if you're not sure, you can find out by
installing rust and running rustc -vV
to see the "host" target), and the
script also needs jq and
fzf installed to run.
curl -LSsf https://raw.githubusercontent.com/achristmascarl/rainfrog/main/install.sh | bash
rustc -vV
to see the "host" target)PATH
environment variableUsage: rainfrog [OPTIONS]
Options:
-M, --mouse <MOUSE_MODE> Whether to enable mouse event support. If enabled, the default mouse event handling for your terminal
will not work. [possible values: true, false]
-u, --url <URL> Full connection URL for the database, e.g. postgres://username:password@localhost:5432/dbname
--username <USERNAME> Username for database connection
--password <PASSWORD> Password for database connection
--host <HOST> Host for database connection (ex. localhost)
--port <PORT> Port for database connection (ex. 5432)
--database <DATABASE> Name of database for connection (ex. postgres)
--driver <DRIVER> Driver for database connection (ex. postgres)
-h, --help Print help
-V, --version Print version
if any options are not provided, you will be prompted to input them. if you do not provide an input, that option will default to what is in your environment variables.
rainfrog \
--driver <db_driver> \
--username <username> \
--host <hostname> \
--port <db_port> \
--database <db_name>
the connection_url
must include all the necessary options for connecting
to the database (ex. postgres://username:password@localhost:5432/postgres
).
it will take precedence over all connection options.
rainfrog --url $(connection_url)
docker run
for postgres and mysql, you can run it by specifying all of the options as environment variables:
docker run --platform linux/amd64 -it --rm --name rainfrog \
--add-host host.docker.internal:host-gateway \
-e db_driver="db_driver" \
-e username="<username>" \
-e password="<password>" \
-e hostname="host.docker.internal" \
-e db_port="<db_port>" \
-e db_name="<db_name>" achristmascarl/rainfrog:latest
if you want to provide a custom combination of options and omit others, you can override the Dockerfile's CMD like so:
docker run --platform linux/amd64 -it --rm --name rainfrog \
achristmascarl/rainfrog:latest \
rainfrog # overrides CMD, additional options would come after
since sqlite is file-based, you may need to mount a path to the sqlite db as a volume in order to access it:
docker run --platform linux/amd64 -it --rm --name rainfrog \
-v ~/code/rainfrog/dev/rainfrog.sqlite3:/rainfrog.sqlite3 \
achristmascarl/rainfrog:latest \
rainfrog --url sqlite:///rainfrog.sqlite3
rainfrog can be customized by placing a rainfrog_config.toml
file in
one of the following locations depending on your os, as determined by
the directories crate:
Platform | Value | Example |
---|---|---|
Linux | $XDG_CONFIG_HOME /_project_path_ or $HOME /.config/_project_path_ |
/home/alice/.config/barapp |
macOS | $HOME /Library/Application Support/_project_path_ |
/Users/Alice/Library/Application Support/com.Foo-Corp.Bar-App |
Windows | {FOLDERID_LocalAppData} \_project_path_ \config |
C:\Users\Alice\AppData\Local\Foo Corp\Bar App\config |
you can change the default config location by exporting an environment variable. to make the change permanent, add it to your .zshrc/.bashrc/.*rc file:
export RAINFROG_CONFIG=~/.config
right now, the only setting available is whether rainfrog captures mouse events by default. capturing mouse events allows you to change focus and scroll using the mouse. however, your terminal will not handle mouse events like it normally does (you won't be able to copy by highlighting, for example).
you can customize some of the default keybindings, but not all of them. to see a list of the ones you can customize, see the default config file at .config/rainfrog_config.toml. below are the default keybindings.
keybinding | description |
---|---|
Ctrl+c |
quit program |
Alt+1 , Ctrl+k |
change focus to menu |
Alt+2 , Ctrl+j |
change focus to query editor |
Alt+3 , Ctrl+h |
change focus to results |
Alt+4 , Ctrl+g |
change focus to query history |
Tab |
cycle focus forwards |
Shift+Tab |
cycle focus backwards |
q , Alt+q in query editor |
abort current query |
keybinding | description |
---|---|
j , ā |
move selection down by 1 |
k , ā |
move selection up by 1 |
g |
jump to top of current list |
G |
jump to bottom of current list |
h , ā |
focus on schemas (if more than 1) |
l , ā |
focus on tables |
/ |
filter tables |
Esc |
clear search |
Backspace |
focus on tables |
Enter when searching |
focus on tables |
Enter with selected schema |
focus on tables |
Enter with selected table |
preview table (100 rows) |
R |
reload schemas and tables |
Keybindings may not behave exactly like Vim. The full list of active Vim keybindings in Rainfrog can be found at vim.rs.
Keybinding | Description |
---|---|
Alt+Enter , F5 |
Execute query |
j , ā |
Move cursor down 1 line |
k , ā |
Move cursor up 1 line |
h , ā |
Move cursor left 1 char |
l , ā |
Move cursor right 1 char |
w |
Move cursor to next start of word |
e |
Move cursor to next end of word |
b |
Move cursor to previous start of word |
0 |
Move cursor to beginning of line |
$ |
Move cursor to end of line |
gg |
Jump to top of editor |
G |
Jump to bottom of current list |
Esc |
Return to normal mode |
i |
Enter insert (edit) mode |
I |
Enter insert mode at beginning of line |
A |
Enter insert mode at end of line |
o |
Insert new line below and enter insert |
v |
Enter visual (select) mode |
V |
Enter visual mode and select line |
r |
Begin replace operation |
y |
Begin yank (copy) operation |
x |
Begin cut operation |
p |
Paste from clipboard |
u |
Undo |
Ctrl+r |
Redo |
Ctrl+e |
Scroll down |
Ctrl+y |
Scroll up |
keybinding | description |
---|---|
j , ā |
move selection down by 1 |
k , ā |
move selection up by 1 |
g |
jump to top of list |
G |
jump to bottom of list |
y |
copy selected query |
I |
edit selected query in editor |
D |
delete all history |
keybinding | description |
---|---|
j , ā |
scroll down by 1 row |
k , ā |
scroll up by 1 row |
h , ā |
scroll left by 1 cell |
l , ā |
scroll right by 1 cell |
b |
scroll right by 1 cell |
e , w |
scroll left by 1 column |
{ , PageUp , Ctrl+b |
jump up one page |
} , PageDown , Ctrl+f |
jump down one page |
g |
jump to top of table |
G |
jump to bottom of table |
0 |
jump to first column |
$ |
jump to last column |
v |
select individual field |
V |
select row |
Enter |
change selection mode inwards |
Backspace |
change selection mode outwards |
y |
copy selection |
Esc |
stop selecting |
now that rainfrog is in beta, check out the issues tab for planned features
EXPLAIN QUERY PLAN
does not work due to an issue with the
sql parser; see https://github.com/achristmascarl/rainfrog/issues/106u16::MAX
(65,535). more details in
https://github.com/achristmascarl/rainfrog/issues/60Table
widget
may be limited due to the same limitation mentioned above. Could be fixed by
https://github.com/ratatui-org/ratatui/issues/1250"terminal.integrated.macOptionIsMeta": true
; in
kitty, it's macos_option_as_alt yes
in the config.)you can find other reported issues in the issues tab
for bug reports and feature requests, please create an issue.
please read CONTRIBUTING.md before opening issues or creating PRs.