他のバージョンの文書11 | 10 | 9.6 | 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

Name

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

Synopsis

psql [options] [dbname [user]]

説明

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

オプション

-a
--echo-all

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

-A
--no-align

位置揃え無しの出力モードに切替えます。(さもなければ、デフォルトの位置揃えされた出力モードになります。)

-c query
--command query

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

query は、バックエンドで完全に解析可能な問い合わせ文字列 (つまり、psql 特有の機能は含まない)、もしくは、1 つのバックスラッシュコマンドである必要があります。このため SQLpsql メタコマンドを混在させることはできません。以下の様にパイプを使ってその文字列を psql に渡すことで混在させることができます。echo "\x \\ select * from foo;" | psql.

-d dbname
--dbname dbname

接続するデータベースの名前を指定します。これはコマンドラインでオプション形式でない最初の引数として dbname を指定することと同じです。

-e
--echo-queries

バックエンドに送られた問い合わせを全て表示します。これは ECHO 変数を queries に設定することと同じです。

-E
--echo-hidden

\d やその他のバックスラッシュコマンドによって生成される実際の問い合わせを表示します。これを使って、自作のプログラムに似たような機能を含めることができます。これは 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

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

-H
--html

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

-l
--list

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

-o filename
--output filename

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

-p port
--port port

postmaster が接続監視を行なっている、TCP/IP ポート、もしくは、(ホスト名が) 省略された場合は、ローカルな 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

セミコロンと同様に改行が問い合わせの終端となる、シングル行モードで実行します。

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

-t
--tuples-only

カラム名と結果の行数フッタなどの表示を無効にします。 これは、\t メタコマンドと全く同じです。

-T table_options
--table-attr table_options

HTML table タグ内に記述されるオプションを指定できます。詳細については \pset を参照して下さい。

-u

データベース接続の前に psql がユーザ名とパスワードを尋ねるプロンプトを表示します。

概念的な欠陥のため、このオプションは推奨されません。(デフォルトではないユーザ名の入力とバックエンドからの要求によるパスワード入力とは全く異なるものです。)代替である、-U-W オプションを参照することを勧めます。

-U username
--username username

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

-v assignment
--set assignment
--variable assignment

\set 内部コマンドのように、変数の代入を行ないます。値がもしあれば、コマンドラインで名前と値を等号で区切る必要があることに注意して下さい。変数を未設定にするためには、等号を取って下さい。値なしの変数を設定するためには、値なしで等号のみ使用して下さい。これらの代入は起動時の非常に早い段階で行なわれます。そのため、内部目的用に予約された変数は後で上書きされる可能性があります。

-V
--version

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

-W
--password

データベース接続前にパスワード入力を促すように psql に対して要求します。\connect メタコマンドを使用して接続するデータベースを変更した場合であっても、セッション全体用の設定として保持します。

現在のバージョンでは、psql はバックエンドがパスワード認証を要求した時は常に自動的にパスワードプロンプトを表示します。現在これは "ハック" されたものに基づいていますので、自動認識が予想できない失敗をする可能性があります。 そのため、このオプションを使って強制的にプロンプトを表示させます。バックエンドがパスワード認証を要求した時にパスワードプロンプトが表示されない場合、その接続の試行は失敗します。

-x
--expanded

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

-X,
--no-psqlrc

~/.psqlrc 起動用ファイルを読み込みません。

-?
--help

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

長いオプション形式は限られたプラットホームでしか使用できません。

終了状態

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

使用方法

データベースへの接続

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

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

問い合わせの入力

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

$ psql testdb
Welcome to psql 7.3.4, the PostgreSQL interactive terminal.

Type:  \copyright for distribution terms
       \h for help with SQL commands
       \? for help on internal slash commands
       \g or terminate with semicolon to execute query
       \q to quit

testdb=>

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

また、問い合わせが実行される度に、psqlLISTENNOTIFY によって生成された非同期通知イベントをチェックします。

メタコマンド

psql 内で、入力されたもので、引用符で囲まれておらず、バックスラッシュで始まるものは psql 自身によって実行される、psql のメタコマンドです。これらのコマンドは管理のためやスクリプトのために、psql を興味深いものとします。メタコマンドは一般的にスラッシュコマンド、またはバックスラッシュコマンドと呼ばれます。

psql コマンドの形式はバックスラッシュ、その直後にコマンドの動詞、その次に引数がきます。引数と動詞コマンド、またそれぞれの動詞コマンドは空白文字によって区別します。

引数に空白を含める場合、これらは単一引用符で囲みます。単一引用符を引数に含める場合には、その単一引用符の前にバックスラッシュをつけて下さい。単一引用符で囲われたものは、\n (改行)、\t (タブ)、\digits\0digits\0xdigits (与えられた10進数、8進数、16進数の文字) の C 言語風の置換文字の対象となります。

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

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

コマンドには、引数として SQL の (テーブル名などの) 識別子を取るものがあります。これらの引数は SQL の二重引用符などの構文規則に従います。 例えば二重引用符を伴わない識別子は強制的に小文字になる、あるいは、二重引用符内の空白文字は引数に含まれる、などです。

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

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

\a

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

\cd [directory]

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

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

\C [ title ]

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

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

新しいデータベースへの接続または、指定ユーザ名での接続を行ないます。それまでの接続は閉じられます。dbname- の場合、現在のデータベース名が使われます。

username が省略された場合、現在のユーザ名が使用されます。

特別な規則として、引数がない \connect の場合は、デフォルトのデータベースにデフォルトのユーザで接続します (何も引数なしで psql を起動した場合と同じことになります)。

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

\copy table [ ( column_list ) ] { from | to } filename | stdin | stdout [ with ] [ oids ] [ delimiter [as] 'character' ] [ null [as] 'string' ]

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

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

Tip: この操作は SQL COPY コマンドほど効率よくはありません。 というのは、全てのデータがクライアント/サーバ IP 接続かソケット接続を通じてやりとりされなくてはならないからです。データ量が多いときは他の手法を使用する方がよいでしょう。

Note: フロントエンドコピーとバックエンドコピーとでは、stdin 及び stdout の解釈に違いがあることに注意して下さい。フロントエンドコピーでは、これらは常に psql の入出力ストリームを参照します。バックエンドコピーでは、stdinCOPY 自体が読みとるところから読みとります (例えば、-f オプションで実行するスクリプト)。 そして stdout は、問い合わせ出力ストリーム (後述の \o メタコマンドを参照して下さい) を参照します。

\copyright

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

\d [ pattern ]

pattern に一致する各リレーションについて、すべての列、それらの型、そして NOT NULL やデフォルトなどの特別な属性を表示します。 ビューリレーションの場合は、ビューの定義に従い、関連付けられているインデックス、制約、ルールおよびトリガも表示されます。 ("パターンのマッチング" は下記で説明します。)

\d+ という形のコマンドも同じですが、テーブルの列に関連付けられた全てのコメントも表示されます。

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

\da [ pattern ]

利用できる全ての集約関数と、その操作対象となるデータ型の一覧を表示します。pattern (正規表現) が指定された場合、一致する集約のみが表示されます。

\dd [ pattern ]

pattern に一致するオブジェクトの説明を表示します。引数が指定されていない場合は、可視的なオブジェクトすべての説明を表示します。 どちらの場合でも、説明があるオブジェクトのみがリストされます。 ("オブジェクト" には、集約、関数、演算子、型、リレーション (テーブル、ビュー、インデックス、シーケンス、ラージオブジェクト) が含まれます)。例を下記に示します。

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

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

Note: PostgreSQL はオブジェクトの説明を pg_description システムテーブルに保存します。

\dD [ pattern ]

使用可能なドメイン (派生型) をすべて表示します。 pattern が指定されている場合は、一致するドメインのみが表示されます。

\df [ pattern ]

利用できる全ての関数と、その引数と戻り値の型の一覧を表示します。 pattern が指定されている場合は、一致する関数のみが表示されます。\df+ という形で使われた場合、各関数の言語や説明を含む付加的情報も表示されます。

Note: 不要な情報を減らすため、\df はデータ型 I/O 関数を表示しません。 これは、cstring データ型を受け入れたり返したりする関数を無視することで実装されます。

\distvS [ pattern ]

これは実際のコマンドの名前ではなく、i、s、t、v、S という文字はそれぞれ、インデックス、シーケンス、テーブル、ビュー、システムテーブルを意味します。 これらの文字のうち任意のものまたはすべてを、任意の順番で指定して、一致するすべてのオブジェクトの一覧を表示することができます。 文字 S を指定すると、システムオブジェクトのみが表示されます。 S を指定しなければ、システムオブジェクト以外のオブジェクトのみが表示されます。 コマンド名の後に "+" を付加すると、各オブジェクトに関連付けられている説明も (存在すれば) 表示されます。

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

\dl

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

\do [ pattern ]

利用できる演算子と、その演算項目 (オペランド) と戻り値を一覧表示します。 pattern を指定すると、パターンに名前が一致する演算子のみが表示されます。

\dp [ pattern ]

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

GRANT コマンドと REVOKE コマンドは、アクセス権限の設定に使われます。 詳細については GRANT を参照して下さい。

\dT [ pattern ]

全てのデータ型、または、pattern に一致する型のみを一覧表示します。 \dT+ という形式のコマンドは補足情報も表示します。

\du [ pattern ]

すべてのデータベースユーザ、もしくは、pattern に一致するユーザのみを一覧表示します。

\edit (or \e) [ filename ]

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

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

Tip: psql は環境変数 PSQL_EDITOREDITORVISUAL を (この順番に) 検索し、使用するエディタを決定します。これら全てが未設定である場合は、/bin/vi が実行されます。

\echo text [ ... ]

引数をスペースで区切り、標準出力に出力し、改行します。スクリプトの出力に、情報を点在させる場合に有用です。例を下記に示します。

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

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

Tip: \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 コマンドの構文ヘルプが表示されます。

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

\H

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

\i filename

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

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

\l (or \list)

サーバ上のすべてのデータベースとその所有者の一覧を表示します。このコマンドに "+" を追加することで、そのデータベースに関する全ての説明も表示することができます。PostgreSQL のインストール時にマルチバイトコーディングをサポートするようにコンパイルしていた場合、各データベースのエンコード方式の名称も表示されます。

\lo_export loid filename

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

Tip: ラージオブジェクトの OID を確認するためには、\lo_list を使用して下さい。

Note: ラージオブジェクトに対する全ての操作に関わる重要な情報について、LO_TRANSACTION 変数の説明を参照して下さい。

\lo_import filename [ comment ]

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

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

上の応答は、そのラージオブジェクトをオブジェクト ID 152801 として受け付けられたことを示します。 今後再びそのラージオブジェクトにアクセスしたい場合はこの番号を記憶しておかなければなりません。このため、全てのオブジェクトに人間がわかるようなコメントを常に関連づけることを推奨します。このコメントは \lo_list コマンドを使用して参照することができます。

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

Note: ラージオブジェクトに対する全ての操作に関わる重要な情報について、LO_TRANSACTION 変数の説明を参照して下さい。

\lo_list

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

\lo_unlink loid

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

Tip: ラージオブジェクトの OID を確認するためには、\lo_list を使用して下さい。

Note: ラージオブジェクトに対する全ての操作に関わる重要な情報について、LO_TRANSACTION 変数の説明を参照して下さい。

\o [ {filename | |command} ]

以降の問い合わせの結果を filename ファイルに保存、もしくは、以降の問い合わせの結果を別個の Unix シェルに渡し、command を実行します。引数がない場合、問い合わせの出力は stdout にリセットされます。

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

Tip: 問い合わせの結果の間にテキストを点在させるためには、\qecho を使用して下さい。

\p

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

\pset parameter [ value ]

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

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

format

出力形式を unalignedalignedhtml、または latex のいずれかに設定します。一意に判別されるならば省略が可能です。(1文字でも十分であることを意味します。)

"Unaligned (揃えない)" は、1行に1つのタプルの全フィールドを、現在有効なフィールド区切り文字で区切って書き出します。これは、他のプログラムによって読み込む予定の (タブ区切りやカンマ区切りといった) 出力を作成することを意図しています。デフォルトの "Aligned (揃える)" モードは、標準的で、人による可読性の高い、きれいに整形されたテキスト出力です。"HTML""LaTeX" モードは、対応するマークアップ言語の文書に含めることができるようにテーブルを出力します。この出力は完全な文書ではありません。(これは HTML の場合は大したことではありませんが、LaTeX の場合は必ず完全な文書になるようにラッパーを作成しなければなりません。)

border

2 番目の引数は数字です。通常はこの数字が多くなればなるほど、表示するテーブルが持つ境界線は太くなりますが、これは特定の形式に依存しています。HTML モードでは、この値は直接 border=... 属性に反映されます。 他の形式の場合は、0 (境界線なし)、1 (内側の境界線)、2 (テーブル枠) という数のみが有効です。

expanded (or x)

通常形式と拡張形式を切替えます。拡張形式が有効な場合、全ての出力は左にフィールド名、右にデータという 2 つの列を持ちます。このモードはデータが通常の "horizontal (水平)" モードによる画面表示に適していない場合に有用です。

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

null

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

fieldsep

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

footer

デフォルトのフッタ (x rows) の表示、非表示を切替えます。

recordsep

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

tuples_only (or t)

タプルのみの表示と完全表示を切替えます。完全表示ではカラムのヘッダやタイトル、各種フッタといった余計かもしれない情報も表示します。タプルのみのモードでは、テーブルの実データのみが表示されます。

title [ text ]

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

Note: これは、以前までは HTML モードでしか影響しませんでした。現在では全ての出力形式においてタイトルを設定することができます。

tableattr (or T) [ text ]

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

pager

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

いかなる場合でも、ページャの使用が適切と見なされる場合にのみ、psql はそのページャを使用します。これはとりわけ、出力が端末であること、および、テーブルが通常画面表示に適していない場合です。表示ルーチンのモジュールの性質により、実際に表示される行数を常に予測することはできません。 このため、psql はページャを使用する場合と使用しない場合を明確に区別することができません。

節に、これらの形式の違いがどのように見えるかについての図があります。

Tip: \pset には各種のショートカットコマンドがあります。\a\C\H\t\T、及び、\x を参照して下さい。

Note: 引数なしで \pset を呼び出した場合はエラーになります。将来、この呼出によって、現在の全ての表示用オプションの状態を表示するようになる予定です。

\q

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

\qecho text [ ... ]

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

\r

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

\s [ filename ]

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

Note: 現在のバージョンでは、プログラムの終了時に自動的に保存されるようになりましたので、コマンドの履歴を保存する必要が無くなりました。この履歴は psql の起動の度に自動的に読み込まれます。

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

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

変数名には、文字、数字、アンダースコアを使用することができます。詳細については、psql の変数に関する節を参照して下さい。

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

Note: このコマンドは SET SQL コマンドとは全く別のものです。

\t

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

\T table_options

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

\timing

各 SQL 文にかかる時間 (ミリ秒) の表示を切り替えます。

\w {filename | |command}

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

\x

拡張行形式モードを切替えます。このコマンドは \pset expanded と同じものです。

\z [ pattern ]

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

GRANT コマンドと REVOKE コマンドは、アクセス権限の設定に使われます。 詳細については GRANT を参照して下さい。

これは \dp ("display permissions") の別名です。

\! [ command ]

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

\?

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

さまざまな \d コマンドは pattern パラメータを受け入れ、表示されるオブジェクト名を指定できます。 パターンは SQL 識別子と同様、引用符で囲んでいない文字を小文字に変換して解釈します。一方、二重引用符 (") を使用すると、大文字小文字は変換されることなく保護され、識別子に空白を含めることもできます。 二重引用符内の二重引用符の組は、結果の名前において単一の二重引用符になります。 例えば、FOO"BAR"BAZfooBARbaz と解釈されますが、"A weird"" name"A weird" name と解釈されます。

さらに、\d パターンで、*"任意の連続した文字" を表し、?"任意の単一文字" を表します。 (この表記は Unix シェルのファイル名パターンと同様です。) 上級ユーザであれば、文字クラスなどの正規表現表記 (例えば"任意の数字" に一致する [0-9]) を使用することもできます。 これらのパターンマッチング文字が文字通り解釈されるようにするには、これらを二重引用符で囲みます。

(引用符なしの) ドットを含むパターンは、スキーマ名にオブジェクト名が続くパターンとして解釈されます。 例えば、 \dt foo*.bar* は、foo で始まるスキーマ内の bar で始まるテーブルをすべて表示します。 ドットがない場合、パターンは現行のスキーマ検索パス内で可視的であるオブジェクトのみに一致します。

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

高度な機能

変数

psql は、一般的な Unix コマンドシェルに似た変数の置換機能を提供します。この機能は新しいためまだあまり洗練されていませんが、今後拡張していく予定です。変数は単なる名前と値の組合せです。 値として任意の長さの任意の文字を使うことができます。変数の設定にはpsql\set メタコマンドを以下のように使用します。

testdb=> \set foo bar

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

testdb=> \echo :foo
bar

Note: \set の引数は他のコマンドと同様、同じ置換ルールに従います。このため、\set :foo 'something' のような興味深い参照を作成して、PerlPHP で、それぞれ"ソフトリンク" とか "可変変数" と呼ばれるものを取得することができます。残念ながら (好運にも?)、こういった構成をうまく使用する方法はありません。一方、\set bar :foo による変数のコピーは完全に有効な方法です。

2 番目の引数を指定せずに \set を実行した場合、単に変数が値を持たずに設定されます。変数を未設定にする (削除する) 方法は、\unset コマンドを使用することです。

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

DBNAME

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

ECHO

"all" に設定した場合、入力された、もしくは、スクリプトからの全ての行は、解析及び実行の前に標準出力に書き出されます。これをプログラム起動時に設定するには、-a スイッチを使用して下さい。"queries" に設定した場合、psql はバックエンドに送信された全ての問い合わせのみを表示します。このためのオプションは -e です。

ECHO_HIDDEN

この変数が設定された場合、バックスラッシュコマンドでデータベースに問い合わせを行なう時に、その問い合わせがまず表示されます。これにより、PostgreSQL 内部について学習することも、自作プログラム内で同様の関数機能を用意することもできます。この変数を noexec という値に設定した場合、問い合わせは実際にバックエンドに送信、実行されずに、単に表示されるだけになります。

ENCODING

現在のクライアント側のマルチバイトコーディング方式です。マルチバイト文字を使用するように設定していなければ、この変数は常に "SQL_ASCII" です。

HISTCONTROL

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

Note: この機能は bash の機能を恥も外聞もなく真似たものです。

HISTSIZE

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

Note: この機能は bash の機能を恥も外聞もなく真似たものです。

HOST

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

IGNOREEOF

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

Note: この機能は bash の機能を恥も外聞もなく真似たものです。

LASTOID

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

LO_TRANSACTION

PostgreSQL のラージオブジェクトインタフェースを使って、1 つのタプルに収まらないデータを特別に保存した場合、その操作全体は 1 つのトランザクションブロック内に含まれる必要があります。(より詳細についてはラージオブジェクトインタフェースについての文書を参照して下さい。) psql には、その内部コマンド \lo_export\lo_import\lo_unlink のいずれかが呼び出された時、進行中のトランザクション内に既に入っていることを確認する方法がありませんので、何らかの独断的な動作を取らなければなりません。この動作は、既に進行中であるトランザクションをロールバックするか、または、そのトランザクションをコミットするか、全く何もしないかのいずれかとなります。最後の動作を取る場合は、自分で BEGIN TRANSACTION/COMMIT ブロックを用意する必要があります。 さもないと、その結果は予期できないものになります (大抵は、どのような場合でも思い通りの動作が行なわれないという結果になります)。

希望する動作の選択は、この変数を "rollback""commit""nothing" のいずれかに設定することです。デフォルトはトランザクションをロールバックすることです。1 つか数個のオブジェクトの読み込みの場合はこれで問題ありません。しかし、多くのラージオブジェクトの転送を行なう場合、明示的に全てのコマンドを入れる 1 つのトランザクションブロックを用意することを勧めします。

ON_ERROR_STOP

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

PORT

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

PROMPT1
PROMPT2
PROMPT3

これらは psql が発行するプロンプトがどのように見えるかを指定します。後述の "プロンプト" を参照して下さい。

QUIET

この変数は -q コマンドラインオプションと同じです。対話式モードでは、あまり便利ではありません。

SINGLELINE

この変数は -S コマンドラインオプションと同じです。実行時に未設定としたりリセットしたりできます。

SINGLESTEP

この変数は -s コマンドラインオプションと同じです。

USER

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

SQL 差し替え

更に psql の変数機能には、変数を正規の SQL 文に代用 ("差し替え、interpolate") できるという有用な機能があります。このための構文は、繰り返しになりますが、変数名の前にコロン (:) を追加することです。

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

は、my_table テーブルに問い合わせることになります。変数の値は文字通りコピーされますので、片方だけの引用符やバックスラッシュコマンドでさえも含めることができます。変数に代入したものが意味を持つことを確実にしなければなりません。変数の差し替えは引用符で括られた SQL の項目には行なわれません。

この機能は、連続する文において、直前に挿入された OID を参照して、外部キーシナリオを構築することによく適用されます。他にも、ファイルの内容をフィールドにコピーする場合もこの機構を使用することができます。ファイルをまず変数に読み込み、上と同様に処理させます。

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

この方法において、my_file.txt に単一引用符が含まれるかも知れないという問題が起こり得ます。3 行目を処理する時の構文エラーを防ぐためには、この文字はエスケープする必要があります。以下のように sed プログラムを使って、エスケープさせることができます。

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

バックスラッシュの数 (6) が正しいことを確認して下さい。この方法で解決できます。psql は、この行を解析した後 sed -e "s/'/\\'/g" < my_file.txt をシェルに渡します。二重引用符内部に対してシェルがなすべきことを行ない、-es/'/\'/g を引数として sed を実行します。sed アプリケーションがこれを解析する時、2 つのバックスラッシュは 1 つのバックスラッシュに置き換えてから、正規表現による置換を行ないます。多分、ある時点では、全ての Unix コマンドが同一のエスケープ文字を使用することは素晴らしいと考えたでしょう。しかし、この考えは SQL のテキスト定数もある解釈に従うため、同様に全てのバックスラッシュをエスケープしなければならないということを無視しています。このような場合、ファイルの前処理を外部で行なった方が良いでしょう。

コロン (":") も問い合わせ自体に使用できますので、次のルールが適用されます。変数が未設定の場合、"コロン+名前" という文字の並びは変更されません。バックスラッシュでコロンをエスケープすることで、どのような場合でも解釈されないようにすることができます。(変数用のコロン構文は ecpg のような組み込み問い合わせ言語用の SQL 標準です。配列のスライス、及び、型キャスト用のコロン構文は PostgreSQLの拡張であり、競合しています。)

プロンプト

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

対応するプロンプト変数の値が文字として表示されます。 ただし、パーセント ("%") のある場合は例外です。その次の文字に従って、特定の他のテキストに置き換えられます。以下の置換が定義されています。

%M

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

%m

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

%>

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

%n

接続に使用するユーザ名 (ローカルシステムのユーザ名ではありません) です。

%/

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

%~

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

%#

現在のユーザがデータベースのスーパーユーザである場合、"#"、さもなくば、">" となります。

%R

PROMPT1 内の場合、通常は "="、シングル行モードでは "^"、(\connect が失敗した場合に起こり得る) データベースとの接続が切れたセッションでは "!" となります。 PROMPT2 内の場合、psql が問い合わせの入力が終っていない、/* ... */というコメントの内側にある、引用符の内側にある、の内のどの理由で更なる行の入力を要求しているかに依存した、"-""*"、単一引用符、二重引用符のいずれかにこの並びは置換されます。 PROMPT3 内の場合のこのシーケンスは何も生成しません。

%digits

digits0x から始まる場合、残った文字は 16 進数として解釈され、コードに対応する文字に置換されます。0 から始まる場合は、8 進数として解釈され、対応する文字に置換されます。 これら以外は 10 進数と見なされます。

%:name:

psqlname 変数の値です。 詳細については "変数" を参照して下さい。

%`command`

通常の "バッククオート" による置き換えに似た、command の出力です。

プロンプトにパーセント印を入れる場合は、%% と書きます。デフォルトのプロンプトは、プロンプト 1 と 2 に'%/%R%# '、プロンプト 3 に '>> ' を設定した場合と同じです。

Note: この機能は tcsh の機能を遠慮なく真似たものです。

コマンドライン編集

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

$if psql
set disable-completion on
$endif

(これは psql の機能ではなく、readline の機能です。詳細については readline の文書を参照して下さい。)

環境

HOME

初期化ファイル (.psqlrc) およびコマンド履歴ファイル (.psql_history) 用のディレクトリです。

PAGER

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

PGDATABASE

デフォルトで接続先となるデータベースです。

PGHOST
PGPORT
PGUSER

デフォルトの接続パラメータです。

PSQL_EDITOR
EDITOR
VISUAL

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

SHELL

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

TMPDIR

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

ファイル

注釈

Note: この節では、psql に特有の例のみをいくつか示します。SQL の学習や PostgreSQL に関する知識を得ることを目的にするのならば、配布物に含まれるチュートリアルを読んだ方が良いでしょう。

最初の例では、どのように複数行に渡る問い合わせを入力するのかを示します。プロンプトの変化に注意して下さい。

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

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

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