他のバージョンの文書9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

psql

名前

psql -- PostgreSQL対話的ターミナル

概要

psql [option...] [dbname [username]]

説明

psqlとはPostgreSQLのターミナル型フロントエンドです。 対話的に問い合わせを入力し、それをPostgreSQLに対して発行して、結果を確認することができます。 また、ファイルから入力を読み込むことも可能です。 さらに、スクリプトの記述を簡便化したり、様々なタスクを自動化したりする、いくつものメタコマンドとシェルに似た各種の機能を備えています。

オプション

-a
--echo-all

読み込んだ全ての行を標準出力に表示します。 これは対話式モードよりもスクリプト処理の際に有用です。 ECHO変数をallに設定するのと同じ意味を持ちます。

-A
--no-align

位置揃えなしの出力モードに切り替えます (デフォルトの出力モードは位置揃えありです)。

-c command
--command command

psqlに対し、commandという1つのコマンド文字列を実行し、終了するよう指示します。 このコマンドはシェルスクリプト内で有用です。

commandは、サーバで完全に解析可能な(つまり、psql特有の機能は含まない)コマンド文字列、もしくは、バックスラッシュコマンド1つである必要があります。 このため、このオプションではSQLpsqlメタコマンドを混在させることはできません。 これらを同時に使用するには、echo '\x \\ SELECT * FROM foo;' | psqlのようにパイプを使って文字列をpsqlに渡します(\\はメタコマンドの区切り文字です。)。

コマンド文字列が複数のSQLコマンドを含む場合、トランザクションを複数に分けるBEGIN/COMMITコマンドが明示的に文字列内に含まれない限り、それらのコマンドは1つのトランザクションで処理されます。 これは、同じ文字列をpsqlの標準入力として渡した場合の動作とは異なります。

-d dbname
--dbname dbname

接続するデータベースの名前を指定します。 コマンドラインでオプション以外の最初の引数としてdbnameを指定するのと同じ効力を持ちます。

このパラメータに=記号が含まれる場合、conninfo文字列として扱われます。 詳しくは項30.1を参照してください。

-e
--echo-queries

サーバに送られたコマンドを標準出力にも送ります。 ECHO変数をqueriesに設定するのと同じ効力を持ちます。

-E
--echo-hidden

\dやその他のバックスラッシュコマンドによって生成される実際の問い合わせを表示します。 これを使って、psqlの内部動作を調べることができます。 psql内部からECHO_HIDDEN変数を設定するのと同じ効力を持ちます。

-f filename
--file filename

対話式にコマンドを読み取るのではなく、filenameファイルをコマンドのソースとして使用します。 このファイルの処理が終了した後、psqlは終了します。 これは\i内部コマンドとほぼ同じ効力を持ちます。

filename-(ハイフン)を指定すると、標準入力から読み取られます。

このオプションを指定するのと、psql < filenameと入力するのでは、微妙に動作が異なります。 一般的には、両者とも期待通りの動作を行いますが、-fを使用した場合は、エラーメッセージに行番号を付けるなどの機能がいくつか有効になります。 また、このオプションを使用した場合、起動時のオーバーヘッドが減少する可能性が若干あります。 一方、シェルの入力リダイレクションを使用する方法では、(理論的には)全て手作業で入力した場合の出力とまったく同一な出力になることが保証されます。

-F separator
--field-separator separator

separatorを位置揃えを行わない出力におけるフィールド区切り文字として使用します。 \pset fieldsepもしくは\fと同じ効力を持ちます。

-h hostname
--host hostname

サーバを実行しているマシンのホスト名を指定します。 この値がスラッシュから始まる場合、Unixドメインソケット用のディレクトリとして使用されます。

-H
--html

HTML表形式を有効にします。 \pset format htmlもしくは\Hコマンドと同じ効力を持ちます。

-l
--list

利用可能な全てのデータベースを一覧表示し、終了します。 この他の接続に関連しないオプションは無視されます。 \list内部コマンドと似た効力を持ちます。

-L filename
--log-file filename

すべての問い合わせの出力を通常の出力先に出力し、さらにファイルfilenameに書き出します。

-n
--no-readline

行編集用のreadlineを使用しません。また履歴も使用しません。 コピー&ペースト時のタブ展開を無効にするために有用かもしれません。

-o filename
--output filename

全ての問い合わせの出力をfilenameファイルに書き込みます。 これは\oコマンドと同じ効力を持ちます。

-p port
--port port

サーバが接続監視を行っているTCPポートもしくはローカルUnixドメインソケットファイルの拡張子を指定します。 PGPORT環境変数の値、環境変数が設定されていない場合はコンパイル時に指定した値(通常は5432)がデフォルト値となります。

-P assignment
--pset assignment

\pset形式による表示オプションをコマンドラインから指定することができます。 ここでは空白ではなく等号を使って名前と値を区切っていることに注意してください。 つまり、出力形式をLaTeXにする場合、-P format=latexと入力します。

-q
--quiet

psqlがメッセージ出力なしで処理を行うように指示します。 デフォルトでは、ウェルカム(welcome)メッセージや各種の出力情報が表示されますが、 このオプションを使用した場合、これらのメッセージが表示されません。 -cオプションと併用すると便利です。 psql内でQUIET変数を設定した場合も、同じ効力を得ることができます。

-R separator
--record-separator separator

separatorを位置揃えを行わない出力におけるレコード区切り文字として使用します。 これは\pset recordsepコマンドと同じです。

-s
--single-step

シングルステップモードで実行します。 これは各コマンドがサーバに送信される前に、ユーザに対して実行するかキャンセルするかについて確認を求めることを意味します。 スクリプトのデバッグを行う時に使用してください。

-S
--single-line

シングル行モードで実行します。このモードでは、セミコロンと同じように改行もSQLコマンドの終端として扱われます。

注意: このモードはどうしてもこのような方式を使用したいユーザ向けに用意されたものです。無理に使用する必要はありません。 特に、1行にSQLとメタコマンドを混在させる場合、経験の浅いユーザにとってその実行順番は必ずしもわかりやすいものではありません。

-t
--tuples-only

列名と結果の行数フッタなどの表示を無効にします。 これは、\tコマンドとまったく同じ効力を持ちます。

-T table_options
--table-attr table_options

HTMLtableタグで使用されるオプションを指定できます。 詳細は\psetを参照してください。

-U username
--username username

デフォルトのユーザではなくusernameユーザとしてデータベースに接続します (当然、指定したユーザがデータベースに接続する権限を持っていなければなりません)。

-v assignment
--set assignment
--variable assignment

\set内部コマンドのように、変数の代入を行います。 値がある場合、コマンド上では、名前と値を等号(=)で区切る必要があることに注意してください。 等号を指定しないと変数が未設定の状態になります。 値なしの変数を設定するには、値を指定しないで等号のみ使用してください。 これらの代入は起動時の非常に早い段階で行われます。 そのため、内部で使用するために予約されている変数は後で上書きされる可能性があります。

-V
--version

psqlのバージョンを表示し、終了します。

-w
--no-password

パスワードの入力を促しません。 サーバがパスワード認証を必要とし、かつ、.pgpassファイルなどの他の方法が利用できない場合、接続試行は失敗します。 バッチジョブやパスワードを入力するユーザが存在しない場合にこのオプションは有用かもしれません。

このオプションがセッション全体にわたって設定され続けることに注意してください。 このため\connectメタコマンドの使用に関しても初期接続試行と同様に影響します。

-W
--password

データベースに接続する前に、psqlは強制的にパスワード入力を促します。

サーバがパスワード認証を要求する場合psqlは自動的にパスワード入力を促しますので、これが重要になることはありません。 しかし、psqlは、サーバにパスワードが必要かどうかを判断するための接続試行を無駄に行います。 こうした余計な接続試行を防ぐために-Wの入力が有意となる場合もあります。

このオプションがセッション全体に対して残ることに注意してください。 このため初期接続試行と同様に\connectメタコマンドの使用にも影響を与えます。

-x
--expanded

拡張テーブル形式モードを有効にします。 これは\xコマンドと同じです。

-X
--no-psqlrc

起動用ファイル(psqlrcファイルもしくはユーザ用の~/.psqlrcファイル)を読み込みません。

-1
--single-transaction

-fオプションを使用してpsqlがスクリプトを実行する時、このオプションを併記すると、スクリプトをBEGIN/COMMITで囲み、単一トランザクション内でスクリプトを実行します。 これにより確実にすべてのコマンドが完全に成功するか、変更がまったく行われないかのいずれかになります。

スクリプト内部でBEGINCOMMITROLLBACKを使用している場合、このオプションは想定した効果をもたらしません。 また、スクリプト内部にトランザクションブロック内部で実行することができないコマンドが含まれている場合、このオプションを指定することで、そのコマンドは失敗(そしてそのためにトランザクション全体が失敗)します。

-?
--help

psqlのコマンドライン引数に関するヘルプを表示し、終了します。

終了状態

psqlは、正常に終了した時には0を、psqlにとって致命的なエラー(メモリ不足やファイルが見つからないなど)が発生した時には1を、セッションが対話式でない状態でサーバとの接続が不完全になった時には2を、ON_ERROR_STOP変数が設定されている状態でスクリプトでエラーが発生した時には3をシェルに返します。

使用方法

データベースへの接続

psqlPostgreSQLの正式なクライアントアプリケーションです。 データベースに接続するには、接続するデータベース名、ホスト名、サーバのポート番号、接続する際に使用するユーザ名がわかっていなければなりません。 psqlでは、それらをコマンドラインオプションで指定することができます。接続するデータベース名は-d、ホスト名は-h、サーバのポート番号は-p、接続するユーザ名は-Uを使用してそれぞれ指定します。 オプションに属さない引数がある場合、それはデータベース名(データベース名が与えられている場合にはユーザ名)とみなされます。 これらのオプションは全て指定されている必要はありません。指定されていない時はデフォルト値が使用されます。 ホスト名を省略した場合、psqlはUnixドメインソケット経由でローカルホストにあるサーバに、Unixドメインソケットを持たないマシンではlocalhostへのTCP/IP経由で接続します。 デフォルトのポート番号はコンパイル時に設定されます。 データベースサーバは同じデフォルト値を使用するので、多くの場合、ポートは指定する必要はありません。 デフォルトのユーザ名とデータベース名は、Unixのユーザ名です。 任意のユーザ名で全てのデータベースに接続できるわけではありません。 データベース管理者は、接続権限をユーザに知らせておかなければなりません。

デフォルトがまったく適用できない時は、入力の手間を省くために、環境変数PGDATABASEPGHOSTPGPORTPGUSERに適当な値を設定することもできます。 (この他の環境変数については、項30.13を参照してください。) また、~/.pgpassファイルを使用すれば、定常的なパスワードの入力を防ぐことができ、便利です。 詳細は項30.14を参照してください。

他の接続パラメータの指定方法としてconninfo文字列があります。 これは、データベース名の代わりに使用されます。 この機構により、接続全体に関する非常に幅広い制御を行うことができます。

$ psql "service=myservice sslmode=require"

この方法では接続パラメータの検索に、項30.16で説明するLDAPを使用することもできます。 利用できる接続オプションのすべてについての詳細は、項30.1を参照してください。

何らかの原因(権限がない、指定したホストでサーバが稼働していないなど)で接続ができなかった場合は、psqlはエラーメッセージを表示し、終了します。

SQLコマンドの入力

通常の操作において、psqlは、psqlが現在接続しているデータベース名の後に=>の文字列が付いたプロンプトを表示します。 以下に例を示します。

$ psql testdb
psql (8.4.4)
Type "help" for help.


testdb=>

プロンプトに対しユーザはSQLコマンドを入力することができます。 通常、入力された行は問い合わせ終了を意味するセミコロンに達した時点でサーバへと送信されます。 つまり、改行は問い合わせの終了とはみなされません。 したがって、わかりやすくするために、コマンドは複数の行にわたって記述することができます。 コマンドが送信され問題なく実行されると、画面にコマンドの結果が表示されます。

また、コマンドが実行される度に、psqlLISTENNOTIFYによって生成された非同期通知イベントを検査します。

メタコマンド

psql内で入力されたコマンドのうち、バックスラッシュで始まり、引用符で囲まれていないものは、psql自身が実行するpsqlのメタコマンドとして扱われます。 これらのコマンドを使うと、データベースを管理したりスクリプトを作成するにあたって、psqlがより便利になります。 メタコマンドは一般的にスラッシュコマンド、またはバックスラッシュコマンドと呼ばれます。

psqlコマンドは、バックスラッシュ、コマンド本体、引数の順につなげた形式になっています。 引数とコマンド本体の間と引数間は、空白文字によって分割されています。

引数に空白を含める場合は単一引用符で囲みます。 単一引用符を引数に含める場合には、その単一引用符を二重にしてください。 単一引用符で囲われた文字は、C言語と同じような置換の対象となります。 このような文字には、\n(改行)、\t(タブ)、\digits(8進数で表された文字)、\xdigits(16進数で表された文字)があります。

引用符で囲まれておらず、かつコロン(:)で開始する引数は、psql変数として扱われます。この時は、変数の値が引数となります。

逆引用符(`)で囲まれた引数は、コマンドラインとして認識され、シェルに渡されます。 そして、コマンドの結果(末尾の改行は削除されます)が引数の値とみなされます。 逆引用符に対しても上記のエスケープシーケンスが該当します。

コマンドには、引数としてSQLの(テーブル名などの)識別子を取るものがあります。 これらの引数は次のようなSQLの構文規則に従います。 引用符を伴わない文字は強制的に小文字になります。しかし、二重引用符(")で囲まれると、大文字小文字変換が行われず、空白文字を識別子内に含めることができます。 さらに、二重引用符内では、連続する2つの二重引用符は1つの二重引用符とみなされます。 例えば、FOO"BAR"BAZfooBARbazと解釈され、"A weird"" name"A weird" nameになります。

引数の解析は、引用符で囲まれていないもう1つのバックスラッシュが見つかると終了します。 これは、新たなメタコマンドの始まりと認識されます。 \\(バックスラッシュ2つ)という特別な文字の並びは引数の終わりを意味するので、SQLコマンドが残されている場合は、その解析を続けます。 このように、SQLコマンドとpsqlコマンドは1つの行に自由に混合して記述することができます。 しかし、あらゆる場合において、メタコマンドの引数は行をまたぐことはできません。

メタコマンドとして、以下のものが定義されています。

\a

現在のテーブルの出力形式が「揃えない」になっていれば「揃える」に、 「揃える」になっていれば「揃えない」に設定します。 このコマンドは後方互換性を保持するためにあります。 より一般的な解決策は\psetを参照してください。

\cd [ directory ]

現在の作業ディレクトリをdirectoryに変更します。 引数がない場合は、現在のユーザのホームディレクトリに変更します。

ティップ: 現在の作業ディレクトリを表示するには、\! pwdを使用してください。

\C [ title ]

問い合わせ結果として表示されるテーブルタイトルの設定、または、タイトルの設定解除を行います。 このコマンドは、\pset title titleと同じ効力を持ちます (このコマンド名は"caption"に由来します。以前はHTMLのテーブルの標題(caption)を設定するためだけに使われていたためです)。

\connect (or \c) [ dbname [ username ] [ host ] [ port ] ]

PostgreSQLサーバへの接続を新規に確立します。 新規接続に成功した場合、以前の接続は閉ざされます。 dbnameusernamehostportのいずれかが省略、あるいは -と指定された場合、対応するパラメータの値はこれまでの接続の値が使用されます。 これまで接続されていない場合は、そのパラメータの値にはlibpqのデフォルト値が使用されます。

接続の試行が(ユーザ名の間違いやアクセス拒否などの理由で)失敗した場合、psqlが対話式モードである場合に限って、それまでの接続が保持されます。 非対話式スクリプトを実行している場合は、処理はエラーとなり、即座に停止します。 この実装の違いは、対話モードでは入力ミスに対するユーザの簡便性を考慮し、非対話モードではスクリプトによって間違ったデータベースを操作することを防ぐための安全策を考慮した結果生じています。

\copy { table [ ( column_list ) ] | ( query ) } { from | to } { filename | stdin | stdout | pstdin | pstdout } [ with ] [ binary ] [ oids ] [ delimiter [ as ] 'character' ] [ null [ as ] 'string' ] [ csv [ header ] [ quote [ as ] 'character' ] [ escape [ as ] 'character' ] [ force quote column_list ] [ force not null column_list ] ]

フロントエンド(クライアント)コピーを行います。 これはCOPY SQLコマンドを実行する操作ですが、サーバで指定ファイルに対する読み込みまたは書き込みを行うのではなく、psqlがファイルの読み書きや、サーバとローカルファイルシステム間のデータ送信を行います。 この場合、ファイルへのアクセス権限はサーバではなくローカルユーザのものを使用するので、SQLのスーパーユーザ権限は必要ありません。

このコマンドの構文はCOPY SQLコマンドに似ています(詳細はこのコマンドの説明を参照してください)。 このため、\copyコマンドには特別な解析規則が適用されていることに注意してください。 特に、変数の置換規則やバックスラッシュエスケープは適用されません。

\copy ... from stdin | to stdoutはそれぞれコマンドの入力と出力を元に読み書きを行います。 コマンドの発行源と同じところから、\.を読み取るまで、あるいは、ストリームがEOFに達するまで全ての行を読み続けます。 出力はコマンドの出力と同じところに送られます。 psqlの標準入力や標準出力を使用するには、pstdinpstdoutを使用してください。 これは、SQLスクリプトファイルの内部でテーブルにデータを投入する場合に便利です。

ティップ: この操作はSQLCOPYコマンドほど効率が良いわけではありません。 これは、全てのデータをクライアント/サーバ接続を通じてやり取りしなければならないからです。 データ量が多い時はSQLコマンドを使用する方が良いでしょう。

\copyright

PostgreSQLの著作権および配布条項を表示します。

\d[S+] [ pattern ]

patternに一致する各リレーション(テーブル、ビュー、インデックス、シーケンス)について、全ての列、列の型、テーブル空間(デフォルト以外を使用している場合)、NOT NULLやデフォルトなどの特別な属性を表示します。 ビューの場合は、ビューの定義に従い、関連付けられているインデックス、制約、ルールおよびトリガも表示されます("パターンのマッチング"については後述します)。

\d+という形式も同一のコマンドを表しますが、より多くの情報を表示します。 こちらでは、テーブルの列に関連付けられたコメントやテーブルにOIDが存在するかどうかも表示されます。

デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。

注意: \dpattern引数なしで使用された場合は、\dtvsと同じ意味となり、全てのテーブル、ビュー、シーケンスの一覧が表示されます。 これは単に便宜上のものです。

\da[S] [ pattern ]

利用できる全ての集約関数と、その操作対象となるデータ型、戻り値のデータ型の一覧を表示します。 patternが指定された場合、そのパターンに名前が一致する集約のみが表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。

\db[+] [ pattern ]

利用可能なテーブル空間を一覧表示します。 patternが指定された場合、そのパターンに名前が一致するテーブル空間のみが表示されます。 コマンド名に+が付与された場合、各オブジェクトに関連付けされた権限についても表示します。

\dc [ pattern ]

利用できる全ての変換と文字セット符号化方式の一覧を表示します。 patternが指定された場合、そのパターンに名前が一致する変換のみが表示されます。

\dC[S] [ pattern ]

利用できる型キャストの一覧を表示します。 patternが指定された場合、そのパターンに元データ型または変換先データ型が一致するキャストのみが表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。

\dd[S] [ pattern ]

patternに一致するオブジェクトの説明を表示します。 引数が指定されていない場合は、全ての可視的なオブジェクトの説明を表示します。 どちらの場合でも、一覧に表示されるのは説明を持つオブジェクトのみです デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。 "オブジェクト"には、集約、関数、演算子、型、リレーション(テーブル、ビュー、インデックス、シーケンス)、ラージオブジェクト、ルール、トリガが含まれます。 次に例を示します。

=> \dd version
                     Object descriptions
   Schema   |  Name   |  Object  |        Description
------------+---------+----------+---------------------------
 pg_catalog | version | function | PostgreSQL version string
(1 row)

オブジェクトの説明はCOMMENT SQLコマンドを使用して作成することができます。

\dD[S] [ pattern ]

使用可能なドメインを全て表示します。 patternが指定されている場合は、一致するドメインのみが表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。

\des[+] [ pattern ]

異種サーバ(分かりやすく言うと"外部サーバ")をすべて列挙します。 patternが指定されている場合は、名前がパターンに一致するサーバのみが表示されます。 \des+構文が使用された場合、各サーバの完全な説明、サーバのACL、型、バージョン、オプションが表示されます。

\deu[+] [ pattern ]

ユーザマップ(分かりやすく言うと"外部ユーザ")をすべて列挙します。 patternが指定されている場合は、名前がパターンに一致するユーザのみが表示されます。 \deu+構文が使用された場合、各マップについて追加情報が表示されます。

注意

\deu+ではリモートユーザのユーザ名とパスワードも表示される可能性があります。 これらを外部に曝さないように注意しなければなりません。

\dew[+] [ pattern ]

異種データラッパ(分かりやすく言うと"外部ラッパ")をすべて列挙します。 patternが指定されている場合、名前がパターンに一致する異種データラッパのみが表示されます。 \dew+構文が使用された場合、異種データラッパのACLとオプションも表示されます。

\df[antwS+] [ pattern ]

利用できる全ての関数と、その引数と戻り値の型、および'agg'(集約)、'normal'、'trigger'、'window'という関数の種類の一覧を表示します。 特定の種類の関数のみを表示させるには、対応する文字antwを使用してください。 patternが指定されている場合は、そのパターンに名前が一致する関数のみが表示されます。 \df+構文が使われた場合、各関数の、揮発性、言語、ソースコードや説明を含む付加的情報も表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。

注意: 特定の型を引数とする関数や特定の型を返す関数を検索するには、ページャの検索機能を使用して\dfの出力をスクロールしてください。

\dF[+] [ pattern ]

利用可能なテキスト検索設定を列挙します。 patternが指定された場合、このパターンにマッチする名前の設定のみが表示されます。 \dF+形式が使用された場合、背後のテキスト検索パーサや各パーサトークン型についての辞書リストなど各設定の完全な説明が表示されます。

\dFd[+] [ pattern ]

利用可能なテキスト検索辞書を列挙します。 patternが指定された場合、このパターンにマッチする名前の辞書のみが表示されます。 \dFd+形式が使用された場合、選択された辞書それぞれについて背後のテキスト検索テンプレートやオプション値など更なる情報が表示されます。

\dFp[+] [ pattern ]

利用可能なテキスト検索パーサを列挙します patternが指定された場合、このパターンにマッチする名前のパーサのみが表示されます。 \dFp+形式が使用された場合、背後の関数や認知されるトークン型のリストなど各パーサの完全な説明が表示されます。

\dFt[+] [ pattern ]

利用可能なテキスト検索テンプレートを列挙します。 patternが指定された場合、このパターンにマッチする名前のテンプレートのみが表示されます。 \dFt+形式が使用された場合、テンプレートそれぞれについて背後の関数名など更なる情報が表示されます。

\dg[+] [ pattern ]

全てのデータベースロールを一覧表示します。 patternが指定されている場合は、そのパターンに名前が一致するロールのみが表示されます。 (このコマンドは実質\duと同じになりました。) \dg+形式が使用された場合、ロールそれぞれについてロールのコメントなどの更なる情報が表示されます。

\di[S+] [ pattern ]
\ds[S+] [ pattern ]
\dt[S+] [ pattern ]
\dv[S+] [ pattern ]

これらのコマンド群では、istvという文字は、それぞれ、インデックス、シーケンス、テーブル、ビューを意味します。 これらの文字のうち任意のものを任意の順番で指定すると、一致する全てのオブジェクトの一覧を表示することができます。 例えば\ditはインデックスとテーブルを表示します。 コマンド名の後に+を付加すると、ディスク上の物理サイズと各オブジェクトに関連付けられている説明が(存在すれば)表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。

patternを指定すると、パターンに名前が一致するオブジェクトのみが表示されます。

\dl

\lo_listの別名で、ラージオブジェクトの一覧を表示します。

\dn[+] [ pattern ]

利用できるスキーマ(名前空間)の一覧を表示します。 pattern(正規表現)を指定すると、パターンに名前が一致するスキーマのみが表示されます。 ローカルではない一時スキーマは表示されません。 コマンド名の後に+を付加すると、各オブジェクトに関連付けられている説明が(存在すれば)表示されます。

\do[S] [ pattern ]

利用できる演算子と、その演算項目と戻り値を一覧表示します。 patternを指定すると、パターンに名前が一致する演算子のみが表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。

\dp [ pattern ]

使用可能なテーブル、ビュー、シーケンスを、関連付けられているアクセス権限とともに一覧表示します。 patternを指定すると、パターンに名前が一致するテーブル、ビュー、シーケンスのみが表示されます。

GRANTコマンドとREVOKEコマンドは、アクセス権限の設定に使われます。

\dT[S+] [ pattern ]

利用可能なデータ型を一覧表示します。 patternを指定すると、パターンに一致する名前を持つ型のみを表示します。 +をコマンド名に付けると、型ごとに、型の内部名、サイズ、enum型では許される値も一緒に表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。

\du[+] [ pattern ]

全てのデータベースロールを一覧表示します。 patternを指定すると、パターンに一致する名前のロールのみを表示します。 \du+形式が使用された場合、ロールそれぞれについてロールのコメントなどの更なる情報が表示されます。

\edit (または \e) [ filename ]

filenameが指定された場合、このファイルが編集されます。 エディタを終了した後、その内容は問い合わせバッファにコピーされます。 引数がない場合、現在の問い合わせバッファが一時ファイルにコピーされ、同様に編集されます。

次に、新しい問い合わせバッファは、通常のpsqlの規則に従い、全体を1行として再解析されます (このため、この方法では"スクリプト"を作成できません。 この目的のためには\iを使用してください)。 これはまた、問い合わせの終端がセミコロンである(もしくは問い合わせがセミコロンを含む)場合、すぐに実行されることを意味しています。 セミコロンがない場合は、単に問い合わせバッファ内に保持されるだけです。

ティップ: psqlは環境変数PSQL_EDITOREDITORVISUALをこの順番に検索し、使用するエディタを決定します。 これらの環境変数が全てが未設定である場合は、Unixシステムではviが、Windowsシステムではnotepad.exeが実行されます。

\ef [ function_description ]

このコマンドは指名された関数定義をCREATE OR REPLACE FUNCTIONコマンド構文で取り出し、編集します。 編集は\eと同様の方法で行われます。 エディタ終了後、更新されたコマンドは問い合わせバッファ内で待機しています。 それを送信するためにはセミコロンか\gを入力してください。 取り消す場合は\rを入力してください。

対象の関数を名前単体、または、たとえばfoo(integer, text)のように名前と引数で指定することができます。 同じ名前の関数が複数存在する場合、引数の型を指定しなければなりません。

関数が指定されなかった場合、空のCREATE FUNCTIONのテンプレートが編集用に表示されます。

\echo text [ ... ]

引数を空白で区切り、標準出力に出力し、改行します。 出力するスクリプトのところどころに情報を記載する場合に有用です。 使用例を次に示します。

=> \echo `date`
Tue Oct 26 21:40:57 CEST 1999

最初の引数が引用符で囲まれていない-nである場合、最後の改行は出力されません。

ティップ: \oコマンドを使用して問い合わせの出力先を変更した場合、このコマンドではなく、\qechoを使用した方が良いでしょう。

\encoding [ encoding ]

クライアント側の文字セット符号化方式を設定します。 引数を指定しない場合、このコマンドは現在の符号化方式を表示します。

\f [ string ]

位置揃えされていない問い合わせの出力用に、フィールドの区切り文字を設定します。 デフォルトは、縦棒("|")です。 一般的な出力オプションの設定方法については、\psetを参照してください。

\g [ { filename | |command } ]

現在の問い合わせ入力バッファをサーバに送ります。 オプションを指定すれば、問い合わせ出力をfilenameに格納したり、その出力を別のUnixシェルに渡し、commandを実行したりすることもできます。 \gだけを指定した場合は、セミコロンと実質的に同じです。 \gに引数を指定した場合は、\oコマンドの"一度限りの"代替手段として使用できます。

\help (or \h) [ command ]

指定したSQLコマンドの構文に関するヘルプを表示します。 commandが指定されていない場合は、psqlは構文ヘルプが存在する全てのコマンドの一覧を表示します。 commandをアスタリスク(*)にすると、全てのSQLコマンドの構文ヘルプが表示されます。

注意: 入力を簡単にするため、複数の単語からなるコマンドを引用符で囲む必要はありません。 \help alter tableと入力するだけで十分です。

\H

HTML問い合わせ出力形式を有効にします。 HTML形式が有効になっている場合は、デフォルトの位置揃えされたテキスト形式に戻します。 このコマンドは互換性と簡便性のために存在します。 他の出力オプションについては、\psetを参照してください。

\i filename

filenameファイルから入力を読み取り、キーボードから入力された場合と同じように実行します。

注意: 読み取られた行を画面に表示させる場合は、ECHO変数をallに設定する必要があります。

\l(または\list
\l+(または\list+

サーバ上の全てのデータベースの名前、所有者、文字セット符号化方式、アクセス権限の一覧を表示します。 コマンド名に+を付けると、データベースのサイズ、デフォルトのテーブル空間、説明も表示します。 (サイズ情報は現在のユーザが接続可能なデータベースでのみ表示されます。)

\lo_export loid filename

データベースからloidというOIDを持つラージオブジェクトを読み取り、filenameに書き出します。 これはlo_exportサーバ関数とは微妙に異なります。 lo_export関数は、データベースサーバを実行しているユーザ権限で、サーバ上のファイルシステムに対して動作します。

ティップ: ラージオブジェクトのOIDを確認するには、\lo_listを使用してください。

\lo_import filename [ comment ]

ファイルをPostgreSQLのラージオブジェクトに保存します。 オプションで、そのオブジェクトに指定したコメントを関連付けることができます。 下記に例を示します。

foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me'
lo_import 152801

上の応答は、指定したラージオブジェクトがオブジェクトID 152801として受け付けられたことを示します。 今後この新規作成されたラージオブジェクトにアクセスする場合に、この番号が使用されます。 可読性を高めるために、常に全てのオブジェクトに人間がわかるようなコメントを関連付けることが推奨されます。 \lo_listコマンドではOIDとコメントの両方が表示されます。

このコマンドは、ローカルなユーザによってローカルなファイルシステムに対して動作します。一方、サーバ側のlo_importは、サーバのユーザによってサーバ上のファイルシステムに対して動作します。 このコマンドとサーバ側のlo_importは、この点で微妙に異なっています。

\lo_list

現在データベースに保存されている全てのPostgreSQLラージオブジェクトの一覧を、そのオブジェクトに付けられたコメントと一緒に表示します。

\lo_unlink loid

loidというOIDが示すラージオブジェクトをデータベースから削除します。

ティップ: ラージオブジェクトのOIDを確認するには、\lo_listを使用してください。

\o [ {filename | |command} ]

以降の問い合わせの結果を、filenameで指定されたファイルに保存するか、または、別のUnixシェルに渡し、commandを実行します。 引数がない場合、問い合わせの出力は標準出力にリセットされます。

"問い合わせの結果"には、全てのテーブル、コマンドの応答、データベースサーバからの注意メッセージだけでなく、データベースに問い合わせを行う(\dのような)各種バックスラッシュコマンドの出力が含まれます。ただし、エラーメッセージは含まれません。

ティップ: 問い合わせの結果の間にテキストを挿入するには、\qechoを使用してください。

\p

現在の問い合わせバッファを標準出力に書き出します。

\password [ username ]

指定したユーザ(デフォルトは現在のユーザ)のパスワードを変更します。 このコマンドは、新しいパスワード、暗号化するかどうかを問い合わせ、それをALTER ROLEコマンドとしてサーバに送信します。 これによりコマンド履歴やサーバログなどどこにも新しいパスワードが平文で残りません。

\prompt [ text ] name

変数nameへの入力をユーザに促します。 省略可能ですがプロンプトtextを指定することができます。 (複数の単語をプロンプトで使用する場合は単一引用符で括ってください。)

デフォルトでは\promptは入出力に端末を使用します。 しかし、-fコマンドラインスイッチが使用されている場合、\promptは標準入力、標準出力を使用します。

\pset parameter [ value ]

このコマンドは問い合わせ結果のテーブル出力に影響するオプションを設定します。 parameterには、どのオプションを設定するのかを記述します。 valueの意味はこのparameterに依存します。

次は、表示の調整に関するオプションです。

format

出力形式をunalignedalignedwrappedhtmllatextroff-msのいずれかに設定します。 一意に判別できる範囲で省略が可能です (この場合、1文字でも十分であることを意味します)。

"Unaligned(揃えない)"は、表示行の1行に1つの行の全列を、現在有効なフィールド区切り文字で区切って書き出します。 このモードは、他のプログラムに読み込ませるタブ区切りやカンマ区切りなどの出力を行うために用意されています。 デフォルトの"Aligned(揃える)"モードは、人間が読みやすいように、美しく整形された標準的なテキスト出力です。

"Wrapped(改行付き)"alignedと似ていますが、指定された幅で出力を折り返します。 \pset columnsがゼロ(デフォルト)ならば、wrappedモードはスクリーン出力にのみに影響を与え、環境変数COLUMNS または検出されたスクリーンの幅で制御された幅で折り返されます。 \pset columnsが非ゼロの値ならば、ファイルやパイプへの出力を含むすべての出力は折り返されます。

columns

wrapped書式の対象幅、幅出力がページャを必要とするかどうかを決める幅を制御します。 ゼロ(デフォルト)では、wrapped書式がスクリーン出力にのみ影響を与えることになります。

border

2番目の引数は数値です。 基本的には、この数字が多くなればなるほど、表示するテーブルが持つ境界線は増えますが、具体的にはそれぞれの出力形式に依存しています。 HTMLモードでは、この値は直接border=...属性に反映されます。 他の形式の場合は、0(境界線なし)、1(内側の境界線)、2(テーブル枠)という3つの数値のみ有効です。

expanded (またはx

省略可能ですが2つ目の引数を指定することができます。 指定する場合は、onまたはoffのいずれかになり、それぞれ拡張モードを有効または無効にします。 2つ目の引数が指定されない場合は、通常形式と拡張形式を切り替えます。 拡張形式を有効にした場合、問い合わせの出力は左に列名、右にデータという2つの列で出力されます。 このモードは、データが通常の"horizontal(水平)"モードによる画面表示に適していない場合に有用です。

拡張モードは4つの全ての形式でサポートされています。

null

2番目の引数は、列がnullの場合に表示する文字列です。 デフォルトでは何も表示しません。 そのため、よく空の文字列と間違うことがあります。 このような場合、\pset null '(null)'を使用する方が良いでしょう。

fieldsep

位置揃えなしの出力モードで使用されるフィールド区切り文字を指定します。 これにより、例えばタブ区切り、カンマ区切りといった他プログラムがよく使用する形式を作成することができます。 タブをフィールド区切り文字として使用するには、\pset fieldsep '\t'と入力します。 デフォルトのフィールド区切り文字は'|'(縦棒)です。

footer

省略可能ですが2つ目の引数を指定することができます。 指定する場合は、onまたはoffのいずれかになり、それぞれデフォルトのフッタ(x rows)を有効または無効にします。 2つ目の引数が指定されない場合は、デフォルトのフッタの表示、非表示を切り替えます。

numericlocale

省略可能ですが2つ目の引数を指定することができます。 指定する場合は、onまたはoffのいずれかになり、それぞれロケールの影響を受ける文字の表示を10進数マーカの左の数字として分離する機能を有効または無効にします。 2つ目の引数が指定されない場合は、有効無効を切り替えます。

recordsep

位置揃えなしの出力モードで使用されるレコード(行)の区切り文字を指定します。 デフォルトは改行文字です。

tuples_only (またはt

省略可能ですが2つ目の引数を指定することができます。 指定する場合は、onまたはoffのいずれかになり、それぞれタプルのみの表示を有効または無効にします。 2つ目の引数が指定されない場合は、タプルのみの表示と完全表示を切り替えます。 完全表示では列のヘッダ、タイトル、各種フッタなどの情報が追加されます。 タプルのみのモードでは、テーブルの実データのみが表示されます。

title [ text ]

今後表示される全てのテーブル用にテーブルタイトルを設定します。 これは出力に説明のためのタグを付けたい場合に有用です。 引数がない場合、タイトルは設定されません。

tableattr (またはT[ text ]

HTMLtableタグ内に記述する任意の属性を指定できます。 これを使用して、例えば、cellpaddingbgcolorを指定することができます。 border属性は既に\pset borderによって処理されているので、このコマンドでborderを指定する必要はありません。

pager

問い合わせ、およびpsqlヘルプ出力の際の、ページャの使用を制御します。 PAGER環境変数が設定されている場合、出力は指定したプログラムにパイプで渡されます。 PAGERが設定されていない場合は、プラットフォーム依存のデフォルト(moreなど)が使用されます。

ページャがoffの時、ページャは使用されません。 ページャがonの時、ページャの使用が適切な場合(つまり、出力先が端末でかつ1画面に納まらない場合)にのみ使用されます \pset pagerはページャの有効無効を切り替えます。 ページャを常時使用することを意味するalwaysに設定することもできます。

節に、これらの形式がどのように見えるかを示した図があります。

ティップ: \psetには各種のショートカットコマンドがあります。 \a\C\H\t\T\xを参照してください。

注意: 引数なしで\psetを呼び出した場合はエラーになります。 今後のバージョンでは、現在の表示用オプションの状態が全て表示されるようになる予定です。

\q

psqlプログラムを終了します。

\qecho text [ ... ]

このコマンドは、\echoと同じです。 ただし、\oによる設定と同様に、出力が問い合わせ出力チャネルに書き出される点が異なります。

\r

問い合わせバッファをリセット(クリア)します。

\s [ filename ]

コマンドラインの履歴の表示、またはfilenameへの保存を行います。 filenameが省略された場合、履歴は標準出力に書き出されます。 このオプションは、コンパイル時に、psqlGNU Readlineライブラリを使用するように設定されている場合のみ使用可能です。

\set [ name [ value [ ... ] ] ]

value、または複数のvalueが与えられた場合はそれらを連結したものを、name内部変数に設定します。 2番目の引数がない場合は、単に変数に値がないものとして設定されます。 変数を未設定とするには、\unsetコマンドを使用してください。

変数名には、文字、数字、アンダースコアを使用することができます。 詳細は、後述の変数を参照してください。 変数名は大文字小文字を区別します。

必要ならばどのようなものでも任意の変数に設定できますが、psqlはいくつかの変数を特別なものとして扱っています。 これらについては変数に関する節にて説明します。

注意: このコマンドはSQLSETコマンドとはまったく別のものです。

\t

出力列名ヘッダと行数フッタの表示を切り替えます。 このコマンドは\pset tuples_onlyと同じで、簡便性のために用意されています。

\T table_options

HTML表形式出力モードにおけるtableタグ内部に記述する属性を指定できます。 このコマンドは\pset tableattr table_optionsと同じ効力を持ちます。

\timing [ on | off ]

パラメータがない場合、各SQL文にかかる時間(ミリ秒単位)の表示の有無を切り替えます。 パラメータがある場合、同じことを設定します。

\w filename または \w |command

現在の問い合わせバッファを、filenameファイルに出力するか、もしくは、command Unixコマンドにパイプで渡します。

\x

拡張テーブル形式モードを切り替えます。 このコマンドは\pset expandedと同じ効力を持ちます。

\z [ pattern ]

使用可能な全てのテーブル、ビュー、シーケンスを、関連付けられているアクセス権限とともに表示します。 patternを指定すると、パターンに名前が一致するテーブル、ビュー、シーケンスのみが表示されます。

GRANTコマンドとREVOKEコマンドは、アクセス権限の設定に使われます。

これは\dp"権限の表示(display privileges)")の別名です。

\! [ command ]

別のシェルを起動するか、もしくは、Unixのcommandコマンドを実行します。 引数はこれ以上解釈されず、そのままシェルに渡されます。

\?

バックスラッシュ("\")コマンドに関するヘルプ情報を表示します。

パターン

\dコマンドでは、patternパラメータを渡して、表示するオブジェクト名を指定することができます。 パターンが正確にオブジェクト名に一致するというのが最も単純な場合です。 パターン内の文字は、SQL名と同様、通常小文字に変換されます。 例えば\dt FOOfooという名前のテーブルを表示します。 SQL名と同様、パターンを二重引用符で括ることで小文字への変換が取り止められます。 二重引用符自体をパターン内に含めなければならない場合、二重引用符で括った文字列の中で二重引用符を二重に記載してください。 繰り返しますが、これはSQLの引用符付き識別子の規則に従ったものです。 例えば、\dt "FOO""BAR"FOO"BARという名前のテーブルを表示します(foo"barではありません)。 SQL名と異なる点は、パターンの一部を二重引用符で括ることができる点です。 例えば、\dt FOO"FOO"BARfooFOObarという名前のテーブルを表示します。

パターン内部では、*は(0文字を含む)任意の文字の並びに一致し、?は任意の1文字に一致します。 (この記法はUnixシェルのファイル名パターンと似ています。) 例えば、\dt int*は、intから始まる名前を持つすべてのテーブルを表示します。 しかし、二重引用符の中では、*?はその特別な意味を失い、文字そのものに一致することになります。

ドット(.)を含むパターンは、スキーマ名にオブジェクト名が続くパターンとして解釈されます。 例えば、\dt foo*.*bar*は、fooで始まるスキーマ内のbarを含むテーブルを全て表示します。 ドットがない場合、パターンは現行のスキーマ検索パス内で可視的なオブジェクトのみに一致します。 繰り返しますが、二重引用符で括られた文字列内のドットは特別な意味を失い、文字そのものに一致することになります。

上級者は文字クラスに、例えば任意の数に一致する[0-9]などの正規表現を使用することができます。 上述のように.が区切り文字となる点、*は正規表現の.*記法になる点、?.になる点、$がそのまま扱われる点は例外ですが、すべての正規表現の特殊文字が項9.7.3の規定通りに動作します。 .?と、R*(R+|)と、R?(R|)と記述することで、これらのパターン文字を模擬することができます。 $を正規表現文字として扱う必要はありません。 通常の正規表現の解釈と異なり、パターンは常に名前全体に一致するためです。 (言い替えると、$は自動的にパターンに追加されます。) パターンの適用位置を決められない場合は、*を先頭や末尾に記載してください。 二重引用符の内側では、正規表現の特殊文字はその意味を失い、文字そのものに一致することになる点に注意してください。 また、正規表現の特殊文字は、演算子名パターン( つまり\doの引数)では文字そのものに一致します。

patternパラメータが完全に省略されている場合、\dコマンドは現在のスキーマ検索パス内で可視的なオブジェクトを全て表示します。 これは*というパターンを使用することと同じです。 データベース内の全てのオブジェクトを表示するには、*.*というパターンを使用します。

高度な機能

変数

psqlは一般的なUnixコマンドシェルに似た変数の置換機能を提供します。 変数とは名前と値の組み合わせです。 値として任意の長さの任意の文字列を使用できます。 変数を設定するには、psql\setメタコマンドを以下のように使用します。

testdb=> \set foo bar

この例では、foo変数をbarという値に設定しています。 変数の内容を取り出すには、以下のように変数名の前にコロンを付けて、任意のスラッシュコマンドの引数として使用します。

testdb=> \echo :foo
bar

注意: \setの引数は他のコマンドと同じ置換規則に従います。 このため、\set :foo 'something'のような参照を作成して、Perlにおける"ソフトリンク"PHPにおける"可変変数"に当たるものを得られます。 しかし、残念ながら(あるいは好運にも)、このような構成をうまく使用する方法はありません。 一方、\set bar :fooのようにして変数をコピーするのは、完全に有効な方法です。

2番目の引数を指定せずに\setを実行した場合、値として空文字列を持つ変数として設定されます。 変数を未設定にする(削除する)には、\unsetコマンドを使用してください。

psqlの内部変数名は文字、数字、アンダースコアから構成されます。順番や長さには制限がありません。 これらの変数の多くは、psqlに特別扱いされており、 実行時に変更可能なアプリケーションの状態やオプションの設定を表す値を持っています。 これらの変数を別の目的で使用することもできますが、即座にプログラムの動作がおかしくなる可能性があるため、推奨されません。 慣習上、特別視される変数は全て大文字(と数字とアンダースコア)からなります。 将来的な互換性を最大限考慮するために、自分で作成した変数にはこのような変数名を使用しないでください。 以下に特別に取り扱われる変数の一覧を示します。

AUTOCOMMIT

この変数の値がonの場合(自動コミット有効モード:デフォルト)、各SQLコマンドの実行が成功すると、自動的にコミットされます。 コミットを延期するには、BEGINもしくはSQLのSTART TRANSACTIONコマンドを入力する必要があります。 値がoffもしくは未設定の場合(自動コミット無効モード)、明示的にCOMMITもしくはENDを発行するまで、SQLコマンドはコミットされません。 自動コミット無効モードでは、トランザクションブロック以外でコマンドが発行されると、そのコマンドを実行する前に、自動的にBEGINコマンドが発行されます(ただし、そのコマンド自体がBEGINコマンドやその他のトランザクション制御コマンドである場合、トランザクションブロック内で実行することができないコマンド(VACUUMなど)である場合は除きます)

注意: したがって、自動コミット無効モードでは、ABORTROLLBACKを発行して、明示的に失敗したトランザクションを放棄しなければなりません。 また、コミットせずにセッションを終了した場合は、作業が失われてしまうので注意してください。

注意: PostgreSQLは、伝統的に自動コミット有効モードで動作していましたが、自動コミット無効モードの方がよりSQLの仕様に近いものです。 自動コミット無効モードは、システム全体に対するpsqlrcファイル、もしくは、個人用の.psqlrcファイルで設定すれば実現できます。

DBNAME

現在接続しているデータベース名です。 この変数は(プログラム起動時も含め)データベースに接続する度に設定されますが、これを未設定にすることもできます。

ECHO

allを設定した場合、キーボード、もしくは、スクリプトからの取得された全ての行は、解析/実行の前に標準出力に書き出されます。 この動作をプログラム起動時に設定するには、-aスイッチを使用してください。 queriesを設定した場合、psqlはサーバに送信された問い合わせのみを表示します。 これらを切り替えるオプションは-eです。

ECHO_HIDDEN

この変数が設定されている場合、バックスラッシュコマンドでデータベースに問い合わせを行う時、最初にその問い合わせが表示されます。 これにより、PostgreSQL内部動作について調べたり、自作プログラム内で同様の関数機能を用意したりすることが可能になります (この動作をプログラム起動時に選択するには-Eスイッチを使用してください)。 この変数をnoexecという値に設定した場合、問い合わせは実際にサーバに送信、実行されずに、単に表示されるだけになります。

ENCODING

現在のクライアント側の文字セット符号化方式です。

FETCH_COUNT

この変数が0より大きな整数値に設定されている場合、SELECT問い合わせの結果は、指定した行数の集合として取り出され、表示されます。 デフォルトの動作では、表示する前にすべての結果が取り出されます。 したがって、結果セットの大きさに比例する形でメモリの使用量が限定されます。 この機能を有効とする場合に100から1000までの値がよく使用されます。 この機能を使用する際には、既に一部の行が表示されている場合、問い合わせが失敗する可能性があることに注意してください。

ティップ: 任意の出力書式でこの機能を使用することができますが、デフォルトのaligned書式は適していません。 FETCH_COUNT行のグループそれぞれが別々に整形されてしまい、行のグループによって列幅が異なることになるためです。 他の出力書式は適切に動作します。

HISTCONTROL

この変数をignorespaceに設定した場合、空白文字から始まる行は履歴リストには入りません。 ignoredupsに設定した場合、これまでの履歴にある行は履歴リストに入りません。 ignorebothに設定した場合は、上記の2つを組み合わせたものになります。 この変数を設定しない場合、または上記以外の値を設定する場合は、対話モードで読まれる全ての行が履歴リストに保存されます。

注意: この機能はBashの機能を真似たものです。

HISTFILE

履歴を格納するために使用されるファイルの名前です。 デフォルトは~/.psql_historyです。 例えば、~/.psqlrcで以下を記述すると、psqlはデータベース毎に分けて履歴を管理します。

\set HISTFILE ~/.psql_history- :DBNAME

注意: この機能はBashの機能を真似たものです。

HISTSIZE

コマンド履歴に保存するコマンド数です。 デフォルト値は500です。

注意: この機能はBashの機能を真似たものです。

HOST

接続中のデータベースサーバホストです。 この変数は(プログラム起動時も含め)データベースに接続する度に設定されますが、未設定にすることもできます。

IGNOREEOF

この変数を未設定にすると、対話式セッションにEOF文字(通常Control+D)が送信された時、psqlが終了します。 数値を設定すると、指定された数だけ、送信されたEOF文字を無視してから終了します。 数値以外を設定した場合は、デフォルトの10になります。

注意: この機能はBashの機能を真似たものです。

LASTOID

INSERTlo_insertコマンドによって返された、最後に影響を受けたOIDの値です。 この変数は、次のSQLコマンドの結果が表示されるまでの間のみ保証されています。

ON_ERROR_ROLLBACK

onの場合、トランザクションブロック内である文がエラーとなった時に、そのエラーは無視され、トランザクションは継続します。 interactiveの場合、対話式セッション内の場合にのみエラーは無視されます。スクリプトファイルを読み込んでいる場合は無視されません。 off(デフォルト)の場合、トランザクションブロック内の文がエラーになると、トランザクション全体をアボートします。 ON_ERROR_ROLLBACKがonという状態は、トランザクションブロック内で各コマンドの実行直前に暗黙的なSAVEPOINTを行い、エラーが起きた時にこのセーブポイントにロールバックすることで実現されています。

ON_ERROR_STOP

デフォルトでは、非対話式スクリプトにて、SQLコマンドや内部メタコマンドにおいてエラーが発生した場合、処理は続行されます。 これはpsqlの旧来からの動作ですが、好ましくない場合もあります。 そこで、この変数を設定しておくと、エラー発生時に、処理中のスクリプトが即座に停止します。 スクリプトが他のスクリプトから呼ばれていた場合は、呼び出し元のスクリプトも同様に停止します。 最も外側のスクリプトがpsqlの対話式セッションからではなく、-fオプションを使って呼び出されていた場合、psqlは致命的エラー条件(エラーコード1)と区別するためにエラーコード3を返します。

PORT

接続中のデータベースサーバのポートです。 この変数は(プログラム起動時も含め)データベースに接続する度に設定されますが、未設定にすることもできます。

PROMPT1
PROMPT2
PROMPT3

これらの変数は、psqlが発行するプロンプトの見た目を指定します。 後述のプロンプトを参照してください。

QUIET

この変数は-qコマンドラインオプションと同じ効力を持ちます。 対話式モードではあまり役立ちません。

SINGLELINE

この変数は-Sコマンドラインオプションと同じ効力を持ちます。

SINGLESTEP

この変数は-sコマンドラインオプションと同じ効力を持ちます。

USER

接続中のデータベースユーザです。 この変数は(プログラム起動時も含め)データベースに接続する度に設定されますが、未設定にすることもできます。

VERBOSITY

この変数をdefaultverboseterseのいずれかに設定することで、エラー報告の冗長性を制御できます。

SQL差し替え

さらにpsqlの変数には、正規のSQL文の中で使用("差し替え:interpolate")できるという便利な機能があります。 この機能を利用するには、前述のように、変数名の前にコロン(:)を付加してください。

testdb=> \set foo 'my_table'
testdb=> SELECT * FROM :foo;

この例では、問合せはmy_tableテーブルに対して行われます。 変数の値はそのままコピーされるので、対応のとれていない引用符やバックスラッシュコマンドさえも含めることができます。 挿入した場所で変数が展開された時に、確実に正しい意味になるようにしなければなりません。 引用符で囲まれたSQLの項目では、変数の差し換えは行われません。

この機能の有効な利用方法の1つは、ファイルの内容をテーブル列にコピーする場合も利用することができます。 その際は、ファイルをまず変数に読み込み、上と同様の処理を行います。

testdb=> \set content '''' `cat my_file.txt` ''''
testdb=> INSERT INTO my_table VALUES (:content);

この方法には1つ問題があります。それは、my_file.txtに単一引用符が含まれている可能性があるという問題です。 上記の2行目における構文エラーを防ぐためには、この文字をエスケープする必要があります。 sedプログラムを使って次のようにすれば、単一引用符をエスケープすることができます。

testdb=> \set content '''' `sed -e "s/'/''/g" < my_file.txt` ''''

標準非準拠の文字列を使用しているのであれば、さらにバックスラッシュを二重にしなければなりません。 以下のように多少ややこしくなります。

testdb=> \set content '''' `sed -e "s/'/''/g" -e 's/\\/\\\\/g' < my_file.txt` ''''

異なるシェルの引用符記法を使用していることに注意してください。この単一引用符記号やバックスラッシュともシェルには特別なものではありません。 sedにとっては特別な意味を持ちますので、バックスラッシュはまだ二重にしなければなりません。 (たぶん、ある時点では、全てのUnixコマンドが同一のエスケープ文字を使用することは素晴らしいと考えたでしょう。)

コロン(:)もSQLコマンド自体で使用できるので、次の規則が適用されます。 "name"という文字列が現時点で設定済みの変数名でない時は、":name"という文字列は変更されません。 コロンをバックスラッシュでエスケープすれば、常に置換されなくなります (変数用のコロン構文は、ECPGのような組み込みの問い合わせ言語用のSQL標準として規定されています。 配列の一部の切り出し、および型キャスト用のコロン構文はPostgreSQLの拡張であり、競合しています)。

プロンプト

psqlが発行するプロンプトは好みに応じてカスタマイズできます。 PROMPT1PROMPT2PROMPT3という3つの変数はプロンプトの表示内容を示す文字列や特別なエスケープシーケンスを持ちます。 プロンプト1はpsqlが新しいコマンドを受け付ける際に発行される通常のプロンプトです。 プロンプト2はコマンドがセミコロンで終わっていない、または、引用符が閉じていないためにさらにコマンドの入力が要求されている際に発行されます。 プロンプト3はSQLCOPYコマンドを実行している際、または、端末上で行の値の入力が要求されている際に発行されます。

選択されたプロンプト変数の値はそのまま文字として表示されます。 ただし、パーセント(%)が含まれる場合は例外です。 この場合は、次の文字に従って、特定のテキストに置換されます。 置換対象として定義されているのは次のものです。

%M

データベースサーバの(ドメイン名付きの)完全なホスト名です。その接続がUnixドメインソケットの場合は[local]となります。 ただし、Unixドメインソケットがコンパイル時に設定したデフォルトの場所に存在しない場合は、[local:/dir/name]となります。

%m

最初のドットで取り除いたデータベースサーバのホスト名です。その接続がUnixドメインソケットの場合は[local]となります。

%>

データベースサーバが監視するポート番号です。

%n

データベースセッションユーザの名前です (この値の展開結果は、SET SESSION AUTHORIZATIONコマンドの実行によってデータベースセッション中に変わることがあります)。

%/

接続中のデータベース名です。

%~

デフォルトデータベースの場合に~(チルダ)が出力される点を除いて、%/と同じです。

%#

セッションユーザがデータベーススーパーユーザである場合は#、それ以外の場合は>となります (この値の展開結果は、SET SESSION AUTHORIZATIONコマンドの実行によってデータベースセッション中に変わることがあります)。

%R

プロンプト1の場合、通常は=、シングル行モードでは^、データベースとの接続が切れたセッションでは!になります(\connectが失敗した場合に発生します)。 プロンプト2の場合、-*、単一引用符、二重引用符、ドル記号に置き換えられます。どの文字に置き換えられるかは、psqlが入力を待っている理由(コマンドが終了していない、/* ... */によるコメント行の中にいる、引用符やエスケープされたドル記号の中にいる)によって決まります。 プロンプト3の場合、何も表示されません。

%x

トランザクションの状態です。 トランザクションブロックの外にいる場合は空文字列に、トランザクションブロックの中にいる場合は*に、失敗したトランザクションブロックの中にいる場合は!に、(接続されていないなど)トランザクションの状態が不定の場合は?になります。

%digits

指定8進数値コードの文字に置換されます。

%:name:

psqlname変数の値です。 詳細は変数を参照してください。

%`command`

通常の"逆引用符"による置き換えに似た、commandの出力です。

%[ ... %]

プロンプトには端末制御文字を含めることができます。 具体的には、色の変更、背景、プロンプトテキストの様式、端末ウィンドウのタイトルなどが指定できます。 Readlineの行編集機能を適切に動作させるためには、印字されない制御文字を%[%]で囲んで、不可視であることを明示しなければなりません。 この記号の組み合わせはプロンプト内に複数記述することができます。 以下に例を示します。

testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# '

これにより、VT100互換の配色可能な端末では、ボールドフォントで(1;)、黄色で点滅する(33;40)プロンプトが表示されます。

プロンプトにパーセント記号を入れる場合は、%%と記述してください。 デフォルトのプロンプトは、プロンプト1と2に'%/%R%# '、プロンプト3に'>> 'を設定した場合と同じです。

注意: この機能はtcshの機能を真似たものです。

コマンドライン編集

psqlは行内編集や繰り返し入力が簡便になるようにReadlineライブラリをサポートしています。 コマンド履歴は、psqlの終了時に自動的に保存され、psqlの起動時に再読み込みされます。 タブによる補間もサポートされていますが、SQLのパーサとしてコマンドを解釈して判断してくれるわけではありません。 タブによる補間を何らかの事情により使用したくなければ、ホームディレクトリ以下の.inputrcというファイルに以下のように書き込むことで無効にできます。

$if psql
set disable-completion on
$endif

(これはpsqlの機能ではなく、Readlineの機能です。 詳細についてはReadlineのドキュメントを参照してください)。

環境

COLUMNS

\pset columnsがゼロの場合、wrapped書式の幅、および、幅出力がページャを必要とするかどうかを決める幅を制御します。

PAGER

問い合わせ結果が画面に入り切らない場合、このコマンドによって結果をパイプします。 一般的に指定される値は、more、またはlessです。 デフォルトはプラットフォームによって異なります。 ページャの使用を禁止するには\psetコマンドを使用します。

PGDATABASE
PGHOST
PGPORT
PGUSER

デフォルトの接続パラメータです(項30.13を参照)。

PSQL_EDITOR
EDITOR
VISUAL

\eコマンドが使用するエディタです。 変数はこのリスト順に検索されます。 つまり最初に設定されたものが使用されます。

SHELL

\!コマンドが実行するコマンドです。

TMPDIR

一時ファイルを格納するディレクトリです。 デフォルトは/tmpです。

また、このユーティリティは、他のほとんどのPostgreSQLユーティリティと同様、libpqでサポートされる環境変数を使用します(項30.13を参照してください)。

ファイル

注釈

Windowsユーザ向けの注意

psql"コンソールアプリケーション"としてコンパイルされます。 Windowsのコンソールウィンドウは、システムの他の部分とは異なる符号化方式を使用しているので、psqlで8ビット文字を使用する時には特別な配慮が必要です。 psqlは、コンソール用コードページとして問題があることを検出すると、起動時に警告を発します。 コンソール用コードページを変更するためには、以下の2つが必要です。

最初に、複数行にわたるコマンドの入力例を示します。 プロンプトの変化に注意してください。

testdb=> CREATE TABLE my_table (
testdb(>  first integer not null default 0,
testdb(>  second text)
testdb-> ;
CREATE TABLE

さて、ここでテーブル定義を再度確認してみます。

testdb=> \d my_table
             Table "my_table"
 Attribute |  Type   |      Modifier
-----------+---------+--------------------
 first     | integer | not null default 0
 second    | text    |

次に、プロンプトをもっと面白いものに変更してみます。

testdb=> \set PROMPT1 '%n@%m %~%R%# '
peter@localhost testdb=>

テーブルにデータを入力したものと考えてください。データを見る場合は次のようにします。

peter@localhost testdb=> SELECT * FROM my_table;
 first | second
-------+--------
     1 | one
     2 | two
     3 | three
     4 | four
(4 rows)

\psetコマンドを使って、このテーブルの表示を違うタイプに変更することができます。

peter@localhost testdb=> \pset border 2
Border style is 2.
peter@localhost testdb=> SELECT * FROM my_table;
+-------+--------+
| first | second |
+-------+--------+
|     1 | one    |
|     2 | two    |
|     3 | three  |
|     4 | four   |
+-------+--------+
(4 rows)

peter@localhost testdb=> \pset border 0
Border style is 0.
peter@localhost testdb=> SELECT * FROM my_table;
first second
----- ------
    1 one
    2 two
    3 three
    4 four
(4 rows)

peter@localhost testdb=> \pset border 1
Border style is 1.
peter@localhost testdb=> \pset format unaligned
Output format is unaligned.
peter@localhost testdb=> \pset fieldsep ","
Field separator is ",".
peter@localhost testdb=> \pset tuples_only
Showing only tuples.
peter@localhost testdb=> SELECT second, first FROM my_table;
one,1
two,2
three,3
four,4

その他の方法として、短縮されたコマンドを使用してみます。

peter@localhost testdb=> \a \t \x
Output format is aligned.
Tuples only is off.
Expanded display is on.
peter@localhost testdb=> SELECT * FROM my_table;
-[ RECORD 1 ]-
first  | 1
second | one
-[ RECORD 2 ]-
first  | 2
second | two
-[ RECORD 3 ]-
first  | 3
second | three
-[ RECORD 4 ]-
first  | 4
second | four