Metadata-Version: 2.5
Name: db-client-tui
Version: 0.1.0
Summary: A terminal UI for SQL Server, PostgreSQL, MySQL, SQLite, Oracle, and more
Project-URL: Homepage, https://github.com/sergey-today/db-client-tui
Project-URL: Repository, https://github.com/sergey-today/db-client-tui
Project-URL: Issues, https://github.com/sergey-today/db-client-tui/issues
Author: Peter, Sergey Anisimov
License-Expression: MIT
License-File: LICENSE
Keywords: database,firebird,mssql,mysql,oracle,postgresql,server,sql,sqlite,terminal,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Requires-Python: >=3.10
Requires-Dist: docker>=7.0.0
Requires-Dist: keyring>=24.0.0
Requires-Dist: pyperclip>=1.8.2
Requires-Dist: sqlparse>=0.5.0
Requires-Dist: textual-fastdatatable==0.19.0
Requires-Dist: textual[syntax]>=6.10.0
Provides-Extra: all
Requires-Dist: adbc-driver-flightsql>=1.0.0; extra == 'all'
Requires-Dist: clickhouse-connect>=0.7.0; extra == 'all'
Requires-Dist: duckdb>=1.1.0; extra == 'all'
Requires-Dist: firebirdsql>=1.3.5; extra == 'all'
Requires-Dist: google-cloud-bigquery; extra == 'all'
Requires-Dist: google-cloud-spanner>=3.0.0; extra == 'all'
Requires-Dist: hdbcli>=2.20.0; extra == 'all'
Requires-Dist: ibm-db>=3.2.0; extra == 'all'
Requires-Dist: impyla>=0.18.0; extra == 'all'
Requires-Dist: libsql>=0.1.0; extra == 'all'
Requires-Dist: mssql-python>=1.1.0; extra == 'all'
Requires-Dist: oracledb>=2.0.0; extra == 'all'
Requires-Dist: osquery>=3.0.0; extra == 'all'
Requires-Dist: paramiko<4.0.0,>=2.0.0; extra == 'all'
Requires-Dist: presto-python-client>=0.8.4; extra == 'all'
Requires-Dist: psycopg2-binary>=2.9.0; extra == 'all'
Requires-Dist: pyathena>=3.22.0; extra == 'all'
Requires-Dist: pymysql>=1.1.0; extra == 'all'
Requires-Dist: redshift-connector; extra == 'all'
Requires-Dist: requests>=2.32.4; extra == 'all'
Requires-Dist: snowflake-connector-python>=3.7.0; extra == 'all'
Requires-Dist: sshtunnel>=0.4.0; extra == 'all'
Requires-Dist: surrealdb>=1.0.0; extra == 'all'
Requires-Dist: teradatasql>=20.0.0; extra == 'all'
Requires-Dist: trino>=0.329.0; extra == 'all'
Provides-Extra: athena
Requires-Dist: pyathena>=3.22.0; extra == 'athena'
Provides-Extra: bigquery
Requires-Dist: google-cloud-bigquery; extra == 'bigquery'
Provides-Extra: clickhouse
Requires-Dist: clickhouse-connect>=0.7.0; extra == 'clickhouse'
Provides-Extra: cockroachdb
Requires-Dist: psycopg2-binary>=2.9.0; extra == 'cockroachdb'
Provides-Extra: d1
Requires-Dist: requests>=2.32.4; extra == 'd1'
Provides-Extra: db2
Requires-Dist: ibm-db>=3.2.0; extra == 'db2'
Provides-Extra: duckdb
Requires-Dist: duckdb>=1.1.0; extra == 'duckdb'
Provides-Extra: firebird
Requires-Dist: firebirdsql>=1.3.5; extra == 'firebird'
Provides-Extra: flight
Requires-Dist: adbc-driver-flightsql>=1.0.0; extra == 'flight'
Provides-Extra: hana
Requires-Dist: hdbcli>=2.20.0; extra == 'hana'
Provides-Extra: impala
Requires-Dist: impyla>=0.18.0; extra == 'impala'
Provides-Extra: mariadb
Requires-Dist: pymysql>=1.1.0; extra == 'mariadb'
Provides-Extra: mssql
Requires-Dist: mssql-python>=1.1.0; extra == 'mssql'
Provides-Extra: mysql
Requires-Dist: pymysql>=1.1.0; extra == 'mysql'
Provides-Extra: oracle
Requires-Dist: oracledb>=2.0.0; extra == 'oracle'
Provides-Extra: osquery
Requires-Dist: osquery>=3.0.0; extra == 'osquery'
Provides-Extra: postgres
Requires-Dist: psycopg2-binary>=2.9.0; extra == 'postgres'
Provides-Extra: presto
Requires-Dist: presto-python-client>=0.8.4; extra == 'presto'
Provides-Extra: redshift
Requires-Dist: redshift-connector; extra == 'redshift'
Provides-Extra: snowflake
Requires-Dist: snowflake-connector-python>=3.7.0; extra == 'snowflake'
Provides-Extra: spanner
Requires-Dist: google-cloud-spanner>=3.0.0; extra == 'spanner'
Provides-Extra: ssh
Requires-Dist: paramiko<4.0.0,>=2.0.0; extra == 'ssh'
Requires-Dist: sshtunnel>=0.4.0; extra == 'ssh'
Provides-Extra: surrealdb
Requires-Dist: surrealdb>=1.0.0; extra == 'surrealdb'
Provides-Extra: teradata
Requires-Dist: teradatasql>=20.0.0; extra == 'teradata'
Provides-Extra: trino
Requires-Dist: trino>=0.329.0; extra == 'trino'
Provides-Extra: trino-gssapi
Requires-Dist: trino[gssapi]>=0.329.0; extra == 'trino-gssapi'
Provides-Extra: trino-kerberos
Requires-Dist: trino[kerberos]>=0.329.0; extra == 'trino-kerberos'
Provides-Extra: turso
Requires-Dist: libsql>=0.1.0; extra == 'turso'
Description-Content-Type: text/markdown

<p align="center">
  <img src="assets/favorites/logo_db-client-tui.png" alt="db-client-tui logo" width="180">
</p>

<h3 align="center">The lazygit of SQL databases</h3>

<p align="center">
  <em>Connect and query your database from your terminal in seconds.</em>
</p>

<p align="center">
  <a href="https://github.com/sergey-today/db-client-tui/stargazers"><img src="https://img.shields.io/github/stars/sergey-today/db-client-tui?style=flat&color=yellow" alt="GitHub Stars"></a>
  <img src="https://img.shields.io/badge/python-3.10+-blue.svg" alt="Python">
  <img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License">
</p>

<p align="center">
  <code>pipx install db-client-tui</code>
</p>

<p align="center">
  <a href="https://www.buymeacoffee.com/PeterAdams"><img src="https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=flat&logo=buy-me-a-coffee&logoColor=black" alt="Buy Me a Coffee"></a>
</p>

---

### Connect
Supports all major databases: SQL Server, PostgreSQL, MySQL, SQLite, MariaDB, FirebirdSQL, Oracle, DuckDB, CockroachDB, ClickHouse, Snowflake, Supabase, CloudFlare D1, Turso, Athena, BigQuery, Spanner, RedShift, IBM Db2, SAP HANA, Teradata, Trino, Presto, Apache Flight SQL, Apache Impala, SurrealDB and osquery.

![Database Providers](docs/demos/demo-providers.gif)

### Query
Syntax highlighting. History. Vim-style keybindings.

![Query History](docs/demos/demo-history.gif)

### Results
Load millions of rows. Inspect data, filter by content, fuzzy search.

![Filter results](docs/demos/demo-filter/demo-filter.gif)

### Docker Discovery
Automatically finds running database containers. Press 'Enter' to connect, db-client-tui figures out the details for you.

![Docker Discovery](docs/demos/demo-docker-picker.gif)

---

## Features

**Connection manager:** Save and switch connections without CLI args

**Just run `db-client-tui`:** No CLI config needed, pick a connection and go

**Multi-database support:** PostgreSQL, MySQL, SQLite, SQL Server, and 10+ more

**Docker integration:** Auto-detect running database containers

**Cloud CLI integration:** Easily browse and connect to your external databases through Azure, AWS and GCP CLI's

**SSH tunnels:** Connect to remote databases securely with password or key auth

**Secure credentials:** Passwords stored in your OS keyring

**Vim-style editing:** Modal editing for terminal purists

**Query history:** Searchable, per-connection history

**Filter results:** Fuzzy search through millions of rows

**Context-aware help:** Keybindings shown on screen

**Browse databases:** Tables, views, procedures, indexes, triggers, sequences

**Autocomplete:** Sophisticated SQL completion engine for tables, columns, and procedures

**CLI mode:** Execute SQL from the command line

**Themes:** Rose Pine, Tokyo Night, Nord, Gruvbox

**Dependency wizard:** Auto-install missing drivers

---

## Motivation

Throughout my career, the undesputed truth was that heavy GUI's like SSMS was the only respectable way to access a database. It didn't matter that I wasn't a DBA, or that I didn't need complex performance graphs. I was expected to install a gigabyte-heavy behemoth that took ages to launch all for the mere purpose of running a few queries to update and view a couple of rows.

When I switched to Linux, I was suddenly unable to return to the devil I know, and I asked myself: _how do I access my data now?_

The popular answer was VS Code's SQL extension. But why should we developers launch a heavy Electron app designed for coding just to execute SQL?

I had recently grown fond of Terminal UI's for their speed and keybinding focus. I looked for SQL TUIs, but the options were sparse. The ones I found lacked the user-friendliness and immediate "pick-up-and-go" nature of tools I loved, like lazygit, and I shortly returning to vscode sql extension.

Something wasn't right. I asked myself, why is it that running SQL queries can't be enjoyable? So I created db-client-tui.

db-client-tui is for the developer who just wants to query their database with a user friendly UI without their RAM being eaten alive. It is a lightweight, beautiful, and keyboard-driven TUI designed to make accessing your data enjoyable, fast and easy like it should be-- all from inside your favorite terminal.

---

## Installation

```bash
# pipx (recommended)
pipx install db-client-tui

# uv
uv tool install db-client-tui

# pip
pip install db-client-tui

# Arch Linux (AUR)
yay -S db-client-tui

# Nix (flake)
nix run github:sergey-today/db-client-tui
```

## Usage

```bash
db-client-tui
```

The keybindings are shown at the bottom of the screen.

### Try it without a database

Want to explore the UI without connecting to a real database? Run with mock data:

```bash
db-client-tui --mock=sqlite-demo
```

### CLI

```bash
db-client-tui -c "MyConnection"
db-client-tui --connection "MyConnection"

# Run a query
db-client-tui query -c "MyConnection" -q "SELECT * FROM Users"

# Output as CSV or JSON
db-client-tui query -c "MyConnection" -q "SELECT * FROM Users" --format csv
db-client-tui query -c "MyConnection" -f "script.sql" --format json

# Create connections for different databases
db-client-tui connections add mssql --name "MySqlServer" --server "localhost" --auth-type sql
db-client-tui connections add postgresql --name "MyPostgres" --server "localhost" --username "user" --password "pass"
db-client-tui connections add mysql --name "MyMySQL" --server "localhost" --username "user" --password "pass"
db-client-tui connections add cockroachdb --name "MyCockroach" --server "localhost" --port "26257" --database "defaultdb" --username "root"
db-client-tui connections add sqlite --name "MyLocalDB" --file-path "/path/to/database.db"
db-client-tui connections add turso --name "MyTurso" --server "libsql://your-db.turso.io" --password "your-auth-token"
db-client-tui connections add firebird --name "MyFirebird" --server "localhost" --username "user" --password "pass" --database "employee"
db-client-tui connections add athena --name "MyAthena" --athena-region-name "us-east-1" --athena-s3-staging-dir "s3://my-bucket/results/" --athena-auth-method "profile" --athena-profile-name "default"
db-client-tui connections add athena --name "MyAthenaKeys" --athena-region-name "us-east-1" --athena-s3-staging-dir "s3://my-bucket/results/" --athena-auth-method "keys" --username "ACCESS_KEY" --password "SECRET_KEY"

# Connect via SSH tunnel
db-client-tui connections add postgresql --name "RemoteDB" --server "db-host" --username "dbuser" --password "dbpass" \
  --ssh-enabled --ssh-host "ssh.example.com" --ssh-username "sshuser" --ssh-auth-type password --ssh-password "sshpass"

# Fetch password from a secrets manager (1Password, pass, Vault, etc.)
db-client-tui connections add postgresql --name "ProdDB" --server "prod.example.com" --username "dbuser" \
  --password-command "op read 'op://Work/prod-db/password'"

# Temporary (not saved) connection
db-client-tui connect sqlite --file-path "/path/to/database.db"

# Connect via URL - scheme determines database type (postgresql://, mysql://, sqlite://, etc.)
db-client-tui postgresql://user:pass@localhost:5432/mydb
db-client-tui mysql://root@localhost/testdb
db-client-tui sqlite:///path/to/database.db

# Save a connection via URL
db-client-tui connections add --url dbtype://user:pass@host/db --name "MyDB"

# Provider-specific CLI help
db-client-tui connect -h
db-client-tui connect supabase -h
db-client-tui connections add -h
db-client-tui connections add supabase -h

# Manage connections
db-client-tui connections list
db-client-tui connections delete "MyConnection"
```

## Keybindings

| Key | Action |
|-----|--------|
| `i` | Enter INSERT mode |
| `Esc` | Back to NORMAL mode |
| `e` / `q` / `r` | Focus Explorer / Query / Results |
| `s` | SELECT TOP 100 from table |
| `h` | Query history |
| `d` | Clear query |
| `n` | New query (clear all) |
| `y` | Copy query (when query editor is focused) |
| `v` / `y` / `Y` / `a` | View cell / Copy cell / Copy row / Copy all |
| `Ctrl+Q` | Quit |
| `?` | Help |

### Vim Motions (Query Editor, NORMAL mode)

Use with operators like `y`, `d`, `c` (e.g. `dw`, `y$`).

| Motion | Action |
|--------|--------|
| `h` / `j` / `k` / `l` | Move cursor left / down / up / right |
| `w` / `W` | Next word / WORD |
| `b` / `B` | Previous word / WORD |
| `0` / `$` | Line start / end |
| `gg` / `G` | File start / end |
| `f{c}` / `F{c}` | Find char forward / backward |
| `t{c}` / `T{c}` | Till char forward / backward |
| `%` | Matching bracket |

### Commands Menu (`<space>`)

| Key | Action |
|-----|--------|
| `<space>c` | Connect to database |
| `<space>x` | Disconnect |
| `<space>z` | Cancel running query |
| `<space>e` | Toggle Explorer |
| `<space>f` | Toggle Maximize |
| `<space>t` | Change theme |
| `<space>h` | Help |
| `<space>q` | Quit |

Autocomplete triggers automatically in INSERT mode. Use `Tab` to accept.

---

## Configuration

Connections and settings are stored in `$XDG_CONFIG_HOME/db-client-tui/` (default: `~/.config/db-client-tui/`). Override the location by setting `DB_CLIENT_TUI_CONFIG_DIR`.

### Custom keybindings

Edit the `keymap.json` file in your db-client-tui config dir. See [`config/keymap.template.json`](config/keymap.template.json) for the full default keymap. Keymap.json need to only contain the overriding keymaps.

## FAQ

### How are sensitive credentials stored?

Connection details are stored in `connections.json` inside the config directory, but passwords are stored in your OS keyring when available (macOS Keychain, Windows Credential Locker, Linux Secret Service).

### How does db-client-tui compare to Harlequin, Lazysql, etc.?

db-client-tui is inspired by [lazygit](https://github.com/jesseduffield/lazygit) - you can just jump in and there's no need for external documentation. The keybindings are shown at the bottom of the screen and the UI is designed to be intuitive without memorizing shortcuts.

Key differences:
- **No need for external documentation** - db-client-tui embrace the "lazy" approach in that a user should be able to jump in and use it right away intuitively. There should be no setup instructions. If python packages are required for certain adapters, db-client-tui will help you install them as you need them.
- **No CLI config required** - Just run `db-client-tui` and pick a connection from the UI
- **Lightweight** - While Lazysql or Harlequin offer more features, I experienced that for the vast majority of cases, all I needed was a simple and fast way to connect and run queries. db-client-tui is focused on doing a limited amount of things really well.

---

## Inspiration

db-client-tui is built with [Textual](https://github.com/Textualize/textual) and inspired by:
- [lazygit](https://github.com/jesseduffield/lazygit) - Simple  TUI for git
- [lazysql](https://github.com/jorgerojas26/lazysql) - Terminal-based SQL client with connection manager

## Contributing

See `CONTRIBUTING.md` for development setup, testing, and CI steps.

### Driver Reference

Most of the time you can just run `db-client-tui` and connect. If a Python driver is missing, `db-client-tui` will show (and often run) the right install command for your environment.

| Database                            | Driver package               | `pipx`                                             | `pip` / venv                                       |
| :---------------------------------- | :--------------------------- | :------------------------------------------------- | :------------------------------------------------- |
| SQLite                              | *(built-in)*                 | *(built-in)*                                       | *(built-in)*                                       |
| PostgreSQL / CockroachDB / Supabase | `psycopg2-binary`            | `pipx inject db-client-tui psycopg2-binary`            | `python -m pip install psycopg2-binary`            |
| SQL Server                          | `mssql-python`               | `pipx inject db-client-tui mssql-python`               | `python -m pip install mssql-python`               |
| MySQL                               | `PyMySQL`                    | `pipx inject db-client-tui PyMySQL`                    | `python -m pip install PyMySQL`                    |
| MariaDB                             | `PyMySQL`                    | `pipx inject db-client-tui PyMySQL`                    | `python -m pip install PyMySQL`                    |
| Oracle                              | `oracledb`                   | `pipx inject db-client-tui oracledb`                   | `python -m pip install oracledb`                   |
| DuckDB                              | `duckdb`                     | `pipx inject db-client-tui duckdb`                     | `python -m pip install duckdb`                     |
| ClickHouse                          | `clickhouse-connect`         | `pipx inject db-client-tui clickhouse-connect`         | `python -m pip install clickhouse-connect`         |
| Turso                               | `libsql`                     | `pipx inject db-client-tui libsql`                     | `python -m pip install libsql`                     |
| Cloudflare D1                       | `requests`                   | `pipx inject db-client-tui requests`                   | `python -m pip install requests`                   |
| Snowflake                           | `snowflake-connector-python` | `pipx inject db-client-tui snowflake-connector-python` | `python -m pip install snowflake-connector-python` |
| Firebird                            | `firebirdsql`                | `pipx inject db-client-tui firebirdsql`                | `python -m pip install firebirdsql`                |
| Athena                              | `pyathena`                   | `pipx inject db-client-tui pyathena`                   | `python -m pip install pyathena`                   |
| BigQuery                            | `google-cloud-bigquery`      | `pipx inject db-client-tui google-cloud-bigquery`      | `python -m pip install google-cloud-bigquery`      |
| Spanner                             | `google-cloud-spanner`       | `pipx inject db-client-tui google-cloud-spanner`       | `python -m pip install google-cloud-spanner`       |
| Apache Arrow Flight SQL             | `adbc-driver-flightsql`      | `pipx inject db-client-tui adbc-driver-flightsql`      | `python -m pip install adbc-driver-flightsql`      |
| Apache Impala                       | `impyla`                     | `pipx inject db-client-tui impyla`                     | `python -m pip install impyla`                     |
| Trino                               | `trino`                      | `pipx inject db-client-tui trino`                      | `python -m pip install trino`                      |
| SurrealDB                           | `surrealdb`                  | `pipx inject db-client-tui surrealdb`                  | `python -m pip install surrealdb`                  |
| osquery                             | `osquery`                    | `pipx inject db-client-tui osquery`                    | `python -m pip install osquery`                    |

### SSH Tunnel Support

SSH tunnel functionality requires additional dependencies. Install with the `ssh` extra:

```bash
# pipx
pipx install 'db-client-tui[ssh]'

# uv
uv tool install 'db-client-tui[ssh]'

# pip
pip install 'db-client-tui[ssh]'
```

If you try to create an SSH connection without these dependencies, db-client-tui will detect this and show you the exact command to install them for your environment.

---

## Star History

[![Star History Chart](https://star-history.dera.page/svg?repos=sergey-today/db-client-tui&type=Date)](https://star-history.dera.page/#sergey-today/db-client-tui&Date)

---

## License

MIT
