sqsh

English | 日本語

A TUI MySQL client for fast database exploration with fuzzy search, written in Rust.

Features

• Bastion Support: Connect to MySQL through SSH bastion servers with per-connection or shared bastion configuration
• TUI Interface: Interactive terminal UI powered by ratatui
• Fuzzy Finder: Quick connection and table selection with skim (Rust-native fzf)
• TOML Configuration: Manage multiple connections in a single config file
• Connection Pooling: Configurable connection pool with global defaults and per-connection overrides
• Shell Input: Run shell commands from within sqsh (executes on bastion when connected via bastion)
• Read-only Mode: Prevent accidental writes with client-side SQL detection and server-side session enforcement
• Secure: Memory-zeroed password handling, TLS/SSL support, config file permission checks

Installation

Homebrew

brew tap hatohato25/sqsh
brew trust --formula hatohato25/sqsh/sqsh
brew install sqsh

Note: brew trust is required by Homebrew 4.x and later to explicitly trust third-party tap formulae before installation.

Linux / WSL (Windows Subsystem for Linux)

curl -fsSL https://raw.githubusercontent.com/hatohato25/sqsh/main/install.sh | bash

The script automatically detects your architecture, downloads the appropriate binary from GitHub Releases, verifies its checksum, and installs it to /usr/local/bin (with sudo) or ~/.local/bin (without sudo).

From Source

cargo build --release
cp target/release/sqsh /usr/local/bin/

Requirements

• Rust 1.75.0 or later (for building from source)
• MySQL 5.7+ / MariaDB 10.3+

Configuration

Create a configuration file at ~/.config/sqsh/config.toml and restrict its permissions:

chmod 600 ~/.config/sqsh/config.toml

sqsh warns if the file permissions are not 600.

See the Configuration docs for the full settings reference and example configurations. A minimal annotated example is also available in config.example.toml.

Usage

sqsh                          # Start with default config (~/.config/sqsh/config.toml)
sqsh --config /path/to.toml   # Specify a config file
sqsh --verbose                # Enable debug logging
sqsh --readonly               # Start in read-only mode (overrides per-connection settings)
sqsh --lang ja                # Use Japanese display language

Config file search order when --config is not specified:

1. ~/.config/sqsh/config.toml
2. ./config.toml

Note: If you use fish or another non-POSIX shell, the skim-based preview (fuzzy finder preview window) may not render correctly. In that case, prefix the command with SHELL=/bin/bash:

SHELL=/bin/bash sqsh

Key Bindings

See the Key Bindings docs for the full list of key bindings across the connection selector, SQL input, shell input, and result viewer.

Local Testing with Docker

The repository ships with a docker-compose.yml and initialization scripts under docker/init/ that spin up a MySQL 8.0 instance pre-loaded with several sample databases.

Available sample databases

Database	Description
testdb	Basic users / products / orders
ecommerce	Customers, items, transactions, reviews
blog	Authors, posts, comments, tags
analytics	Events (~1M rows), sessions, page views
inventory	Warehouses, products, stock levels, shipments
hr_system	Departments, employees, projects, time entries

Steps

1. Start the MySQL container

docker compose up -d

Wait until the container reports healthy (the init scripts run automatically on first start; the analytics.events table takes a minute to populate ~1M rows):

docker compose ps          # STATUS should show "healthy"

2. Create a config file

mkdir -p ~/.config/sqsh
cp config.example.toml ~/.config/sqsh/config.toml
chmod 600 ~/.config/sqsh/config.toml

Then edit ~/.config/sqsh/config.toml so the local-dev connection points to the Docker instance:

[[connections]]
name = "local-dev"

[connections.mysql]
host     = "127.0.0.1"
port     = 13306          # mapped port in docker-compose.yml
database = "testdb"
user     = "testuser"
password = "testpass"
ssl_mode = "disabled"

3. Launch sqsh

sqsh

Select local-dev from the connection picker and start exploring.

Stopping and cleaning up

docker compose down          # stop containers, keep volume
docker compose down -v       # stop containers and remove volume

Development

# Run all tests
cargo test

# Run integration tests (requires Docker or Podman)
cargo test --test integration_test

License

MIT