pspg: The Table-Aware Pager Your psql Session Has Been Begging For

2026-07-05

You run SELECT * FROM users WHERE ... in psql, the result is 40 columns wide, less wraps every row into unreadable spaghetti, and the header disappears the moment you press space. So you type \pset pager off and squint at 200-line dumps like it's 1994. There is a better answer that predates every fashionable TUI: pspg, the "Postgres Pager" — despite the name it happily eats MySQL, SQLite, CSV, TSV, JSON-lines, and plain aligned text.

Install it (apt install pspg, brew install pspg, dnf install pspg) and wire it into psql:

cat >> ~/.psqlrc <<'EOF'
\pset border 2
\pset linestyle unicode
\setenv PAGER 'pspg --no-mouse -X -b'
EOF

Now every query lands in a pager that understands the table. The header row freezes. The first column freezes. Rows never wrap; you scroll horizontally with the arrow keys. Vim bindings work: / searches, n/N jump, g/G top/bottom, m sets a bookmark you can revisit with '.

Point it at anything tabular:

# CSV with a real header
pspg -f sales.csv --csv

# Tab-separated with custom delimiter
pspg -f logs.tsv --csv --csv-separator=$'\t'

# JSON lines from an API
curl -s https://api.example.com/events | pspg --querystream --format=json

# Live: watch a query result refresh every 2s
pspg --query='SELECT pid,state,query FROM pg_stat_activity' \
     --host=db.internal --dbname=prod --watch 2

That last one is quietly amazing — pspg becomes a mini-dashboard, and you can freeze the view with p to inspect without the refresh yanking your cursor away.

Interactive superpowers most people never discover:

Where does it beat the alternatives?

One trick worth stealing: set it as the pager for mycli, litecli, and even kubectl get -o wide:

alias kwide='kubectl get pods -o wide | pspg --no-mouse -X -b --csv-header=on'

Suddenly a 20-node pod listing is navigable instead of terminal soup.

Key Takeaway: If your daily driver includes psql, mysql, sqlite, or any wide CSV, pspg turns "pager hell" into a frozen-header, sortable, searchable table view with the same key bindings you already know from less.

All newsletters