psqlへのLua統合パッチで独自バックスラッシュコマンドを作る

psqlへLuaを組み込み、利用者が独自のバックスラッシュコマンドを定義できる実験パッチが公開されました。サイズ順にテーブルを並べる `\my.dt` の例から、固定機能の追加とは異なる拡張方法と、現時点での使い分けを整理します。

こはるの読みどころ

これはリリース済み機能ではなく、psqlの拡張点を探る実験です。すぐに導入する話と、設計の可能性として理解する話を分けて読むと判断しやすいですよ。

psqlで \dt+ を開き、テーブルをサイズ順に並べたい。欲しいのは小さな操作でも、標準のメタコマンドへ新しい構文を足すとなると、すべての利用者に関わる設計問題になります。

Pavel Stěhule氏が2026年8月26日に示したのは、psqlへLuaを組み込み、利用者自身が \my.dt のようなコマンドを定義する実験パッチです。並べ替え方を標準機能として一つに決めるのではなく、拡張点を用意して判断をスクリプト側へ移します。

ただし、これはリリース済みのPostgreSQL機能ではありません。何が便利になるのか、サイズ順表示の長い議論とどうつながるのか、そして今の環境なら何を選べるのかを順に見ていきましょう。

Luaでpsqlの仕様議論を利用者側のコマンドへ移せる

psqlはPostgreSQLのターミナル型フロントエンドで、バックスラッシュから始まるメタコマンドはサーバではなくクライアント側で処理されます。PostgreSQL 18のpsql文書にも、\dtを含むメタコマンドがpsql自身の機能として整理されています。

Lua統合パッチは、ここへ \luacode、\luafile、\lua、\luaset、\luastrを加えます。中心になるのは、Luaから psql.registerCommand を呼び、名前、ヘルプ、処理関数を持つ独自コマンドを登録できる点です。lua-psqlリポジトリは、この仕組みをPostgreSQLのmasterブランチ向け実験コードと位置づけています。

この違いは大きいですね。標準の \dt に並べ替えオプションを一つ足す設計ではなく、チームや用途ごとに必要なSQL、引数、表示方法を一つのコマンドへまとめられる設計です。

`\my.dt+`がフィルタ・並べ替え・表示を一度に扱う

提示された \my.dt は、標準の \dt に近いテーブル一覧をLuaで組み立てます。実行例は次の形です。

text

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

この一行で、pg_catalogスキーマを対象にし、サイズの降順で結果を出します。末尾の + があるとサイズと説明を表示し、-asc-sizeなら昇順、-desc-sizeなら降順へ切り替える作りです。

ハンドラは、psql.scanSlashOptionでパターンとオプションを読み、スキーマ名とテーブル名を現在の接続でエスケープしてSQLの条件へ加えます。その後、psql.execでクエリを実行し、psql.printQueryでpsqlらしい表として表示します。-helpの応答もコマンド自身が持つため、単なるSQL断片より再利用しやすい形です。

起動用スクリプトは :{?LUA_RELEASE} でpsql変数の存在を調べ、Lua対応ビルドでだけ登録処理を実行します。この変数存在テストは現行psqlにもある構文で、公式文書では :{?variable_name} が定義済みかどうかを真偽値へ置換すると説明されています。

`pg_table_size`で並べた結果はインデックスを含まない

独自コマンドに自由度があるからこそ、「サイズ」の定義は利用者が決める必要があります。今回の例が並べ替えと表示に使うのは pg_table_size です。

PostgreSQLの管理関数リファレンスによると、pg_table_sizeはインデックスを除外し、TOASTテーブル、Free Space Map、Visibility Mapを含むテーブル領域を返します。インデックスまで含む総量が必要なら、pg_total_relation_sizeを使う必要があります。

つまり、-desc-sizeの先頭は「インデックスを含めた総ディスク使用量が最大のテーブル」とは限りません。肥大化調査、バックアップ容量の見積もり、インデックス整理では欲しい指標が違うため、コマンド名やヘルプで定義を明示したいところです。

2019年から続くサイズ順表示はpspgという別解も生んだ

テーブル一覧のサイズ順表示は、今回初めて出た要望ではありません。2019年には、SORT_BY_SIZEというpsql変数で \dt+ の並び順を変える提案がpgsql-hackersへ投稿されています。2025年には \dt と \di へ昇順・降順の修飾子を加える別パッチも登場しましたが、Commitfestの記録ではPostgreSQL 19向けの提案が「Needs review」のまま閉じたCommitfestに残り、2026年8月27日時点でrebaseも必要です。

難しいのは、サイズ順が便利かどうかではなく、どのメタコマンドへ、どの構文で、どの範囲まで共通化するかです。Luaによる登録機構は、個別の要求を標準構文へ積み上げず、利用者定義コマンドとして切り出す方向を示します。

もう一つの答えが、psqlの出力を受け取る表向けページャーのpspgです。pspgの公式リポジトリは数値列による並べ替えに対応し、PSQL_PAGERへ設定して使えます。pspgは表示済みの結果をその場で並べ替える道具、Luaパッチはクエリの条件やヘルプまで含む再利用可能なコマンドを作る仕組み、と役割を分けると分かりやすいでしょう。

PostgreSQL 18環境ではSQL・pspg・実験ビルドを目的で選ぶ

2026年8月27日時点の現行文書はPostgreSQL 18をcurrent、PostgreSQL 19を開発版として案内しています。現行psqlの文書にLuaコマンドはなく、lua-psql側も「masterブランチ向けの実験」と明記しています。通常のアップデートで有効になる機能ではありません。

最大のユーザーテーブルを今すぐ調べるだけなら、次のSQLで目的を満たせます。pg_table_sizeを pg_total_relation_sizeへ変えれば、インデックス込みの順番にもできます。

SQL

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;

既存のメタコマンドが内部で発行するSQLを土台にしたい場合は、psqlの -E または ECHO_HIDDENで隠れたクエリを表示できます。対話中に列を切り替えて眺めたいならpspg、同じ判断ロジックを引数付きコマンドとして何度も使いたいならLua案、という選び方です。

Lua案を試すには、パッチを適用したPostgreSQL masterを ./configure --with-lua で構成してビルドする必要があります。登録したハンドラは現在の接続でSQLを実行できるため、信頼できるスクリプトだけを、検証用の接続先と権限で試すのがよいでしょう。API、対応Luaバージョン、配布方法、将来の互換性はまだ確定していません。

Lua統合の価値は新しい`\dt`より自分のコマンドを持てること

冒頭の問いへの答えは、標準の \dt へ並べ替え構文を足さなくても、Luaで用途別のコマンドを作れる可能性が見えてきた、です。フィルタ、サイズの定義、並べ替え、表示、ヘルプを利用者側で一つにまとめられれば、psqlは固定されたコマンド集から、小さな運用ツールを載せられるクライアントへ近づきます。

一方で、現段階は採用判断より設計検証の段階です。日常運用ではSQLやpspgを使い、Lua統合は隔離した環境で「どんな独自コマンドなら標準機能より管理しやすいか」を確かめる。そこまで分けて考えると、このパッチの実務的な意味が見えてきます。