vizgres

A fast, keyboard-driven PostgreSQL client for the terminal.

Features

• Schema Browser: Navigate schemas, tables, views, functions, indexes with expand/collapse
• SQL Editor: Multi-line editing with syntax highlighting, autocomplete, undo/redo
• Query Execution: Run queries with configurable timeout, cancel running queries, streaming row counter
• EXPLAIN ANALYZE: One-key query plan analysis with visual tree viewer and color-coded timing
• Results Viewer: Scrollable table with auto-pagination, cell-level navigation, resizable columns, and NULL styling
• Inspector: Full cell content viewer with JSON pretty-printing
• Export: Save results as CSV or JSON
• Query History: Navigate previous queries with Ctrl+Up/Down
• Multi-Tab: Work with multiple queries simultaneously
• Connection Profiles: Save and manage database connections
• Auto-Reconnect: Per-tab transparent reconnection on connection loss
• Read-Only Mode: Per-connection write protection with destructive query confirmation
• Color Themes: Dark, light, midnight, and ember themes
• Meta-Commands: psql-style \dt, \dv, \di, \dn, \d table
• Large Schema Support: Pagination for databases with 10k+ tables

Install

# From crates.io
cargo install vizgres

# From source
cargo install --path .

Requires Rust 1.93+ (2024 edition). Tested against PostgreSQL 18; compatible with PostgreSQL 11+.

Usage

# Connect via URL
vizgres postgres://user:pass@localhost:5432/mydb

# Connect to saved profile
vizgres myprofile

# Connect via DATABASE_URL (common in containers/PaaS)
export DATABASE_URL=postgres://user:pass@localhost:5432/mydb
vizgres

# Connect via PG* environment variables
export PGDATABASE=mydb PGHOST=localhost PGUSER=me
vizgres

# Interactive connection dialog (when no target or env vars)
vizgres

Keybindings

Press ? in-app for full keybinding help. All keybindings are configurable in ~/.vizgres/config.toml.

Global

Key	Action
Tab / Shift+Tab	Cycle focus between panels
Ctrl+Q	Quit
Ctrl+P	Open command bar
?	Show help
Ctrl+T	New tab
Ctrl+W	Close tab
Ctrl+Tab	Next tab

Editor

Key	Action
F5 / Ctrl+Enter	Execute query
Ctrl+E	EXPLAIN ANALYZE
Ctrl+L	Clear editor
Ctrl+Z	Undo
Ctrl+Shift+Z	Redo
Ctrl+Alt+F	Format SQL
Ctrl+Up/Down	Query history
Tab	Cycle autocomplete suggestions
Right	Accept autocomplete
Escape	Cancel running query

Schema Tree

Key	Action
j/k or ↑/↓	Navigate
Enter	Expand / Preview table data
Space	Toggle expand
h	Collapse / go to parent
/	Filter tree
y	Copy qualified name
d	Show table definition (DDL)

Results

Key	Action
j/k or ↑/↓	Navigate rows
h/l or ←/→	Navigate columns
Enter	Open inspector
v	Toggle view mode (vertical / explain tree↔text)
Shift+H / Shift+L	Narrow / Widen column
Shift+R	Reset column widths
y	Copy cell
Y (Shift+y)	Copy row
Ctrl+S	Export as CSV
Ctrl+J	Export as JSON
g/G	Jump to first/last row
n	Next page
p	Previous page

Commands

Open the command bar with Ctrl+P:

Command	Action
/connect [url]	Connect to database
/refresh	Reload schema
/save-query [name]	Save current query
/clear	Clear editor
/help	Show help
/quit	Quit

Meta-Commands

Type in the editor and execute (like psql):

Command	Action
\dt	List tables
\dv	List views
\di	List indexes
\dn	List schemas
\d <table>	Describe table (columns, indexes, constraints, triggers)

Configuration

Settings are stored in ~/.vizgres/config.toml:

# Color theme: dark, light, midnight, ember
theme = "dark"

# Query timeout in milliseconds (0 = no timeout)
query_timeout_ms = 30000

# Maximum rows to fetch (0 = unlimited)
max_result_rows = 10000

# Items per category in tree (0 = unlimited)
tree_category_limit = 500

# Query history size
history_size = 500

# Custom keybindings
[keybindings.editor]
"ctrl+enter" = "execute_query"

[keybindings.results]
"ctrl+c" = "copy_cell"

Connection profiles are stored in ~/.vizgres/connections.toml. If you store passwords there, restrict file permissions:

chmod 600 ~/.vizgres/connections.toml

Manage config: vizgres config edit, vizgres config list, vizgres config path.

Sample Database

A script is included to load the IMDb non-commercial dataset (~200M rows across 7 tables) into the local Docker/Podman PostgreSQL. Useful for testing vizgres against a realistic workload:

# Start PostgreSQL and load IMDb data (~1.5 GB download, takes a few minutes)
just db-up
just imdb-load

# Connect
vizgres postgres://test_user:test_password@localhost:5433/imdb

# Clean up when done
just imdb-clean

Downloaded files are cached in .imdb-data/ and reused if less than 24 hours old.

License

MIT