🐸 rainfrog

a database tool for the terminal

[!WARNING] rainfrog is currently in beta

the goal for rainfrog is to provide a lightweight, terminal-based tool for interacting with databases.

features

• efficient navigation via vim-like keybindings and mouse controls

• query editor with keyword highlighting, session history, and favorites

• 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

the levels of support for different databases can be split into 4 tiers:

• tier 1: most frequently tested, bugs will be addressed as soon as possible.

• tier 2: often tested, fixed when necessary.

• tier 3: community supported; contributions are welcome, but otherwise development is minimal.

• tier 4: new or experimental; should be treated as unstable, and behavior is subject to change.

databasetierknown issuesvia wire protocol*postgres1mysql2sqlite2redshift2postgresduckdb4musl binaries are not compatible with this driveroracle4requires additional runtime dependencies

*the postgres driver can also be used to connect to other databases that support the postgres wire protocol, such as AWS Redshift. however, this functionality is not well tested. in theory, the mysql driver should be able to do the same for databases that support the mysql protocol. check each database's documentation for compatibility.

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.

table of contents

• installation

  • cargo

  • homebrew

  • arch linux

  • termux

  • nix

  • conda

  • pixi

  • install script

  • release page binaries

  • icons

• dependencies

  • oracle

• usage

  • with connection options

  • with connection url

  • with environment variables

  • docker run

• customization

  • settings

  • database connections

  • keybindings

    • n.b. for mac users

    • general

    • menu (list of schemas and tables)

    • query editor

    • query history

    • query favorites

    • results

• exports

• favorites

• roadmap

• known issues and limitations

• Contributing

• acknowledgements

installation

cargo

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

cargo install rainfrog --locked

by default, all features are included. some features may not be compatible with your platform; check Cargo.toml to see what feature combinations are available.

homebrew

brew 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 --no-default-features

nix

nix-env -iA nixos.rainfrog

conda

conda install -c conda-forge rainfrog

pixi

The command below installs rainfrog from conda-forge, the same repository as conda, but unlike conda it can be installed user-globally using pixi.

pixi global install 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

icons

you will need to have a nerd font installed and used by your terminal for the icons to show up.

dependencies

for some of the databases supported by rainfrog, the driver has additional runtime dependencies. you can find instructions for installing those dependencies below.

oracle

the oracle driver uses ODPI-C, which requires Oracle Client libraries to be installed. instructions for installing the Oracle Instant Client can be found here: ODPI-C Installation.

after installation, you may need to manually copy the client files to a location where ODPI-C can find them, which is either in the same folder as the rainfrog binary, or in the library path of your os. more details can be found in the ODPI-C installation instructions: ODPI-C Client Library Loading.

usage

Usage: rainfrog [OPTIONS] [COMMAND]

Commands:
  edit  Edit the config file (create it first if missing)
  help  Print this message or the help of the given subcommand(s)

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)

with environment variables

if connection_url is not present, rainfrog will first check your DATABASE_URL environment variable, then it will check for DATABASE_URL in a .env file in the current directory or a parent directory.

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

running drivers which have runtime dependencies (like oracle) via docker is not currently supported.

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:

PlatformValueExampleLinux$XDG_CONFIG_HOME/_project_path_ or $HOME/.config/_project_path_/home/alice/.config/barappmacOS$HOME/Library/Application Support/_project_path_/Users/Alice/Library/Application Support/com.Foo-Corp.Bar-AppWindows{FOLDERID_LocalAppData}\_project_path_\configC:\Users\Alice\AppData\Local\Foo Corp\Bar App\config

you can change the default config directory by exporting an environment variable. to make the change permanent, add it to your .zshrc/.bashrc/.*rc file:

export RAINFROG_CONFIG=~/.config/rainfrog

[!WARNING] this should be the path to the directory that the config file is in, NOT the path to the actual file

settings

NameDefaultDescriptionmouse_modetruewhether to capture mouse events. 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).data_compact_columnstruewhether column widths should be dynamic based on the length of the contents of each column. there is still a max column width that won't be exceeded, so this will save some space by compressing the widths of columns with shorter strings.data_row_spacerfalsewhether rows will have a space separating them to make the data table less visually dense.

database connections

database connections can be configured in the configuration file as shown below:

[db]
postgres-local = { host = "localhost", driver = "postgres", port = 5432, database = "postgres", username = "postgres",  default = true }
postgres-dev = { connection_string = "postgresql://postgres:test123@127.0.0.1:5432", driver = "postgres" }
mysql-local = { host = "localhost", driver = "mysql", port = 32768, database = "rainfrog", username = "root" }
sqlite-memory = { connection_string = "sqlite://:memory:", driver = "sqlite"}
sqlite-disk = { connection_string = "sqlite://./my_database.db", driver = "sqlite"}
oracle-local = { host = "localhost", driver = "oracle", port = 1521, database = "rainfrog", username = "rainfrog" }

the connection details can be provided in two formats: a raw connection string or specifying individual fields. connections input are prioritized in the following order:

• cli input

• DATABASE_URL env variable

• config file

if no database connection in the config is set as the default connection, a prompt will appear to select the desired database. The user will also be prompted for the password for the selected database and will have the option to store it in a platform specific keychain for future reuse. future plans for database connections include switching database without having to restart rainfrog.

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.

n.b. for mac users

on mac, for VS Code, terminal, kitty, and others, 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 the settings; in kitty, it's macos_option_as_alt yes in the config.)

general

keybindingdescriptionCtrl+cquit programAlt+1, Ctrl+kchange focus to menuAlt+2, Ctrl+jchange focus to query editorAlt+3, Ctrl+hchange focus to resultsAlt+4, Ctrl+gchange focus to query historyAlt+5, Ctrl+mchange focus to query favoritesTabcycle focus forwardsShift+Tabcycle focus backwardsq, Alt+q in query editorabort current query

menu (list of schemas and tables)

keybindingdescriptionj, ↓move selection down by 1k, ↑move selection up by 1gjump to top of current listGjump to bottom of current listh, ←focus on schemas (if more than 1)l, →focus on tables/filter tablesEscclear filterBackspacefocus on tablesEnter when searchingfocus on tablesEnter with selected schemafocus on tablesEnter with selected tablepreview table (100 rows)Rreload 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.

KeybindingDescriptionAlt+Enter, F5Execute queryF7Bypass parser to execute query (cannot rollback, no validation)j, ↓Move cursor down 1 linek, ↑Move cursor up 1 lineh, ←Move cursor left 1 charl, →Move cursor right 1 charwMove cursor to next start of wordeMove cursor to next end of wordbMove cursor to previous start of word0Move cursor to beginning of line$Move cursor to end of lineggJump to top of editorGJump to bottom of current listEscReturn to normal modeiEnter insert (edit) modeIEnter insert mode at beginning of lineAEnter insert mode at end of lineoInsert new line below and enter insertvEnter visual (select) modeVEnter visual mode and select linerBegin replace operationyBegin yank (copy) operationxBegin cut operationpPaste from clipboarduUndoCtrl+rRedoCtrl+eScroll downCtrl+yScroll upCtrl+f*, Alt+fSave query to favorites

*only works in normal mode

query history

keybindingdescriptionj, ↓move selection down by 1k, ↑move selection up by 1gjump to top of listGjump to bottom of listycopy selected queryIedit selected query in editorDdelete all history

query favorites

keybindingdescriptionj, ↓move selection down by 1k, ↑move selection up by 1gjump to top of listGjump to bottom of listycopy selected queryIedit selected query in editorDdelete selected query/filter favoritesEscclear filter

results

keybindingdescriptionPexport results to csvj, ↓scroll down by 1 rowk, ↑scroll up by 1 rowh, ←scroll left by 1 celll, →scroll right by 1 cellbscroll right by 1 celle, wscroll left by 1 column{, PageUp, Ctrl+bjump up one page}, PageDown, Ctrl+fjump down one pagegjump to top of tableGjump to bottom of table0jump to first column$jump to last columnvselect individual fieldVselect rowEnterchange selection mode inwardsBackspacechange selection mode outwardsycopy selectionEscstop selecting

exports

query results can be exported to csv. exporting is a blocking action, so be careful about exporting too many rows at once, as it will freeze the application.

the file will be saved in your downloads directory, which is one of the following depending on your os, as determined by the directories crate:

PlatformValueExampleLinuxXDG_DOWNLOAD_DIR/home/alice/DownloadsmacOS$HOME/Downloads/Users/Alice/DownloadsWindows{FOLDERID_Downloads}C:\Users\Alice\Downloads

you can change the default export location by exporting an environment variable. to make the change permanent, add it to your .zshrc/.bashrc/.*rc file:

export RAINFROG_EXPORT=~/Documents

favorites

frequently used queries can be saved as favorites. by default, favorites are written to the application's data directory (the same place that logs are written to), which is one of the following depending on your os, as determined by the directories crate:

PlatformValueExampleLinux$XDG_DATA_HOME/_project_path_ or $HOME/.local/share/_project_path_/home/alice/.local/share/barappmacOS$HOME/Library/Application Support/_project_path_/Users/Alice/Library/Application Support/com.Foo-Corp.Bar-AppWindows{FOLDERID_LocalAppData}\_project_path_\dataC:\Users\Alice\AppData\Local\Foo Corp\Bar App\data

each favorite will be a separate .sql file. you can change the default export location by exporting an environment variable. to make the change permanent, add it to your .zshrc/.bashrc/.*rc file:

export RAINFROG_FAVORITES=~/.config/rainfrog/favorites

roadmap

• scrollable table

• cancellable async querying (spawn tokio task)

• menu list with tables and schemas (collapsible)

• tui-textarea for query editor

• basic tui-textarea vim keybindings

• handle custom types / enums

• display rows affected

• confirm before delete/drop

• table selection and yanking

• multi-line pasting

• editor os clipboard support

• handle mouse events

• keybindings hints at bottom

• branch protection

• vhs explainer gifs

• upgrade ratatui and tui-textarea

• shortcuts to view indexes, keys, etc.

• performant syntax highlighting

• session history

• changelog, release script

• handle explain / analyze output

• show query duration

• install script for bins

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

known issues and limitations

• geometry types are not currently supported

• 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 visual mode, when selecting an entire line, the behavior is not the same as vim's, as it simply 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)