PostgresTUI Documentation

Installation

PostgresTUI is a single compiled binary built with Rust. It includes both a terminal (TUI) interface and an embedded web UI in the same binary. No runtime, no dependencies, no installer — one file you drop on PATH. Open source (GPL-3.0).

Download

• Pre-built binary: buy the binary ($4.99 one-time) — macOS aarch64, Linux x86_64, Windows x86_64
• One-line install (pre-built):

sudo curl -L -o /usr/local/bin/postgrestui https://dl-postgrestui.voltrus.id/latest && sudo chmod +x /usr/local/bin/postgrestui

• Build from source (free): GitHub repo — cargo build --release
• Product page: /postgrestui/

System Requirements

First Launch

The binary is self-contained (~5 MB). On macOS, the first run of a downloaded unsigned binary may be blocked by Gatekeeper — run xattr -d com.apple.quarantine /usr/local/bin/postgrestui once to clear it.

Quick Start

1. Connect to a local database (30 seconds)

The most common path — browsing a local or Docker Postgres.

postgrestui -s localhost -p 5432 -d mydb -u postgres

1. The TUI opens with a sidebar of Tables and Views, each with a live row count.
2. Press j/k (or arrow keys) to move, Enter to open a table.
3. The paginated data view loads 500 rows at a time — Prev/Next with u/d.

2. Run an ad-hoc SQL query

1. Switch to the Query tab.
2. Type a query — autocomplete fires on SQL keywords, table names, and columns.
3. Press Ctrl+S to execute. Results render in the paginated view.

SELECT customer_id, SUM(total) AS spent
FROM orders
WHERE created_at >= NOW() - INTERVAL '30 days'
GROUP BY customer_id
ORDER BY spent DESC
LIMIT 50;

3. Export results as CSV / JSON / SQL

From the export menu on any table or query result, pick CSV (Excel-ready), JSON (API-ready), or SQL (INSERT statements). Export the full table or just the current 500-row page.

4. Launch the Web UI instead

Prefer a browser? Add --ui and PostgresTUI starts a local HTTP server on port 5000 with a full dark-theme interface — same browsing, querying, and export, in a tab.

postgrestui -s localhost -d mydb -u postgres --ui

Configuration

Connection Flags

Modes

Managed & cloud Postgres

Connect to any endpoint the same way — point -s at the host and supply credentials. Works with AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL, Supabase, Neon, Render, and self-hosted Docker containers. For TLS-only providers, the binary negotiates SSL automatically.

TUI Keybindings

Key Features

Single binary, zero dependencies

One ~5 MB file. No libpq, no Java, no Electron, no Docker image. Drop it on a server over SSH and you have a full database browser in milliseconds — far faster than waiting for pgAdmin or DBeaver to load.

Table & view browser with row counts

Sidebar navigation lists every table and view with pre-fetched row counts. Instant / search filters the list. Switch between Tables and Views in one keystroke.

Paginated data + horizontal scroll

Large tables load 500 rows per page — no terminal-flooding SELECT * dumps. Wide tables (30+ columns) scroll horizontally so nothing is truncated.

SQL editor with autocomplete

Interactive editor with autocomplete on keywords, table names, and columns, plus syntax highlighting. Errors render inline next to the failing statement.

Multi-format export

Export any table or query result as CSV (Excel-ready), JSON (API-ready), or SQL INSERT statements — full table or current page, from either the TUI or the Web UI.

SSH-friendly

Because it's a pure TUI, PostgresTUI works perfectly over an SSH session to a remote or air-gapped server — no X11 forwarding, no VNC, no GUI installed on the box.

Troubleshooting

Connection refused / timeout

Symptom: "connection refused" or the TUI hangs on launch.
Fix: Confirm the host listens on the port and is reachable. From a shell:

nc -zv db.example.com 5432

If nc fails, check the security group / firewall (RDS and Cloud SQL block 5432 by default to the public internet), the VPC, and that the Postgres process is up.

"FATAL: password authentication failed"

Symptom: Auth fails with a valid-looking password.
Fix: Most often a copied-and-pasted password with trailing whitespace, or the wrong auth method. Confirm the user's pg_hba.conf line allows the connection source and method (md5/scram-sha-256). For managed Postgres, verify the master password in the console.

"database does not exist"

Symptom: "FATAL: database \"mydb\" does not exist".
Fix: The -d value must be an existing database. Connect to postgres (the default maintenance DB) first, then list databases with SELECT datname FROM pg_database; and reconnect with the right one.

SSL required by server

Symptom: "no PostgreSQL user name specified" or an SSL/handshake error on a cloud provider.
Fix: Cloud providers (RDS, Cloud SQL, Supabase) require TLS. The binary negotiates SSL by default; if you disabled it, re-enable SSL for that connection. For self-signed certs, use the trust-cert flag for that session.

Wide table columns truncated in TUI

Symptom: Long text columns appear cut off in the terminal.
Fix: Use horizontal scroll (the TUI supports it), or switch to the Web UI (--ui) where the browser gives you native horizontal scrolling and wider cells.

macOS blocks the binary on first run

Symptom: "postgrestui cannot be opened because the developer cannot be verified."
Fix: Clear the quarantine attribute once: xattr -d com.apple.quarantine /usr/local/bin/postgrestui. Or build from source — a self-built binary is not quarantined.

Related Articles

Guides on terminal database browsers and PostgreSQL workflows.

See also: Terminal Database Browsers — Why CLI Tools Beat pgAdmin and SSMS for Daily Work

Support

• Email: support@voltrus.id
• Product page: /postgrestui/
• Source: github.com/dzulfikar08/postgrestui

When reporting an issue, include the OS, the Postgres version, whether it's managed or self-hosted, and the exact command and error output.