perk-workbench

Perk Workbench

A terminal UI for exploring databases. Built with Bubble Tea.

  ┌─────────────────────────────────────────────┐
  │  perk-workbench chinook-sqlite.db           │
  │                                             │
  │  ┌── Schema ─────┐ ┌── Workspace (tab) ───┐│
  │  │  artists       │ │ SELECT * FROM        ││
  │  │  albums        │ │ artists LIMIT 5;     ││
  │  │  tracks        │ │                      ││
  │  │  ...           │ │ ┌─ Results ────────┐││
  │  │                │ │ │ 1 | AC/DC        │││
  │  │                │ │ │ 2 | Accept       │││
  │  └────────────────┘ │ └──────────────────┘││
  │                      └─────────────────────┘│
  └─────────────────────────────────────────────┘

Quick start

npx perk-workbench path/to/database.db

Or install globally:

npm install -g perk-workbench
perk-workbench path/to/database.db

Connect to MySQL, PostgreSQL, and MongoDB:

perk-workbench 'mysql:user:pass@tcp(host:3306)/db'
perk-workbench 'postgres://user:pass@host:5432/db'
perk-workbench 'mongodb://user:pass@host:27017/db'

MongoDB connections accept mongosh-style statements in the query editor (db.restaurants.find({"borough": "Bronx"}).limit(5), countDocuments, aggregate, distinct, writes, and index DDL); the schema pane lists collections, and the structure tab shows fields sampled from the collection.

Or configure the connection with Laravel-compatible environment variables, then launch without an argument:

export DB_CONNECTION=mysql
export DB_HOST=127.0.0.1
export DB_PORT=3306
export DB_DATABASE=office
export DB_USERNAME=root
export DB_PASSWORD=secret
perk-workbench

Accepted DB_CONNECTION values are sqlite, mysql, and pgsql. SQLite requires DB_DATABASE; remote ports default to 3306 (MySQL) and 5432 (pgsql). A database argument passed on the command line overrides these variables. A .env file in the working directory is read as a fallback; real environment variables take precedence over it, and a command-line argument overrides both.

Credential storage

Connection profiles are saved to connections.json under your user config directory (~/.config/perk-workbench/). Literal passwords are encrypted at rest with AES-256-GCM using a key in secret.key inside the same directory; each ciphertext is bound to its profile and field, and the directory and files are locked down to 0700/0600. Connection targets that carry credentials — redis://user:pass@host, mongodb://user:pass@host/db, postgres://user@host/db?password=…, mysql:user:pass@tcp(host:3306)/db — are encrypted the same way; non-credential targets (file paths, database names) stay plaintext and readable.

Threat model. The key and the ciphertext live under the same user-owned directory, so encryption protects against accidental disclosure and copies of your config (backups, shared screenshots, misplaced files) — not against an attacker with your account access, who can read both. Env and file references are the stronger separation:

perk-workbench                # with DB_PASSWORD set, or
# ${MY_PASSWORD} / file:///path/to/secret in the connection form

A stored password that cannot be decrypted (tampered file, replaced key) is never shown as plaintext and is never rewritten: the app reports it and refuses to save until you re-enter the value, so a transient key problem cannot silently destroy your stored ciphertext.

Features

Architecture

cmd/perk-workbench/    CLI entry point
internal/
├── workbench/         Bubble Tea models, layout, keybindings
├── core/              Workflow state machine (query lifecycle, focus, tabs)
├── database/          Connection dispatcher (routes DSN to driver)
├── sql/               Shared types & contracts (Service, Column, Rows)
├── sqlite/            SQLite driver (modernc.org/sqlite, no CGO)
├── mysql/             MySQL driver
├── postgres/          PostgreSQL driver
├── mongodb/           MongoDB driver (mongosh-style statements)
├── chrome/            Stateless terminal rendering helpers
├── ai/                AI clients (OpenAI, Anthropic, Gemini)
├── clipboard/         System clipboard access
└── log/               Event logging

Development

go test -race ./cmd/... ./internal/...
go vet ./cmd/... ./internal/...
go build ./cmd/perk-workbench
gofmt -l cmd internal

The build version is injected explicitly — never baked in:

go build -ldflags "-X main.version=<version>" ./cmd/perk-workbench
perk-workbench --version

--version prints perk-workbench <version>; a build without the injection honestly reports perk-workbench devel. The injected version is carried into the plugin test evidence document (host_version), so release evidence names the exact host build.

Demo databases for testing:

make sqlite      # Chinook (SQLite)
make mysql       # Office demo (MySQL)
make postgres    # Employees demo (PostgreSQL)
make mongo       # Restaurants demo (MongoDB)

License

MIT