achristmascarl / rainfrog

🐸 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. | database | tier | known issues | via wire protocol* | | -------- | ---- | ------------ | ------------------ | | postgres | 1 | | | | mysql | 2 | | | | sqlite | 2 | | | | redshift| 2 | | postgres | | duckdb | 4 | musl binaries are not compatible with this driver | | | oracle | 4 | requires 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 • • 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): 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 arch linux arch linux users can install from the official repositories using pacman: termux if you are using termux, you'll need to install rust via their package manager: and then make sure to install with termux features (and disable default features): nix conda 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. install script there is a simple install script that assists in downloading and unpacking a binary from the release page to , which you might want to add to your 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 to see the "host" target), and the script also needs jq and fzf installed to run. release page binaries • 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 to see the "host" target) • move the binary to a folder in your 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 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. with connection url the must include all the necessary options for connecting to the database (ex. ). it will take precedence over all connection options. with environment variables if is not present, rainfrog will first check your environment variable, then it will check for in a file in the current directory or a parent directory. for postgres and mysql, you can run it by specifying all of the options as environment variables: if you want to provide a custom combination of options and omit others, you can override the Dockerfile's CMD like so: since sqlite is file-based, you may need to mount a path to the sqlite db as a volume in order to access it: running drivers which have runtime dependencies (like oracle) via docker is not currently supported. customization rainfrog can be customized by placing a file in one of the following locations depending on your os, as determined by the directories crate: | Platform | Value | Example | | -------- | ----------------------------------------------------------------------- | ------------------------------------------------------------- | | Linux | / or /.config/ | /home/alice/.config/barapp | | macOS | /Library/Application Support/ | /Users/Alice/Librar…