pspg: a table-aware pager for psql, mysql and pgcli

Why psql needs a pager that knows about columns

The README opens with the observation that everybody who uses psql also uses the less pager, and that less, while it works well, has no special support for tabular data. That is the whole problem statement. A wide result set in less is a wall of text: the header row scrolls away as soon as you move down, there is no way to hold a key column in place while you look at the right-hand columns, and there is no notion of a row or a column to sort by. The author states that he looked at a few existing projects and found none good enough for the purpose, so he wrote a specialised pager for psql.

The intended user is therefore someone who already lives in a terminal SQL client. The README lists the clients pspg can serve: psql, mysql, sqlite, pgcli, monetdb, Trino, usql, sqlcl for Oracle, and nushell. PostgreSQL is the primary target, but the pager is not tied to it. The project also describes itself as usable as a CSV or TSV viewer, which follows from the same problem: a CSV file is a table, and less treats it as a stream of characters.

What pspg actually does with the rows it receives

The mechanism is a pager that parses its input into a table instead of treating it as opaque text. The repository layout shows the split: src/ contains print.c, table.c, csv.c, sort.c, export.c, unicode.c, themes.c, pgclient.c and related files, and the Makefile compiles them into the pspg binary. The --help output describes the program as "a Unix pager designed for table browsing" and its usage as pspg [OPTION] [file].

From there, the features follow the table model. The README's main target list names the ability to freeze the first few rows or the first few columns, sorting by a specified numeric column, themes such as mcview and FoxPro, mouse support, and copying a selected range to the clipboard. The command line exposes the same ideas: -c or --freezecols=N freezes N columns between 0 and 9, --border selects one of three border types, --double-header uses double lines for the header separator, --line-numbers adds a line number column, and --vertical-cursor shows a vertical column cursor. Input format is inferred, or forced with --csv, --tsv, --csv-separator and --csv-header, and --ignore_file_suffix disables deduction from the file suffix.

Two behaviours matter for interactive use. First, pspg watches the file it has open, with --no-watch-file disabling the inotify event handling, and it reads input forever with --stream or --querystream. Second, --only-for-tables makes pspg fall back to the standard pager when the content is not a table, which is the setting to reach for if you want to keep less for everything except query output. Search options are separate: -i ignores case in searches that do not contain uppercase, -I ignores case in all searches, and -g and -G control whether matching lines are highlighted.

Installing pspg and pointing psql at it

The README gives package installs for three systems. On Debian or Ubuntu the package is in the distribution repositories, and the same is true for RedHat or Fedora. Homebrew covers macOS.

# Debian (Ubuntu)
sudo apt-get install pspg

# RedHat (Fedora)
sudo dnf install pspg

# macOS
brew install pspg

After installing, the basic configuration is a single environment variable. The README says to set PSQL_PAGER to pspg, and gives a variant with two options: -X to preserve content after exit and -b for the black and white theme.

export PSQL_PAGER='pspg -X -b'

With that exported, running psql and executing a query should open the result in pspg rather than less. The README notes that options given on the command line have higher priority than options in the configuration file ~/.pspgconf, so a flag in PSQL_PAGER overrides the same setting written to the config file. A first real use is to run a query with more columns than fit on screen, then freeze the leading columns so the identifying column stays visible while you scroll right. The flag for that is -c, for example -c 2 to freeze two columns, and the README also documents --freezecols=N for the same purpose. Sorting is described in the README as being by a specified numeric column, so it is not a general text sort. If a query returns something that is not a table, --only-for-tables hands the content back to the standard pager instead of trying to render it.

Where pspg gets in the way

The clearest limitation is platform support. The README states plainly that native installation on MS Windows is not supported, and that pspg works well inside wsl2, where installation is the same as on the Linux system underneath. If your team runs psql from PowerShell or a native Windows terminal without WSL, this project does not cover you.

There are smaller trade-offs in the option set. Sorting is tied to a numeric column rather than arbitrary text, so ordering by a name column is not what the feature is for. Column freezing stops at 9, which is a real ceiling for very wide schemas. The pager also takes over mouse handling by default, with --no-mouse and --no_xterm_mouse_mode available to turn that off, and it beeps when scrolling is not possible unless --no-sound is set. Several options exist purely to work around other tools: --pgcli-fix is described as an attempt to fix some pgcli related issues, which is a sign that pspg sits in a pipeline it does not fully control. And because pspg is a pager, it renders what the client sends. It is not a query tool, it does not hold a database connection for you, and it cannot fix output that the client has already truncated.

pspg against less and against the client's own formatting

The obvious alternative is less, and the difference is not cosmetic. less is a general-purpose pager that treats input as a stream of lines; it has no concept of a header row, so it cannot keep one on screen, and no concept of a column, so it cannot freeze or sort one. pspg parses the same input as a table and builds its interface around that structure. The cost of that choice is that pspg is a narrower tool: it is built for tables and has an explicit escape hatch, --only-for-tables, for content that is not one.

The second alternative is not a different pager but a different place to format the table. Clients such as psql can be configured to expand output, and pgcli brings its own formatting and completion. The README's own position is that pspg complements pgcli rather than replacing it: pgcli is listed among the supported clients, and --pgcli-fix exists to smooth over pgcli-specific behaviour. So the choice is not pspg or pgcli. It is whether the thing that draws the table on screen should be the client or a separate pager process that understands rows and columns. pspg takes the second position, and it also works as a CSV or TSV viewer, which a client-embedded formatter does not.

Maintenance, licence and what an upgrade costs

The repository is not archived, and its last push was on 2026-09-21, which is recent. Releases are frequent and closely numbered: 5.8.14 on 2025-12-18, 5.8.15 on 2026-01-23, and 5.8.16 on 2026-02-18. That pattern suggests small, incremental changes rather than long gaps, and the version numbering means upgrades are unlikely to require configuration rewrites. The practical upgrade cost is low for most users because the interface is a command line and an environment variable. If you pin the version in PSQL_PAGER with specific flags, an upgrade can change defaults, so the flags you rely on are worth keeping explicit.

The licence is BSD-2-Clause, a permissive licence. The repository also contains a SECURITY.md and a pspg.spec file, the latter being the RPM spec used for Fedora packaging. Because pspg is distributed through Debian, Fedora and Homebrew, many users will receive it as a distribution package rather than building from source; the Makefile and configure script are present for anyone who does build it. This is a description of what the repository contains, not legal advice, and anyone redistributing pspg should read the LICENSE file themselves. The README also carries a Stand With Ukraine banner, which is a statement by the project rather than a technical property.

Editorial conclusion

Adopt pspg if you spend the day reading wide result sets in psql, pgcli, mysql or sqlite and you want frozen headers, frozen columns, sorting and a clipboard copy without leaving the terminal. Skip it if you need a native Windows build, since the README states that native installation on MS Windows is not supported and points to wsl2 instead, or if your pager use is mostly log files rather than tables. Before rolling it out, check that PSQL_PAGER is honoured by your client, confirm your terminal handles the mouse and colour modes you plan to use, and read the --help output for the option set of the version your distribution ships.

Frequently asked questions

Official sources

1. Issues
2. License: BSD-2-Clause
3. okbob/pspg on GitHub
4. README
5. Releases