🐸 rainfrog

a database management tui for postgres

[!WARNING] rainfrog is currently in alpha.

the goal for rainfrog is to provide a lightweight, terminal-based alternative to pgadmin/dbeaver.

features

• efficient navigation via vim-like keybindings and mouse controls
• query editor with keyword highlighting and session history
• quickly copy data, filter tables, and switch between schemas
• shortcuts to view table metadata and properties
• cross-platform (macOS, linux, windows, android via termux)

why "rainfrog"?

frogs find refuge in elephant tracks

disclaimer

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.

installation

cargo

after installing rust (recommended to do so via rustup):

cargo install rainfrog

aur

arch linux users can install from the AUR with an AUR helper:

paru -S rainfrog

termux

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

install script

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

release page binaries

1. manually download and unpack the appropriate binary for your os from the latest release (if you're not sure which binary to pick, you can find out by installing rust and running rustc -vV to see the "host" target)
2. move the binary to a folder in your PATH environment variable

usage

[!NOTE] connection_url must include your credentials for accessing the database (ex. postgres://username:password@localhost:5432/postgres)

rainfrog --url $(connection_url)

keybindings

general

menu (list of schemas and tables)

query editor

keybindings may not behave exactly like vim. the full list of active vim keybindings in rainfrog can be found at vim.rs.

query history

results

roadmap

known issues and limitations

• for query results with many columns, the height of the rendered Table widget may be limited, as the maximum area of the underlying buffer is u16::MAX (65,535). Could be fixed by https://github.com/ratatui-org/ratatui/issues/1250
• on mac, for VS Code and terminal (and perhaps other editors), a setting for "use option as meta key" needs to be turned on for Alt/Opt keybindings to work. (In VS Code, it's "terminal.integrated.macOptionIsMeta": true; in kitty, it's macos_option_as_alt yes in the config.)
• in visual mode, when selecting an entire line, the behavior is not the same as vim's, as it simply moves starts the selection at the head of the line, so moving up or down in lines will break the selection.
• mouse events are only used for changing focus and scrolling; the editor does not currently support mouse events, and menu items cannot be selected using the mouse

acknowledgements

• ratatui (this project used ratatui's component template as a starting point)
• tui-textarea (used in the query editor)
• gobang (a rust db tui i drew inspiration from)
• ricky rainfrog