Note

pgplex: The Postgres Toolchain for Humans and Agents - pgconsole · pgschema · pgtui · pgparser

Brought to you by Bytebase, open-source database governance platform.

pgtui

A simple terminal UI for PostgreSQL, written in Go with the Bubble Tea framework.

Features • Installation • Quick Start • Keybindings • Configuration • Docs

---

Status: Beta — Core features are stable and ready for daily use. See Roadmap for planned features.

Why pgtui?

If you're anything like me, you love PostgreSQL but hate context-switching between your terminal and a heavy GUI client just to peek at some data. You want something that:

• Stays in your terminal — no Electron, no browser tabs, just your good old terminal
• Respects your muscle memory — Vim-style navigation because your fingers already know the way
• Gets out of your way — connect, browse, filter, done

That's pgtui. Inspired by lazygit, built for developers who live in the terminal.

Features

Database Navigation

Browse your databases, schemas, and tables with a familiar tree structure. Expand, collapse, and jump around with keyboard shortcuts you already know.

Quick Search

Filter table rows instantly with /. Type your search term and watch results update in real-time — simple, fast, and familiar.

JSONB Viewer

Native JSONB support with formatted display, tree navigation, and ready-to-use query snippets.

Command Palette

Quick access to everything via Ctrl+K. Search commands, jump to tables, or access recent queries — all without leaving the keyboard.

SQL Editor

Write and execute SQL directly. Results appear in tabs, so you can run multiple queries and compare results.

And More...

• Query Favorites — Save and organize frequently used queries
• Auto-Discovery — Automatically find local PostgreSQL instances
• Mouse Support — Click, scroll, double-click when you want to
• Connection History — Quick reconnect to recent databases
• Vim Motions — gg, G, Ctrl+D, Ctrl+U, relative line numbers

Installation

Homebrew (macOS/Linux)

brew install pgplex/pgtui/pgtui

Go Install

go install github.com/pgplex/pgtui/cmd/pgtui@latest

Download Binary

Download the latest release from the Releases page.

Build from Source

git clone https://github.com/pgplex/pgtui.git
cd pgtui
make build
./bin/pgtui

Requirements

• Go 1.24+ (for building from source)
• PostgreSQL 12+ (for connecting)

Quick Start

1. Launch pgtui

   pgtui

2. Connect to a database

   • Press c to open the connection dialog
   • Select a discovered instance or enter connection details manually
   • Press Enter to connect

3. Navigate your data

   • Use hjkl or arrow keys to move around
   • Press Enter to expand nodes or select tables
   • Press Tab to switch between panels

4. Search and explore

   • Press / to search and filter rows
   • Press v on a JSONB cell to open the viewer
   • Press Ctrl+K to open the command palette

5. Get help

   • Press ? to see all keyboard shortcuts

Keybindings

Global

Key	Action
Ctrl+K	Open command palette
Ctrl+E	Open SQL editor
Tab	Switch panels
?	Show help
q	Quit

Navigation

Key	Action
hjkl	Move left/down/up/right
g / G	Jump to top/bottom
Ctrl+D / Ctrl+U	Page down/up
Enter	Select / Expand
Esc	Close dialog / Cancel

Data View

Key	Action
/	Search and filter rows
Esc	Clear search
v	Open JSONB viewer (on JSONB cell)
p	Toggle preview pane
s	Sort by column
[ / ]	Previous/Next tab

SQL Editor

Key	Action
Ctrl+S	Execute query
Ctrl+O	Open in external editor
Esc	Close editor

Configuration

pgtui stores configuration in ~/.config/pgtui/:

File	Purpose
config.yaml	UI and behavior settings
connection_history.yaml	Recent connections (auto-saved)
favorites.yaml	Saved SQL queries

Example Config (config.yaml)

ui:
theme: "default"mouse_enabled: truepanel_width_ratio: 25general:
default_limit: 100performance:
query_timeout: 30000

Documentation

• User Guide — Complete usage guide
• Roadmap — Planned features

Contributing

Contributions are welcome! Whether it's bug reports, feature requests, or pull requests — all are appreciated.

# Setup
git clone https://github.com/pgplex/pgtui.git
cd pgtui
make deps
# Development
make build # Build binary
make test# Run tests
make lint # Run linter
make fmt # Format code

Please read DEVELOPMENT.md before submitting a PR.

Star History

Acknowledgments

pgtui wouldn't exist without these amazing projects:

• lazygit — The inspiration for this project
• Bubble Tea — The TUI framework
• Lip Gloss — Terminal styling
• pgx — PostgreSQL driver for Go
• Bubblezone — Mouse support

Sponsor

Bytebase - open source, web-based database DevSecOps platform.