You open \dt+ in psql and want the tables sorted by size. The operation sounds small, but adding syntax to a standard meta-command turns it into a design decision that affects every user.

On August 26, 2026, Pavel Stěhule presented an experimental patch that embeds Lua in psql and lets users define commands such as \my.dt. Instead of choosing one sorting design for the standard command, it provides an extension point and moves that choice into a script.

This is not a released PostgreSQL feature. The useful questions are what this extension model enables, how it relates to the long-running discussion around size sorting, and which option makes sense in a current environment.

Lua moves psql design choices into user-defined commands

psql is PostgreSQL's terminal-based frontend, and meta-commands beginning with a backslash are processed by the client rather than the server. The PostgreSQL 18 psql documentation describes \dt and the other meta-commands as psql functionality.

The Lua patch adds \luacode, \luafile, \lua, \luaset, and \luastr. Its central capability is psql.registerCommand, which registers a command with a name, help information, and a Lua handler. The lua-psql repository explicitly describes the code as an experiment for PostgreSQL's master branch.

That changes the design boundary. Rather than adding one more sorting option to the built-in \dt, a team can package the SQL, arguments, and output behavior it needs into its own command.

\my.dt+ combines filtering, sorting, and psql-style output

The proposed \my.dt builds a table listing similar to the built-in \dt. The example is invoked like this:

\my.dt+ pg_catalog.* -desc-size

This selects the pg_catalog schema and orders the result by size in descending order. The + form adds size and description columns, while -asc-size and -desc-size select the direction.

The handler reads the pattern and options through psql.scanSlashOption, escapes schema and table names through the current connection, and adds the resulting filters to its SQL. It then runs the query with psql.exec and renders a familiar psql table with psql.printQuery. The command also owns its -help response, making it more reusable than a loose SQL fragment.

The startup script checks :{?LUA_RELEASE} and registers the command only in a Lua-enabled build. That existence test is already part of current psql syntax: the official documentation says :{?variable_name} expands to a Boolean indicating whether the variable is defined.

Sorting by pg_table_size does not include indexes

The flexibility of a custom command also means its author must define what “size” means. This example uses pg_table_size for both display and ordering.

The PostgreSQL system administration function reference defines pg_table_size as the table's disk space excluding indexes but including its TOAST table, free space map, and visibility map. If the desired number includes indexes, pg_total_relation_size is the relevant function.

The first row from -desc-size is therefore not necessarily the table with the largest total on-disk footprint. Bloat analysis, backup-capacity planning, and index cleanup can require different metrics, so a reusable command should make its definition clear in its name or help text.

Size sorting has been discussed since at least 2019, with pspg as another answer

Sorting relation listings by size predates this patch. A 2019 pgsql-hackers proposal suggested a SORT_BY_SIZE psql variable that would change the order of \dt+. Another patch in 2025 proposed ascending and descending modifiers for \dt and \di; its Commitfest record shows the PostgreSQL 19-targeted proposal in a closed Commitfest with “Needs review” status and needing a rebase as of August 27, 2026.

The hard part is not whether size ordering is useful. It is deciding which commands receive it, which syntax represents it, and how generic the behavior should become. Lua command registration takes a different route by keeping specialized policies out of built-in syntax.

pspg provides another answer at the presentation layer. The official pspg repository documents numeric-column sorting and configuration through PSQL_PAGER. pspg sorts an already displayed result interactively; the Lua patch builds a reusable command that can also own query filters, options, and help.

PostgreSQL 18 users can choose SQL, pspg, or an experimental build

As of August 27, 2026, the documentation identifies PostgreSQL 18 as current and PostgreSQL 19 as a development version. The current psql manual does not document Lua commands, while lua-psql labels itself an experiment against master. This is not something enabled by a routine PostgreSQL update.

If the immediate goal is simply to list the largest user tables, SQL is enough. Replace pg_table_size with pg_total_relation_size when indexes must be included.

SELECT
  schemaname,
  relname,
  pg_size_pretty(pg_table_size(relid)) AS table_size
FROM pg_stat_user_tables
ORDER BY pg_table_size(relid) DESC;

When you want to adapt the query behind an existing meta-command, psql's -E option or ECHO_HIDDEN variable reveals the SQL it generates. Choose pspg for interactive reordering of displayed columns, and consider the Lua approach when the same decision logic should become a named command with arguments.

Trying the Lua approach requires building a patched PostgreSQL master tree configured with ./configure --with-lua. Because a registered handler can execute SQL through the current connection, load only trusted scripts and evaluate them with a test connection and appropriate privileges. The API, supported Lua versions, packaging, and future compatibility are not yet settled.

The value of Lua integration is owning a command, not replacing \dt

The opening question now has a clearer answer: size sorting does not have to become more built-in \dt syntax if Lua can express a purpose-built command. Combining filters, size semantics, ordering, presentation, and help on the user side would move psql from a fixed command set toward a client that can host small operational tools.

At this stage, however, the patch is better treated as a design experiment than an adoption target. Use SQL or pspg for routine work, and use an isolated Lua-enabled build to test which custom commands are genuinely easier to maintain than standard features. That distinction is the practical meaning of the proposal today.

Source

• Title: Pavel Stehule: integration Lua to psql II
• URL: https://postgr.es/p/9tg