gotermsql

KO | EN

gitlite — search

#javascript #python #java #ruby #c-plus-plus #nodejs #c-sharp #backup #jonschlinkert #json #node #php

★ 30 Open GitHub ↗

A full-featured terminal SQL IDE in Go. Supports PostgreSQL, MySQL, SQLite, and DuckDB. Features schema browser, autocomplete, syntax highlighting, vim keybindings, and single-binary distribution.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# gotermsql

[![Go Report Card](https://goreportcard.com/badge/github.com/sadopc/gotermsql)](https://goreportcard.com/report/github.com/sadopc/gotermsql)
[![Go Reference](https://pkg.go.dev/badge/github.com/sadopc/gotermsql.svg)](https://pkg.go.dev/github.com/sadopc/gotermsql)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://raw.githubusercontent.com/sadopc/gotermsql/main/LICENSE)
[![Latest Release](https://img.shields.io/github/v/release/sadopc/gotermsql)](https://github.com/sadopc/gotermsql/releases)

A full-featured terminal SQL IDE written in Go. Single binary, zero config, multi-database.

![demo](https://raw.githubusercontent.com/sadopc/gotermsql/main/demo.gif)

## Why gotermsql?

| | gotermsql | pgcli/mycli | usql | lazysql | Harlequin |
|---|---|---|---|---|---|
| Single binary, zero deps | **Yes** | No (Python) | Yes (Go) | Yes (Go) | No (Python) |
| Multi-database | **4 databases** | 1 each | Many (CLI only) | 3 | 10+ (plugins) |
| Schema browser | **Yes** | No | No | Yes | Yes |
| Autocomplete | **Context-aware** | Yes | No | No | Yes |
| Streaming large results | **Yes** | No | No | No | Yes (Arrow) |
| Vim keybindings | **Full modal** | Partial | No | No | Limited |
| Syntax highlighting | **Yes** | Yes | No | No | Yes |
| Multi-tab editing | **Yes** | No | No | No | Yes |
| Instant startup | **Yes** | No | Yes | Yes | No |

- **Single binary, zero dependencies** — no Python, no Node, no Docker. Download and run.
- **Instant startup** — compiled Go, not an interpreted runtime.
- **Multi-database with one tool** — PostgreSQL, MySQL, SQLite, DuckDB.
- **Streaming results** — query billion-row tables without running out of memory.
- **Real vim mode** — full Normal/Insert/Visual modal editing, not just hjkl remaps.
- **Batch schema introspection** — PostgreSQL and MySQL load schemas in 3 queries, not N+1 per table.

## Features

- **Multi-database support** - PostgreSQL, MySQL, SQLite, DuckDB (optional build tag)
- **Schema browser** - Hierarchical tree view with databases, schemas, tables, columns
- **SQL editor** - Syntax highlighting, line numbers, multi-tab editing
- **Autocomplete** - Context-aware completions for tables, columns, keywords, functions
- **Results viewer** - Tabular display with row count, query timing, and export support
- **Streaming results** - SELECT queries stream via paginated iterator, keeping memory constant even for millions of rows
- **Vim keybindings** - Toggleable vim/standard mode (F2)
- **Connection manager** - Save, edit, and manage database connections
- **Query history** - SQLite-backed local history with search (Ctrl+H)
- **Audit log** - Opt-in JSON Lines audit trail for compliance (query, adapter, duration, row count, sanitized DSN)
- **Export** - CSV and JSON export of query results (Ctrl+E)
- **Resizable panes** - Adjust sidebar width and editor/results split with Ctrl+Arrow keys
- **Single binary** - Pure Go, zero CGo by default, cross-platform

## Install

### Homebrew (macOS/Linux)

```bash
brew install sadopc/tap/gotermsql
```

### From source

```bash
go install github.com/sadopc/gotermsql/cmd/gotermsql@latest
```

### Pre-built binaries

Download from [GitHub Releases](https://github.com/sadopc/gotermsql/releases) for Linux, macOS, and Windows.

### Build from repo

```bash
git clone https://github.com/sadopc/gotermsql.git
cd gotermsql
make build
# Binary is at bin/gotermsql
```

### With DuckDB support (requires CGo)

```bash
make build-full
```

## Usage

```bash
# Launch with connection manager
gotermsql

# Connect via DSN
gotermsql postgres://user:pass@localhost:5432/mydb

# SQLite file
gotermsql --adapter sqlite --file ./data.db

# MySQL with flags
gotermsql --adapter mysql -H localhost -u root -d mydb

# PostgreSQL with individual flags
gotermsql --adapter postgres -H localhost -p 5432 -u admin -d production
```

## Keybindings

### Navigation

| Key | Action |
|-----|--------|
| `Tab` | Cycle focus: Editor -> Results -> Sidebar |
| `Shift+Tab` / `Ctrl+J` | Cycle focus backwards |
| `Alt+1/2/3` | Jump to Sidebar/Editor/Results |
| `Ctrl+Arrow` | Resize panes |

### Editor

| Key | Action |
|-----|--------|
| `Ctrl+Enter` / `F5` / `Ctrl+G` | Execute query |
| `Ctrl+C` | Cancel running query |
| `Ctrl+Space` | Force autocomplete |
| `Esc` | Dismiss autocomplete |

### Tabs

| Key | Action |
|-----|--------|
| `Ctrl+T` | New tab |
| `Ctrl+W` | Close tab |
| `Ctrl+]` | Next tab |
| `Ctrl+[` | Previous tab |

### Application

| Key | Action |
|-----|--------|
| `Ctrl+Q` | Quit |
| `Ctrl+B` | Toggle sidebar |
| `Ctrl+R` | Refresh schema |
| `Ctrl+O` | Connection manager |
| `Ctrl+H` | Query history |
| `Ctrl+E` | Export results |
| `F1` | Help |
| `F2` | Toggle vim/standard mode |

## Configuration

Config file is stored at `~/.config/gotermsql/config.yaml`:

```yaml
theme: default
keymode: standard  # "vim" or "standard"
editor:
  tab_size: 4
  show_line_numbers: true
results:
  page_size: 1000
  max_column_width: 50
audit:
  enabled: false     # set to true to enable audit logging
  path: ""           # defaults to ~/.config/gotermsql/audit.jsonl
  max_size_mb: 50    # rotate at 50 MB (0 = no rotation)
connections:
  - name: local-pg
    adapter: postgres
    dsn: postgres://user:pass@localhost:5432/mydb
```

### Audit Log

When enabled, gotermsql writes a JSON Lines audit trail of every query execution. Each line contains the timestamp, full query text, adapter, database name, duration, row count, error status, and sanitized DSN (credentials stripped). This is suitable for shipping to SIEM or log aggregators.

```jsonl
{"timestamp":"2026-02-13T18:23:24Z","query":"SELECT * FROM users","adapter":"postgres","database_name":"mydb","duration_ms":42,"row_count":5,"is_error":false,"dsn":"postgres://%2A%2A%2A@host:5432/mydb"}
```

The log file rotates automatically when it exceeds `max_size_mb`, keeping one backup (`.1` suffix).

## Supported Databases

| Database | Driver | CGo Required |
|----------|--------|-------------|
| 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 |
| DuckDB | [go-duckdb](https://github.com/marcboeker/go-duckdb) | Yes (build tag: `-tags duckdb`) |

Default builds are 100% pure Go with zero CGo dependencies.

## Architecture

```
gotermsql/
├── cmd/gotermsql/          # CLI entry point (cobra)
├── internal/
│   ├── adapter/            # Database adapter interface + implementations
│   │   ├── postgres/       # PostgreSQL (pgx)
│   │   ├── mysql/          # MySQL (go-sql-driver)
│   │   ├── sqlite/         # SQLite (modernc.org)
│   │   └── duckdb/         # DuckDB (optional, build tag)
│   ├── app/                # Root Bubble Tea model, keymaps, messages
│   ├── 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 modal
│   │   └── dialog/         # Reusable dialog component
│   ├── completion/         # SQL completion engine
│   ├── schema/             # Unified schema types
│   ├── config/             # YAML config management
│   ├── history/            # Query history (SQLite-backed)
│   ├── audit/              # JSON Lines audit log
│   └── theme/              # Theme definitions (Lip Gloss)
├── Makefile
└── .goreleaser.yaml
```

Built with [Bubble Tea](https://github.com/charmbracelet/bubbletea), [Lip Gloss](https://github.com/charmbracelet/lipgloss), and [Bubbles](https://github.com/charmbracelet/bubbles).

## Neovim Integration

Use [gotermsql.nvim](https://github.com/sadopc/gotermsql.nvim) to launch gotermsql in a floating terminal window inside Neovim:

```lua
-- lazy.nvim
{
  "sadopc/gotermsql.nvim",
  keys = {
    { "<leader>db", "<cmd>Gotermsql<cr>", desc = "Toggle gotermsql" },
  },
  opts = {},
}
```

## Development

```bash
# Run tests
make test

# Run with race detector
make test-race

# Build and run
make run ARGS="--adapter sqlite --file demo.db"

# Format code
make fmt

# Vet
make vet
```

## License

MIT

gotermsql

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README