🐸 rainfrog

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.

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

supported databases

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!

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

arch linux

arch linux users can install from the official repositories using pacman:

pacman -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

nix

nix-env -iA nixos.rainfrog

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

Usage: 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

with connection options

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>

with connection url

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

customization

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:

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

settings

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).

keybindings

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.

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

now that rainfrog is in beta, check out the issues tab for planned features

known issues and limitations

• geometry types are not currently supported
• in sqlite, EXPLAIN QUERY PLAN does not work due to an issue with the sql parser; see https://github.com/achristmascarl/rainfrog/issues/106
• for x11 and wayland, yanking does not copy to the system clipboard, only to the query editor's buffer. see https://github.com/achristmascarl/rainfrog/issues/83
• in addition to the experience being subpar if the terminal window is too small, if the terminal window is too large, rainfrog will crash due to the maximum area of ratatui buffers being u16::MAX (65,535). more details in https://github.com/achristmascarl/rainfrog/issues/60
• for query results with many columns, the height of the rendered Table widget may be limited due to the same limitation mentioned above. 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

you can find other reported issues in the issues tab

Contributing

for bug reports and feature requests, please create an issue.

please read CONTRIBUTING.md before opening issues or creating PRs.

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
• rainfroggg (my wife's tattoo studio)