README
¶
miu-db
Fast terminal SQL across your databases.
Pick a connection, write SQL, inspect results, stay in your shell.
miu-db is part of the miumono umbrella: small, focused terminal-native
tools that are easy to install, easy to run locally, and predictable in CI.
Quick Start
Install from PyPI:
uv tool install miu-db
miu-db
Try the TUI without a real database:
miu-db --mock=sqlite-demo
Run one query from the CLI:
miu-db query -c local -q "select 1"
Source Install
For local development, install this checkout in editable mode. Code edits apply
the next time you run miu-db.
cd /Users/vanducng/git/personal/miu-db
uv tool install --force --editable ".[all]"
miu-db --mock=sqlite-demo
Re-run the install command after changing dependencies, entry points, or
pyproject.toml.
Connections
Save local connections:
miu-db connections add sqlite --name local --file-path ./app.db
miu-db connections add postgresql --name pg --server localhost --database app --username app
miu-db connections add mysql --name mysql --server localhost --database app --username app
Connect without saving:
miu-db connect sqlite --file-path ./app.db
miu-db postgresql://user:pass@localhost:5432/app
miu-db mysql://root@localhost/app
Manage saved connections:
miu-db connections list
miu-db connections delete local
Passwords are stored in the OS keyring under the miu-db service when possible.
Capabilities
- Terminal UI with explorer, SQL editor, and results grid.
- Vim-style normal/insert modes.
- Per-connection query history.
- Fuzzy filtering over result rows.
- Saved connections with keyring-backed passwords.
- Docker database discovery.
- SSH tunnels.
- Driver install hints when an adapter dependency is missing.
SQLite works out of the box. Optional adapters cover PostgreSQL, MySQL, SQL Server, MariaDB, Oracle, DuckDB, ClickHouse, Snowflake, BigQuery, Athena, Spanner, Turso, D1, Firebird, Redshift, Db2, HANA, Teradata, Trino, Presto, Flight SQL, Impala, SurrealDB, osquery, and more.
Keys
| Key | Action |
|---|---|
i |
Insert mode |
Esc |
Normal mode |
e / q / r |
Focus explorer / query / results |
Enter |
Run statement under cursor |
h |
Query history |
s |
Select top rows from table |
v |
View selected cell |
y / Y |
Copy cell / row |
<space> |
Command menu |
? |
Help |
Ctrl+Q |
Quit |
Config
This is a brand-new miu-db app, not a legacy config alias.
- config:
~/.config/miu/db - override:
MIU_DB_CONFIG_DIR - env vars:
MIU_DB_* - keyring service:
miu-db
miu-db config edit
miu-db config show-keymap
On first run, miu-db copies missing files from ~/.config/sqlit into
~/.config/miu/db so existing saved connections keep working. Existing files
in the new location are never overwritten.
Develop
uv sync --all-extras --dev
uv run miu-db --mock=sqlite-demo
uv run pytest tests/unit/test_config_dir_resolution.py -q
uv run pytest tests/test_sqlite.py -q --timeout=60
Build the package:
uv run python -m build
Release tags use miumono component SemVer:
miu-db-v0.1.5
License
MIT
Directories