psql

Name

psql  --  Postgres 対話式端末型プログラム

Synopsis

psql [ options ] [ dbname [ user ] ]

要約

psqlPostgres の端末ベースのフロン トエンドです。 対話式に問い合わせを入力し、その問い合わせを Postgres に対して発行し、そし てその結果を確認することができます。 入力をファイルから読み込むこともできます。 更に、スクリプトの作成や多種のタスクの自動化を簡単にする ための、多くのメタコマンドと各種のシェルのような機能があ ります。

説明

データベースへの接続

psql は通常の Postgres のクライアントアプリケーショ ンです。 データベースに接続するためには、接続するデータベースの名前、サー バのホスト名とポート番号、及び、接続に使用するユーザ名を知らなけ ればなりません。 これらのパラメータは、それぞれ、-d-h-p-U というコマンドラインオプションを使用することで psql に通知することができます。 オプションに関連しない引数があれば、データベース名として解釈され ます。 (データベース名が指定されていた場合は、ユーザ名として解釈されま す。) これらのオプションは全て必須ではなく、デフォルト値が適用されます。 ホスト名を略した場合、psql は Unix ドメインソケットを使ってローカ ルホスト上のサーバに接続します。 データベースサーバ側も同じデフォルト値を使用していますので、ほと んどの場合はポート番号を指定する必要はありません。 ユーザ名のデフォルトは Unix のユーザ名です。データベース名のデ フォルトも同じです。 任意のユーザ名で任意のデータベースに接続できるわけではないことに 注意して下さい。 データベース管理者はユーザにそのユーザが持つアクセス権限を知らせ なければなりません。 入力を少なくするために、PGDATABASEPGHOSTPGPORTPGUSER 環境変数に適切な値を設定することもできます。

接続が何らかの理由(例えば、権限が無効であるとか、サーバ上で postmaster が動作していないなど) により確立できなかった場合、 psql はエラーを返し、終了します。

問い合わせの入力

通常の操作では、 psql は、psql が現在接続しているデータベース名に続いて "=>" の文字列のプロンプト を表示します。 例えばこのようなものです。

$ psql testdb
Welcome to psql, 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 問い合わせの入力が可能です。 通常、入力された行は一つの問い合わせの終結を意味するセミコロンが入力 された時点で、バックエンドに送られます。 行の終端が問い合わせの終結ではありません! このように問い合わせを複数行に渡って記述することができますので明 瞭になります。 問い合わせが送られ、エラーが何もなければ、問い合わせの結果が画面 上に表示されます。

問い合わせが実行された時は常に、 LISTENNOTIFY によって 生成された非同期通知イベントを psql は確認します。

psql メタコマンド

引用符なしでバックスラッシュから始まる全ての psql への入力は、 psql のメタコマンドです。 メタコマンドは psql 自身で処理されます。 これらのコマンドはデータベース管理やスクリプト作成における psql を興味深いものにしています。 メタコマンドはより一般的にはスラッシュコマンドやバックスラッシュ コマンドと呼ばれます。

psql コマンドは、バックスラッシュ、 すぐに続けて動詞コマンド、そして、何らかの引数という形式です。 動詞コマンドと引数の間、及び、各引数の間は任意数の空白文字で区 切られます。

引数の内部に空白文字を含める場合、単一引用符で引数を 括らなければなりません。 引数などに単一引用符を含める場合は、その前にバック スラッシュを付けます。 更に、単一引用符の間の文字は全て、 \n(改行)、\t(タブ)、 \digits\0digits、及び \0xdigits (指定された 10 進数、8 進数、または、16 進数コードが 示す文字)といった C のような置換ルールに従います。

引数が引用符なしでコロン(:)から始まる場合、 変数として扱われ、変数の値がその引数として扱われます。

"逆引用符" (`) で括られた引 数はシェルに渡すコマンドラインとして扱われます。 そのコマンドの (最後の改行が削除された) 出力が引数の値として扱 われます。 上述のエスケープシーケンスは逆引用符内でも適用されます。

コマンドの中には、(テーブル名といった)SQL の識別子を引数として取るものがあります。 これらの引数は、二重引用符に関する SQL 構文規則に従います。 つまり、二重引用符で括られていない識別子は小文字に強制変換 されます。 他の全てのコマンドでは、二重引用符は特別なものではなく、 引数の一部分となります。

引数の解析は、次に引用符なしのバックスラッシュが現れたところで 終了します。 これは新しいメタコマンドの始まりと解釈されます。 特別な \\ (2 つのバックスラッシュ)という並び は引数の終端を示し、もしあれば、SQL 問い合わ せの解析を続けて行ないます。 このように、SQLpsql コマンドは 1 行に混在させることが できます。 しかし、どのような場合でもメタコマンドの引数を複数行に渡って継続 させることはできません。

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

\a

現在、テーブル出力形式の位置揃えが無効であれば、位置揃えを 有効にします。 有効であれば、無効にします。 このコマンドは後方互換のために残っています。 一般的な手法については、\pset を参照し て下さい。

\C [ title ]

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

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

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

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

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

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

\copy table [ with oids ] { from | to } filename | stdin | stdout [ using delimiters 'characters' ] [ with null as 'string' ]

フロントエンド(クライアント)コピーを行ないます。 これは、SQL COPY コマンドの 操作となります。 ただし、バックエンドが直接指定ファイルの読み書きを行なう(これ には必然的に、そのファイルシステムがバックエンドからアクセスで きるようになっていることはもちろん、バックエンドへのアクセスと 特別なユーザ権限が要求されます)のではなく、 psql がそのファイルを読みバックエン ドにそのデータを中継する、あるいは、バックエンドから中継された データをファイルに書き込みます。

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

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

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

\copyright

Postgres の著作権及び配布条項を表示 します。

\d relation

relation (テーブ ル、ビュー、インデックス、または、シーケンスがこれに相当しま す。)の全列、その型、もしあれば、 NOT NULL やデフォルト値といった特別な属性を 表示します。 実際、指定リレーションがテーブルの場合、定義済みのインデック スも表示されます。 指定リレーションがビューの場合、ビュー定義も表示されます。

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

Note: \d が引数なしで呼び出された場合、 \dtvs と同じになり、全てのテーブル、ビュー、 シーケンスの一覧が表示されます。 これは全く便利な手段です。

\da [ pattern ]

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

\dd [ object ]

object (正規表現 でも指定できます。)の説明を表示します。 引数がない場合は全てのオブジェクトの説明を表示します。 ("Object" には、集約、関数、演算子、型、リレーショ ン(テーブル、ビュー、インデックス、シーケンス、ラージオブジェク ト)が含まれます。) 以下に例を示します。

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

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

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

\df [ pattern ]

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

\distvS [ pattern ]

これは実コマンドの名前ではなく、i、s、t、v、S という文字はそ れぞれ、インデックス、シーケンス、テーブル、ビュー、システム テーブルを意味します。 一覧表示の対象とする、これらのどれかを、または、これらの全て を任意の順番で指定することができます。 この表示には所有者の情報も含まれます。

pattern は、指定 された場合オブジェクトの名前がマッチするものを一覧表示するとい う制限を付与する正規表現です。

\dl

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

\do [ name ]

利用できる演算子と、その演算項目と戻り値を一覧表示します。 name が指定さ れた場合、その名前の演算子のみが表示されます。

\dp [ pattern ]

これは \z の別名ですが、より多くのニー モニック値を含みます。 ("パーミッション(permissions) の表示 (display) ")

\dT [ pattern ]

全てのデータ型、または、 pattern にマッ チする型のみを一覧表示します。 \dT+ という形のコマンドは、付加的な情報も 表示します。

\edit (or \e) [ filename ]

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

その後、新しい問い合わせバッファは、通常の psql のルールに従い、バッファ全体 を 1 行として再解析されます。 (このため、この方法では "scripts" を作成できま せん。この目的のためには \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 に保存 したり、その出力を別のシェルに渡し、 command を実行し たりすることもできます。 単なる \g はセミコロンと仮想的に同じです。 引数がある \g\o コ マンドの "一度限りの" 別方法です。

\help (or \h) [ command ]

指定した SQL コマンドの構文に関するヘル プを表示します。 command が指定 されていなかった場合は、psql は 構文ヘルプが存在する全てのコマンドの一覧を表示します。

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

\H

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

\i filename

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

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

\l (or \list)

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

\lo_export loid filename

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

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

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

\lo_import filename [ comment ]

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

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

現在データベースに保存されている全ての Postgres"ラージオブジェクト" の一覧をその所有者情報と一緒 に表示します。

\lo_unlink loid

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

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

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

\o [ {filename | |command} ]

以降の問い合わせの結果を filename ファ イルに保存、もしくは、以降の問い合わせの結果を別シェルに渡 し、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' と入力します。 デフォルトのフィールド区切り文字は'|' ("パイプ" シンボル) です。

recordsep

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

tuples_only (or t)

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

title [ text ]

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

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

tableattr (or T) [ text ]

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

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 history ライブラリを使用するよ うにコンパイル時に設定されていた場合にのみ使用可能です。

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

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

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

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

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

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

\t

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

\T table_options

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

\w {filename | |command}

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

\x

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

\z [ pattern ]

データベース内の全てのテーブルを適切なアクセス権限 の一覧をつけて表示します。 引数が指定された場合、正規表現として扱われ、それに マッチするテーブルのみの一覧が表示されます。

test=> \z
Access permissions for database "test"
 Relation |           Access permissions
----------+-------------------------------------
 my_table | {"=r","joe=arwR", "group staff=ar"}
(1 row )
これから以下が分かります。

  • "=r": PUBLIC は このテーブルに対して読み取り (SELECT) 権限を持ちます。

  • "joe=arwR": joe ユーザはこのテーブルに対して、読み取り、書き込み (UPDATEDELETE) "追加" (INSERT) 権限、 及び、ルール作成権限を持ちます。

  • "group staff=ar": staff グループはSELECT、及び、 INSERT 権限を持ちます。

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

\! [ command ]

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

\?

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

コマンドラインオプション

コンパイル時に設定されていれば、psql は、標準 Unix 短縮形式オプションとGNU形式の 長めのオプションの両方を受け付けることができます。 後者は全てのシステムで利用できません。

-a, --echo-all

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

-A, --no-align

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

-c, --command query

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

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

-d, --dbname dbname

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

-e, --echo-queries

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

-E, --echo-hidden

\d や他のバックスラッシュコマンドによって生成される実 際の問い合わせを表示します。 これを使って、自作のプログラムで似たような関数機能を含 めることができます。 これは psql 内部から ECHO_HIDDEN 変数を設定することと同じです。

-f, --file filename

対話式に問い合わせを読みとるのではなく、 filename ファイルを問い合わせのソースとして使用します。 このファイルの処理が終了した後、psql は終了します。 これは \i 内部コマンドとほとんど同じです。

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

-F, --field-separator separator

separator を フィールド区切り文字として使用します。 これは \pset fieldsep もしくは \f と同じです。

-h, --host hostname

postmaster を実行しているマシ ンのホスト名を指定します。 このオプションが無い場合、通信はローカルな Unix ドメイン ソケットを使用して行なわれます。

-H, --html

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

-l, --list

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

-o, --output filename

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

-p, --port port

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

-P, --pset assignment

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

-q

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

-R, --record-separator separator

separator を レコード区切り文字として使用します。 これは \pset recordsep コマンドと同じ です。

-s, --single-step

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

-S, --single-line

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

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

-t, --tuples-only

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

-T, --table-attr table_options

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

-u

データベース接続の前に psql が ユーザ名とパスワードを尋ねるようにします。

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

-U, --username username

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

-v, --variable, --set assignment

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

-V, --version

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

-W, --password

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

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

-x, --expanded

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

-X, --no-psqlrc

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

-?, --help

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

先進的機能

変数

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

この変数が設定された場合、バックスラッシュコマンドがデー タベースに問い合わせを行なう時に、その問い合わせがまず表 示されます。 これにより、Postgres 内部につ いて学習することができ、自作プログラム内に似たような機能 を取り込むことができます。 この変数を "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

Postgres のラージオブジェクトイン タフェースを使って、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 文に代用 ("差し替え") できるという有用な機能があります。 このための構文は、繰り返しになりますが、変数名の前にコロン (:) を付与することです。

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 のテキスト定数 もある解釈に従うため、同様に全てのバックスラッシュをエス ケープしなければならないということを忘れてはいけません。 このような場合、ファイルの前処理を外部で行なった方が良い でしょう。

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

プロンプト

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

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

%M

データベースサーバの (ドメイン名の付与された) 完全なホスト 名 (ホスト名情報を取得できなかった場合は "localhost")。

%m

最初のドット以降を取り除いた、データベースサーバのホスト名。

%>

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

%n

接続中のユーザ名。(システム上のローカルなユーザ名ではありません。)

%/

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

%~

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

%#

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

%R

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

%digits

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

%:name:

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

%`command`

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

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

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

その他雑多なもの

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

psql は処理を始める前に、 $HOME/.psqlrc ファイル内のコマンドを読 み込み、実行しようと試みます。 (このファイルにて \setSET コマンドを使用して) 好みに応じたクラ イアントやサーバの設定を行なうことに使用されます。

GNU readline

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

$if psql
set disable-completion on
$endif
(これは psql の機能ではなく、 readline の機能です。より詳細に ついては readline の文書を参照 して下さい。)

readline ライブラリがインストールされているにも関わらず、 psql がそれを使用していないよ うに見える場合は、Postgres の 最上位の configure スクリプトによっ て、そのライブラリが確実に検出されるようにする必要があり ます。 configure によって libreadline.a ライブラリ (もしくは そのシェアドライブラリ) 及び readline.hhistory.h (もしくは readline/readline.hreadline/history.h) ヘッダファイルの 両方が適切なディレクトリ内で検出されなければなりません。 これらのライブラリとヘッダファイルを検出されない所にインス トールした場合は、configure にそれら の場所を通知する必要があります。例えば、以下のようにします。

$ ./configure --with-includes=/opt/gnu/include --with-libs=/opt/gnu/lib  ...
その後で psql を再コンパイルす る必要があります。(コードツリー全体を再コンパイルする必要 はありません。)

GNU readline ライブラリは ftp://ftp.gnu.org に ある GNU プロジェクトの FTP サーバから入手することができます。

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

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

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)
text の列は左に揃えられていますが、右側の int 4 の列 がどのように位置揃えされているのかに注目して下さい。 \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

付録

バグと問題点