psql内で使用できる特殊なコマンドです。SQL文ではなく、psql自体の動作を制御したり、データベースの情報を表示したりします。SQL文の末尾にはセミコロンが必要ですが、メタコマンドの末尾には不要です。
メタコマンドの一覧は \? で確認できます。
情報表示系メタコマンド 🔍
| コマンド |
説明 |
使用例 (S+は追加情報表示) |
\l, \l+ |
データベース一覧を表示します。+付きは詳細情報（サイズ、テーブルスペースなど）も表示します。 |
\l+ |
\dn, \dnS, \dn+ |
スキーマ一覧を表示します。Sはシステムスキーマも表示、+は詳細情報（所有者、アクセス権限など）を表示します。 |
\dn+ public |
\dt, \dtS, \dt+ |
テーブル一覧を表示します (現在のスキーマ、または指定したスキーマ)。Sはシステムテーブルも表示、+は詳細情報（サイズ、永続性など）を表示します。パターンマッチングも可能です。 |
\dt public.*
\dt+ users |
\di, \diS, \di+ |
インデックス一覧を表示します。Sはシステムオブジェクトのインデックスも表示、+は詳細情報（サイズなど）を表示します。 |
\di+ user_id_idx |
\ds, \dsS, \ds+ |
シーケンス一覧を表示します。Sはシステムシーケンスも表示、+は詳細情報（データ型、キャッシュ値など）を表示します。 |
\ds+ public. |
\dv, \dvS, \dv+ |
ビュー一覧を表示します。Sはシステムビューも表示、+は詳細情報（ビュー定義など）を表示します。 |
\dv+ user_view |
\dm, \dmS, \dm+ |
マテリアライズドビュー一覧を表示します。Sはシステムオブジェクトも表示、+は詳細情報（サイズ、アクセス権限など）を表示します。 |
\dm+ sales_summary |
\df, \dfS, \df+ |
関数一覧を表示します。引数の型を指定して絞り込むことも可能です。Sはシステム関数も表示、+は詳細情報（戻り値の型、揮発性など）を表示します。 |
\df public.get_*
\df+ calculate_total(int, numeric) |
\sf[+] <関数名> |
関数の定義 (CREATE FUNCTION 文) を表示します。+付きは行番号も表示します。 |
\sf+ my_function |
\d, \d+ <オブジェクト名> |
テーブル、ビュー、シーケンス、インデックス、複合型などの詳細情報を表示します。+付きはさらに詳細な情報（制約、ストレージ情報など）を表示します。 |
\d users
\d+ public.orders |
\du, \du+, \dg, \dg+ |
ロール (ユーザーとグループ) の一覧を表示します。\du はユーザーロール、\dg はグループロールに近いです (PostgreSQLではユーザーとグループの区別は曖昧)。+付きはロールの属性（ログイン権限、スーパーユーザーかなど）を表示します。 |
\du+ myuser |
\dp <パターン>, \z <パターン> |
テーブル、ビュー、シーケンスのアクセス権限 (GRANT/REVOKE) を表示します。\z は \dp のエイリアスです。 |
\dp users
\z public.* |
\ddp |
デフォルト権限を表示します。ALTER DEFAULT PRIVILEGES で設定された権限を確認できます。 |
\ddp |
\dD, \dD+ <パターン> |
ドメイン一覧を表示します。+付きは制約情報なども表示します。 |
\dD+ public. |
\dT, \dT+ <パターン> |
データ型一覧を表示します (複合型、ENUM型などを含む)。+付きは詳細情報（内部名、サイズなど）を表示します。 |
\dT+ my_enum |
\dx, \dx+ <パターン> |
インストールされている拡張機能 (Extension) の一覧を表示します。+付きは詳細情報（説明、バージョンなど）を表示します。 |
\dx+ uuid-ossp |
\dy |
イベントトリガーの一覧を表示します。 |
\dy |
\dL |
手続き言語 (Procedural Language) の一覧を表示します (plpgsqlなど)。 |
\dL |
\encoding [<エンコーディング名>] |
クライアントの文字エンコーディングを表示または設定します。サーバーエンコーディングと一致させることが重要です。 |
\encoding
\encoding UTF8 |
クエリ実行と編集 ⌨️
| コマンド |
説明 |
使用例 |
\g [<ファイル名> | |<コマンド>] |
現在のクエリバッファの内容を実行します。引数でファイルに出力したり、パイプで他のコマンドに渡したりできます。SQL文の末尾のセミコロン (;) とほぼ同等ですが、出力先指定などの機能があります。 |
SELECT * FROM users \g results.txt
SELECT version() \g | grep PostgreSQL |
\s [<ファイル名>] |
コマンド履歴を表示します。ファイル名を指定すると履歴をファイルに保存します。 |
\s
\s history.sql |
\e [<ファイル名>] [<行番号>] |
外部エディタ (環境変数 PSQL_EDITOR, EDITOR, VISUAL の順で探される) で現在のクエリバッファまたは指定したファイルを開きます。編集後、保存してエディタを終了すると、その内容がクエリバッファに読み込まれます。 |
\e
\e my_query.sql |
\ef [<関数名> [<行番号>]] |
指定した関数の定義を外部エディタで開きます。編集・保存後、psql内で \g を実行すると関数定義が更新されます (実際には ALTER FUNCTION が実行されるわけではなく、編集後の内容がバッファに読み込まれる)。 |
\ef my_function |
\ev [<ビュー名> [<行番号>]] |
指定したビューの定義を外部エディタで開きます。編集・保存後、psql内で \g を実行するとビュー定義が更新されます。 |
\ev my_view |
\p |
現在のクエリバッファの内容を表示します。実行前に確認するのに便利です。 |
\p |
\r |
クエリバッファをリセット（空に）します。 |
\r |
\w <ファイル名> |
現在のクエリバッファの内容を指定したファイルに書き込みます。 |
\w save_query.sql |
\watch [<秒数>] |
現在のクエリバッファの内容を繰り返し実行します。デフォルトは2秒間隔です。Ctrl+C で停止します。監視用途に便利です。 |
SELECT count(*) FROM logs WHERE level = 'ERROR'; \watch 5 |
入出力制御 📜
| コマンド |
説明 |
使用例 |
\i <ファイル名> |
指定したファイルからコマンドを読み込んで実行します。SQLスクリプトの実行に用います。 |
\i setup.sql |
\ir <ファイル名> |
\i と同様ですが、現在のスクリプトファイルからの相対パスでファイルを指定します。スクリプト内で他のスクリプトを読み込む際に便利です。 |
\ir ../common/init.sql |
\o [<ファイル名> | |<コマンド>] |
以降のクエリ結果を、指定したファイルまたはパイプ経由でコマンドに出力します。引数なしで標準出力に戻ります。 |
\o query_result.txt
SELECT * FROM users;
\o
\o | less
SELECT * FROM large_table;
\o |
\copy ... |
クライアントとサーバー間でデータをコピーします (SQLの COPY コマンドとは異なり、クライアント側のファイルシステムにアクセスできます)。ファイルとテーブル間のデータ移行に便利です。構文はSQLの COPY と似ています。 |
\copy users TO 'users.csv' WITH CSV HEADER
\copy products FROM 'products.csv' DELIMITER ',' CSV |
\echo <テキスト> |
指定したテキストを標準出力に表示します。スクリプト内でメッセージを表示するのに使います。変数展開も可能です。 |
\echo 'Processing table :tablename ...' |
\qecho <テキスト> |
指定したテキストをクエリ出力チャネル (\o で指定した先) に表示します。レポートにヘッダーやフッターを追加するのに便利です。 |
\o report.txt
\qecho '--- Sales Report ---'
SELECT * FROM sales;
\qecho '--- End of Report ---'
\o |
出力フォーマット設定 🎨
| コマンド |
説明 |
使用例 |
\a |
出力フォーマットを「整列 (aligned)」と「非整列 (unaligned)」で切り替えます。デフォルトは整列です。非整列はタブ区切りになります。 |
\a |
\C [<タイトル>] |
テーブルのキャプション（タイトル）を設定します。引数なしで解除します。\pset format が html, latex などの場合に意味を持ちます。 |
\C 'User List' |
\H または \html |
HTMLテーブル形式での出力を有効/無効にします。Webページへの埋め込みなどに便利です。 |
\H |
\t [on|off] |
タプル（行データ）のみの表示を有効/無効にします。デフォルトは off で、ヘッダーやフッターも表示されます。on にするとデータ行のみが表示されます。引数なしでトグルします。 |
\t
\t on |
\T <テーブル属性> |
HTML の <table> タグに追加する属性を設定します (例: border="1")。\H が有効な場合に意味を持ちます。 |
\T 'cellpadding="5" cellspacing="0"' |
\x [on|off|auto] |
拡張表示モードを切り替えます。on にすると、各行が「列名 | 値」の形式で表示され、横に長いテーブルが見やすくなります。auto は通常の表示で収まらない場合に自動で拡張表示にします。引数なしでトグルします (on/off)。 |
\x auto |
\pset <オプション> [<値>] |
出力フォーマットに関する様々なオプションを設定します。以下に主なオプションを示します。 |
下記参照 |
\pset format <フォーマット> |
出力フォーマットを指定します。aligned, unaligned, html, latex, troff-ms, csv, wrapped などがあります。 |
\pset format csv |
\pset border <数値> |
罫線のスタイルを設定します。0 (罫線なし), 1 (内側のみ), 2 (内側と外側、デフォルト) があります。 |
\pset border 1 |
\pset tuples_only [on|off] |
\t と同じ効果です。 |
\pset tuples_only on |
\pset title [<テキスト>] |
\C と同じ効果です。テーブルのタイトルを設定します。 |
\pset title 'Product Catalog' |
\pset null '<表示文字列>' |
NULL 値をどのように表示するかを設定します。デフォルトは空文字列です。 |
\pset null '(NULL)' |
\pset recordsep [on|off] |
非整列 (unaligned) モードで行区切り文字 (デフォルトは改行) を表示するかどうか。 |
\pset recordsep on |
\pset linestyle <ascii|old-ascii|unicode> |
罫線の描画に使用する文字種を設定します。 |
\pset linestyle unicode |
\pset pager [on|off|always] |
長い出力に対するページャ（lessなど）の使用を制御します。on は端末の高さに応じて自動、off は無効、always は常時使用。 |
\pset pager off |
変数とプロンプト ⚙️
| コマンド / 構文 |
説明 |
使用例 |
\set [<変数名> [<値> ...]] |
psql 変数を設定します。値が省略された場合は空文字列、変数名も省略された場合は現在の変数一覧を表示します。特殊な変数 (PROMPT1, PROMPT2, PROMPT3, ECHO, VERBOSITY など) もあります。 |
\set mytable users
\set start_id 100
\set
\set PROMPT1 '%/%R%# ' |
\unset <変数名> |
psql 変数の設定を解除します。 |
\unset mytable |
:変数名 |
psql 変数の値を参照（展開）します。SQL 文内でも使用できます。文字列として展開されるため、必要に応じてクォートが必要です。 |
SELECT * FROM :mytable WHERE id > :start_id;
\echo 'Current table is ' :mytable |
:'変数名' |
変数の値を SQL リテラルとして展開します。シングルクォートで囲まれ、内部のシングルクォートはエスケープされます。 |
SELECT * FROM users WHERE name = :'user_name'; |
:`変数名` |
変数の値を SQL 識別子として展開します。ダブルクォートで囲まれ、内部のダブルクォートはエスケープされます。テーブル名や列名などに使用します。 |
SELECT * FROM :"schema_name"."table_name"; |
\prompt [<変数名>] <プロンプトテキスト> |
ユーザーに入力を促し、その値を指定した psql 変数に設定します。変数名を省略すると、入力された値はクエリバッファに追加されます。 |
\prompt user_id 'Enter user ID: '
SELECT * FROM users WHERE id = :user_id; |
PROMPT1, PROMPT2, PROMPT3 |
プロンプトの表示形式を制御する特殊変数。PROMPT1: 通常、PROMPT2: 複数行入力時、PROMPT3: COPY FROM STDIN 時。% で始まるシーケンス（%M: ホスト名、%/: DB名、%n: ユーザー名、%#: スーパーユーザーなら #、他は > など）を使用できます。 |
\set PROMPT1 '%n@%/%R%# ' |
ECHO |
psql が実行するコマンドのエコーを制御する特殊変数。none (デフォルト), queries (実行するクエリを表示), all (\i で読み込んだコマンドも表示)。 |
\set ECHO queries |
VERBOSITY |
エラーメッセージの詳細度を制御する特殊変数。default, terse, verbose。 |
\set VERBOSITY verbose |
ON_ERROR_STOP |
スクリプト実行中にエラーが発生した場合の動作を制御する特殊変数。off (デフォルト、エラー後も続行), on (エラーでスクリプトを停止)。 |
\set ON_ERROR_STOP on |
トランザクション制御 🔄
デフォルトでは、psql は自動コミットモードではありません。各 SQL 文は個別のトランザクションとして実行されるわけではなく、BEGIN から COMMIT または ROLLBACK までが一つのトランザクションブロックになります。ただし、単一の文 (エラーなし) は暗黙的にコミットされます。明示的なトランザクション制御が推奨されます。\set AUTOCOMMIT off とすると、すべての文が明示的な COMMIT/ROLLBACK を必要とするようになります。
| コマンド |
説明 |
BEGIN; または START TRANSACTION; |
トランザクションを開始します。 |
COMMIT; または END; |
現在のトランザクションをコミットし、変更を確定します。 |
ROLLBACK; |
現在のトランザクションをロールバックし、変更を取り消します。 |
SAVEPOINT <セーブポイント名>; |
トランザクション内にセーブポイントを設定します。 |
ROLLBACK TO SAVEPOINT <セーブポイント名>; |
指定したセーブポイント以降の変更を取り消します。 |
RELEASE SAVEPOINT <セーブポイント名>; |
指定したセーブポイントを削除します。これ以降、そのセーブポイントへのロールバックはできなくなります。 |
\set AUTOCOMMIT [on|off] |
自動コミットモードを切り替えます。on の場合、各SQL文が成功すると自動的にコミットされます (psql のデフォルトの振る舞いとは異なる点に注意)。off の場合は明示的な COMMIT/ROLLBACK が必要になります。 |
-- トランザクション例
BEGIN;
UPDATE accounts SET balance = balance - 100 WHERE user_id = 1;
SAVEPOINT after_deduct;
UPDATE accounts SET balance = balance + 100 WHERE user_id = 2;
-- 何か問題が発生した場合
-- ROLLBACK TO SAVEPOINT after_deduct; -- user_id=2 の変更を取り消し
-- ROLLBACK; -- 全ての変更を取り消し
COMMIT; -- 問題なければ変更を確定
その他便利な機能 ✨
| コマンド |
説明 |
使用例 |
\timing [on|off] |
各SQL文の実行時間をミリ秒単位で表示するかどうかを切り替えます。パフォーマンス測定に役立ちます。 |
\timing on |
\cd [<ディレクトリパス>] |
psql のカレントディレクトリを変更します。引数なしで現在のディレクトリを表示します。\i などで相対パスを使用する際に便利です。 |
\cd /path/to/sql/scripts
\cd |
\! [<シェルコマンド>] |
シェルコマンドを実行します。引数なしで対話的なシェルを起動します (終了すると psql に戻る)。 |
\! ls -l *.sql
\! |
\? [<トピック>] |
psql のメタコマンドに関するヘルプを表示します。トピック (例: variables, display) を指定すると、関連するコマンドのヘルプが表示されます。 |
\?
\? variables |
\copyright |
PostgreSQL と psql の配布条件 (著作権情報) を表示します。 |
\copyright |
\history |
\s と同じくコマンド履歴を表示します。 |
\history |
\prompt -r <変数名> |
プロンプトを表示せずに、標準入力から一行読み込んで変数に格納します。スクリプト内でパイプからの入力を受け取る場合などに使用できます。 |
\! echo 'some_value' | psql -c '\prompt -r myvar' -c '\echo :myvar' |
\setenv <NAME> [<VALUE>] |
psql が実行される環境の環境変数を設定します。\! で実行されるコマンドなどに影響します。 |
\setenv PAGER less |
コメント