https://github.com/undont/seeql
keyboard driven terminal SQL client supporting PostgreSQL, MySQL, and SQLite
https://github.com/undont/seeql
sql tui
Last synced: about 11 hours ago
JSON representation
keyboard driven terminal SQL client supporting PostgreSQL, MySQL, and SQLite
- Host: GitHub
- URL: https://github.com/undont/seeql
- Owner: undont
- License: mit
- Created: 2026-04-13T22:31:41.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-22T20:18:35.000Z (13 days ago)
- Last Synced: 2026-06-25T02:52:48.341Z (10 days ago)
- Topics: sql, tui
- Language: Go
- Homepage:
- Size: 4.23 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
Awesome Lists containing this project
README
# seeql
**Keyboard-driven terminal SQL client for PostgreSQL, MySQL, and SQLite.**
[](https://go.dev)
[](LICENCE)
[]()
[]()
[Quick Start](#quick-start) · [Features](#features) · [Keybindings](#keybindings) · [Configuration](#configuration)
---
## Quick Start
```bash
brew install undont/tap/seeql
```
```bash
seeql # Launch connection manager
seeql postgres://user:pass@host/db # Connect via DSN
seeql ./data.db # SQLite file
```
---
## Features
- **Two-pane layout** with sidebar and results table; the query editor floats on demand
- **Terminal-native theme** that inherits your terminal's colour scheme, with no hardcoded colours
- **Streaming results** with constant memory regardless of result-set size
- **Context-aware autocomplete** for tables, columns, keywords, and functions
- **Multi-tab** with per-tab result sets and queries
- **Connection manager** with DSN-based connections; the adapter is auto-detected from the URL scheme
- **Query history** stored in SQLite, searchable via `Ctrl+H`
- **Audit log** as an opt-in JSON Lines trail
- **Pure Go** with zero CGo dependencies and instant startup
---
## Install
### Homebrew
```bash
brew install undont/tap/seeql
```
### From source
```bash
go install github.com/undont/seeql/cmd/seeql@latest
```
### Build from repo
```bash
git clone https://github.com/undont/seeql.git
cd seeql
make build
```
---
## Keybindings
### Global
| Key | Action |
|-----|--------|
| `Tab` | Cycle focus: sidebar / results |
| `e` | Open query editor |
| `Ctrl+S` | Toggle sidebar |
| `Ctrl+O` | Connection manager |
| `Ctrl+R` | Refresh schema |
| `Ctrl+E` | Export results to CSV |
| `?` / `F1` | Help |
| `q` / `Ctrl+Q` | Quit |
### Editor (floating)
| Key | Action |
|-----|--------|
| `F5` / `Ctrl+G` / `Ctrl+Enter` | Execute query |
| `Ctrl+C` | Cancel running query |
| `Ctrl+H` | Query history |
| `Esc` | Close editor |
### Tabs
| Key | Action |
|-----|--------|
| `Ctrl+T` | New tab |
| `X` | Close tab |
| `Ctrl+]` / `Ctrl+[` | Next / previous tab |
### Sidebar (schema browser)
| Key | Action |
|-----|--------|
| `j` / `k` (or `↓` / `↑`) | Navigate up / down |
| `l` / `Enter` | Expand node / load SELECT into editor |
| `h` | Collapse node |
| `g` / `G` | Jump to top / bottom |
| `F5` / `Ctrl+G` / `Ctrl+Enter` | Execute `SELECT * FROM ` in the current tab |
### Results pane
| Key | Action |
|-----|--------|
| `j` / `k` | Navigate rows |
| `h` / `l` | Scroll columns |
| `P` | Open cell popover (full value) |
### Cell popover
| Key | Action |
|-----|--------|
| `j` / `k` (or `↓` / `↑`) | Scroll one line |
| `g` / `G` | Jump to top / bottom |
| `Ctrl+d` / `Ctrl+u` | Page down / up |
| `/` | Search within cell value |
| `n` / `N` | Next / previous match |
| `y` | Yank displayed value to clipboard (pretty-printed when JSON) |
| `Y` | Yank raw value to clipboard |
| `Esc` / `q` | Close |
### History browser
| Key | Action |
|-----|--------|
| `j` / `k` (or `↓` / `↑`) | Move cursor |
| `g` / `G` | Jump to top / bottom |
| `Ctrl+d` / `Ctrl+u` | Page down / up |
| `Enter` | Run the selected query |
| `e` | Load the selected query into the editor and copy to clipboard |
| `y` | Yank the selected query to the clipboard |
| `/` | Filter queries (type to narrow, `Enter`/`↓` to return to nav, `Esc` clears) |
| `Esc` / `q` / `Ctrl+H` | Close |
---
## Configuration
Config at `~/.config/seeql/config.json`:
```json
{
"keymode": "vim",
"editor": {
"tab_size": 4,
"show_line_numbers": true
},
"results": {
"page_size": 1000,
"max_column_width": 50
},
"connections": [
{
"name": "local pg",
"dsn": "postgres://user:pass@localhost:5432/mydb"
},
{
"dsn": "./data.db"
}
]
}
```
---
## Supported Databases
| Database | Driver | CGo |
|----------|--------|-----|
| PostgreSQL | [pgx](https://github.com/jackc/pgx) | No |
| MySQL | [go-sql-driver/mysql](https://github.com/go-sql-driver/mysql) | No |
| SQLite | [modernc.org/sqlite](https://pkg.go.dev/modernc.org/sqlite) | No |
---
Architecture
```
seeql/
├── cmd/seeql/ # CLI entry point
├── internal/
│ ├── adapter/ # Database adapter interface + drivers
│ │ ├── postgres/
│ │ ├── mysql/
│ │ └── sqlite/
│ ├── app/ # Root Bubble Tea model
│ ├── ui/ # UI components
│ │ ├── sidebar/ # Schema tree browser
│ │ ├── editor/ # SQL editor + syntax highlighting
│ │ ├── results/ # Results table + exporter
│ │ ├── tabs/ # Tab bar
│ │ ├── statusbar/ # Status bar
│ │ ├── autocomplete/ # Autocomplete dropdown
│ │ ├── connmgr/ # Connection manager
│ │ ├── historybrowser/ # Query history overlay
│ │ └── dialog/ # Reusable dialog
│ ├── completion/ # SQL completion engine
│ ├── schema/ # Schema types
│ ├── config/ # JSON config
│ ├── history/ # Query history (SQLite)
│ ├── audit/ # JSON Lines audit log
│ └── theme/ # Adaptive theme (ANSI 16-colour)
├── Makefile
└── .goreleaser.yaml
```
Built with [Bubble Tea](https://github.com/charmbracelet/bubbletea) and [Lip Gloss](https://github.com/charmbracelet/lipgloss).
---
## Licence
[MIT](LICENCE)