psqlはPostgreSQLの正式なクライアントアプリケーションです。データベースに接続するためには接続したいデータベース名、ホスト名、サーバのポート番号、接続する際に使用するユーザ名が分かっている必要があります。psqlでは、それらはコマンドラインオプションの引数で指定することができ、それぞれ -d、-h、-p、-Uです。オプションに属さない引数がある場合、それはデータベース名(データベース名がある場合にはユーザ名)と見なされます。これらのオプションすべてが必ず指定されている必要はなく、指定されていない時はデフォルト値が使用されます。ホスト名を省略した場合は、UNIXドメインソケット経由でローカルホストにあるサーバに接続します。デフォルトのポート番号はコンパイル時に設定されます。データベースは同じデフォルト値を使用するので、多くの場合、ポートは指定する必要はありません。デフォルトのユーザ名とデータベース名は、UNIXのユーザ名です。あらゆるユーザ名であらゆるデータベースに接続できるわけではありません。データベース管理者は、接続権限をユーザに知らせておかなければなりません。入力する手間を省くために、環境変数PGDATABASE、 PGHOST、PGPORT、PGUSERに適当な値を設定することもできます。
何かの原因(権限がない、サーバで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=>
プロンプトに対しユーザは問い合わせを入力することができます。通常、入力された行は問い合わせ終了を意味するセミコロンに達した時にバックエンドへと送信されます。つまり、改行は問い合わせの終了を意味しません。したがって、問い合わせはわかりやすくするために、複数の行に渡って記述することができます。問い合わせが問題なく送られたら、画面に問い合わせの結果が表示されます。
また、問い合わせが実行される度に、psqlは LISTENと NOTIFY によって生成された非同期通知イベントをチェックします。
psql内で、入力されたもので、引用符で囲まれていなくて、バックスラッシュで始まるものはpsql自身によって実行される、 psqlのメタコマンドです。これらのコマンドは管理する側、または開発する側にとって、psqlをとても興味深いものとします。メタコマンドは一般的にスラッシュコマンド、またはバックスラッシュコマンドと呼ばれます。
psqlコマンドの形式はバックスラッシュ、その直後にコマンドの動詞、その次に引数がきます。引数と動詞コマンド、またそれぞれの動詞コマンドは空白文字によって区別します。
引数に空白を含める場合、これらは単一引用符で囲う必要があります。単一引用符を引数に含める場合には、2重にして下さい。単一引用符で囲われたものは、\n(改行)、 \t(タブ)、\digits、 \0digits、 \0xdigits (与えられた10進数、8進数、16進数の文字)のC言語の代わりになることがあります。
引用符で囲われていなくて、かつコロン(:)で開始される引数は、変数として扱われ、変数の値が引数として扱われます。
"バックティック"(`)で囲われた引数はコマンドラインとして認識され、シェルに引き渡されます。コマンドの結果(後続の改行は削除されます)は引数の値として見なされます。バックティックに対しても上記のエスケープが該当します。
いくつかのコマンドは、引数にSQLの(テーブル名などの)識別子を取るものがあります。これらの引数はSQLの二重引用符などの構文規則に従います。二重引用符がない識別子は小文字に強制変換されます。その他のすべてのコマンドでは二重引用符は特別な意味を持っておらず、引数の一部分となります。
引数の解析は別の引用符で括られていないバックスラッシュがあるところで終了します。これは、新たなメタコマンドの始まりと認識されます。\\(バックスラッシュ2つ)という特別な文字の並びは引数の終りを意味し、SQL問い合わせ続きがある場合は、その解析を行います。そのような方法で、SQLと psqlコマンドは1つの行に合わせて記述することができます。しかし、あらゆる場合において、メタコマンドの引数は行を跨ることはできません。
以下のメタコマンドが定義されています。
現在のテーブルの出力形式が「揃えない」になっていれば、「揃える」に切り替えます。「揃えない」でない場合は、「揃えない」に設定します。このコマンドは下位互換性のためにあります。一般的な解決法は\psetをご覧下さい。
現在の作業ディレクトリを directory に変更します。引数がない場合は、現在のユーザのホームディレクトリに変更します。
Tip: 現在の作業ディレクトリを表示するには、\!pwd を使用して下さい。
問い合わせ結果として表示される全てのテーブルタイトルの設定、または、タイトルの設定の解除を行ないます。このコマンドは、 \pset title title と同じです。(このコマンドの名前は"caption"に由来し、それは HTMLのテーブルの標題(caption)を設定するためだけに使われていました。)
新しいデータベースに指定したユーザ名で接続、または、指定ユーザ名で接続を行ないます。それまでの接続は閉ざされます。 dbname が - の場合、現在のデータベース名が使われます。
username が省略された場合、現在のユーザ名が使用されます。
特別な規則として、引数がない\connectの場合は、デフォルトのデータベースにデフォルトのユーザで接続します。(何も引数なしで psql を起動した場合と同じことになります。)
接続の試行が(ユーザ名の間違いやアクセスが拒否された場合などの理由で)失敗した場合、 psqlが対話式モードである時に限って、それまでの接続が保持されます。非対話式スクリプトを実行している場合は、処理はエラーとなり、即座に停止します。この違いは、片方は入力ミスに対するユーザの簡便性を、もう片方は、スクリプトが間違ったデータベースを操作してしまう事故を防ぐ安全な機構を考慮して実装されています。
フロントエンド(クライアント)コピーを行ないます。これは、 SQL COPY コマンドを実行する操作です。しかし、バックエンドが直接指定ファイルの読み書きを行なう(これを行うには必然的に、そのファイルシステムがバックエンドからアクセスできるようになっていることはもちろん、バックエンドへのアクセスと特別なユーザ権限が要求されます)のではなく、 psql がそのファイルを読みバックエンドにそのデータを中継する、あるいは、バックエンドから中継されたデータをファイルに書き込みます。
このコマンドの構文はSQL COPYコマンドに似ています(詳細はその説明を参照して下さい)。このため、\copy コマンドには特別な解析ルールが適用されていることに注意して下さい。特に、変数の置換ルールやバックスラッシュエスケープは適用されません。
Tip: この操作は SQL COPY コマンド程効率よくありません。というのは、全てのデータがクライアント/サーバIP接続かソケット接続を通じてやりとりされなくてはならないからです。データ量が多いときは他の手法を使用する方がよいでしょう。
Note: フロントエンドコピーとバックエンドコピーとでは、stdin及び stdoutの解釈に違いがあることに注意して下さい。フロントエンドコピーでは、これらは常にpsql の入出力ストリームを参照します。バックエンドコピーでは、stdin は COPY自体が読みとるところから読みとります。(例えば、-f オプションで実行するスクリプト。)そして、stdout は問い合わせ出力ストリーム (後述の\oメタコマンドを参照して下さい)を参照します。
PostgreSQL の著作権及び配布条項を表示します。
relation(テーブル、ビュー、インデックス、または、シーケンスがこれに相当します。)の全カラム、その型、もしあれば、NOT NULL やデフォルト値といった特別な属性を表示します。実際、指定リレーションがテーブルの場合、定義済みのインデックス、プライマリキー、一意性制約、チェック制約も表示されます。指定リレーションがビューの場合、ビュー定義も表示されます。
\d+ という形のコマンドも同じですが、テーブルのカラムに関連した全てのコメントも表示されます。
Note: \dが引数なしで呼び出された場合、\dtvsと同じ意味となり、全てのテーブル、ビュー、シーケンスの一覧が表示されます。これは単に便宜性のためのものです。
利用できる全ての集約関数と、その操作対象となるデータ型の一覧を表示します。 pattern(正規表現) が指定された場合、一致する集約のみが表示されます。
object (正規表現でも指定可)の説明を表示します。引数がない場合は全てのオブジェクトの説明を表示します。("Object" には、集約、関数、演算子、型、リレーション(テーブル、ビュー、インデックス、シーケンス、ラージオブジェクト)が含まれます。)下記に例を示します。
=> \dd version
Object descriptions
Name | What | Description
---------+----------+---------------------------
version | function | PostgreSQL version string
(1 row)
オブジェクトの説明は COMMENT ON SQL コマンドを使用して生成することができます。
Note: PostgreSQL はオブジェクトの説明をpg_description システムテーブルに保存します。
利用できる全ての関数と、その引数と戻り値の一覧を表示します。 pattern (正規表現)が指定された場合、一致する関数のみが表示されます。\df+ という形で使われた場合、各関数の言語や説明を含む付加的情報も表示されます。
これは実コマンドの名前ではなく、i、s、t、v、S という文字はそれぞれ、インデックス、シーケンス、テーブル、ビュー、システムテーブルを意味します。一覧表示の対象とする、これらのどれかを、または、これらの全てを任意の順番で指定することができます。この表示には所有者の情報も含まれます。
pattern は、指定された場合オブジェクトの名前が一致するものを一覧表示するという制限を付与する正規表現です。
これは \lo_list の別名で、ラージオブジェクトの一覧を表示します。
利用できる演算子と、その演算項目と戻り値を一覧表示します。 name が指定された場合、その名前の演算子のみが表示されます。
これは \z の別名ですが、より多くのニーモニック値を含みます。("permission display (パーミッションの表示)")
全てのデータ型、または、pattern に一致する型のみを一覧表示します。
設定済みの全ユーザ、もしくは、 pattern に一致するユーザのみを一覧表示します。
filename が指定された場合、このファイルが編集されます。エディタの終了後、その内容は問い合わせバッファにコピーされます。引数なしの場合、現在の問い合わせバッファは一時ファイルにコピーされ、そして同様に編集されます。
その後、新しい問い合わせバッファは、通常のpsqlのルールに従い、バッファ全体を1行として再解析されます。(このため、この方法では"scripts"を作成できません。この目的のためには \i を使用して下さい。)これはまた、問い合わせの終端がセミコロンである(もしくは問い合わせがセミコロンを含む)場合、すぐに実行されることを意味しています。この他の場合は、単に問い合わせバッファ内に保持されるだけです。
Tip: psql は環境変数 PSQL_EDITOR、 EDITOR、VISUALを(この順番に)検索し、使用するエディタを決定します。これら全てが未設定である場合は、/bin/viが実行されます。
引数をスペースで区切り、標準出力に出力し、改行します。スクリプトの出力に、情報を点在させる場合に有用です。例を下記に示します。
=> \echo `date` Tue Oct 26 21:40:57 CEST 1999
最初の引数が引用符で括られていない -n である場合、最後の改行は出力されません。
Tip: \o コマンドを使用して問い合わせの出力先を変更していた場合、このコマンドではなく、\qechoを使用した方が良いでしょう。
マルチバイトエンコーディングを使用している場合、クライアント側のコーディングを設定します。引数なしの場合、このコマンドは現在のエンコーディング方式を表示します。
位置揃えされていない問い合わせの出力用のフィールドの区切り文字を設定します。デフォルトは、"|"("パイプ"記号)です。一般的な出力オプションの設定方法については、\psetを参照して下さい。
現在の問い合わせ入力バッファをバックエンドに送ります。また、オプションとしてその出力を filenameに保存したり、その出力を別のシェルに渡し、 commandを実行したりすることもできます。単なる\gはセミコロンと仮想的に同じです。引数がある\gは \oコマンドの"一度限りの"別方法です。
指定した SQL コマンドの構文に関するヘルプを表示します。 command が指定されていなかった場合は、 psql は構文ヘルプが存在する全てのコマンドの一覧を表示します。
Note: 入力を簡単にできるよう、複数単語からなるコマンドを引用符で括る必要はありません。従って、\help alter tableと入力するだけで十分です。
HTML問い合わせ出力形式を有効にします。既にHTML形式が有効であった場合、デフォルトの位置揃えされたテキスト形式に戻します。このコマンドは互換性と簡便性のために存在します。他の出力オプションについては、 \pset を参照して下さい。
filename ファイルから入力を読みとり、キーボードから入力された場合と同じように実行します。
Note: 読みとられた行を画面上に表示させたい場合は、ECHO変数を allに設定する必要があります。
サーバ上のデータベースとその所有者の一覧を表示します。このコマンドに"+"を付与することで、そのデータベースに関する全ての説明を表示することができます。 PostgreSQL のインストール時にマルチバイトコーディングをサポートするようにコンパイルしていた場合、各データベースのコーディングの名称も表示されます。
データベースからloidという OIDを持つラージオブジェクトを読み取り、 filenameに書き出します。 lo_exportサーバ関数とは微妙に異なります。こちらの関数はデータベースサーバを実行しているユーザ権限で、サーバ上のファイルシステムに対して動作します。
Tip: ラージオブジェクトのOIDを探すためには、 \lo_listを使用して下さい。
Note: ラージオブジェクトに対する全ての操作に関わる重要な情報について、 LO_TRANSACTION変数の説明を参照して下さい。
ファイルを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 変数の説明を参照して下さい。
現在データベースに保存されている全てのPostgreSQL の "ラージオブジェクト"の一覧を、そのオブジェクトに付けられたコメントと一緒に表示します。
loidというOIDが示すラージオブジェクトをデータベースから削除します。
Tip: ラージオブジェクトのOIDを探すためには、 \lo_list を使用して下さい。
Note: ラージオブジェクトに対する全ての操作に関わる重要な情報について、 LO_TRANSACTION変数の説明を参照して下さい。
以降の問い合わせの結果をfilename ファイルに保存、もしくは、以降の問い合わせの結果を別シェルに渡し、 command を実行します。引数がない場合、問い合わせの出力はstdoutにリセットされます。
"問い合わせの結果" には全てのテーブル、コマンドの応答、データベースサーバからの注意はもちろん、データベースに問い合わせを行なう(\d のような)各種バックスラッシュコマンドの出力が含まれますが、エラーメッセージは含まれません。
Tip: 問い合わせの結果の間にテキストを点在させるためには、\qechoを使用して下さい。
現在の問い合わせバッファを標準出力に書き出します。
このコマンドは問い合わせ結果のテーブル出力に影響するオプションを設定します。 parameterには、どのオプションを設定するのかを記述します。valueの意味はこの parameterに依存します。
下記は、表示の調整に関するオプションです。
出力形式をunaligned、aligned、html、または、latex に設定します。一意となる省略も可能です。(1文字でも十分であることを意味します。)
"Unaligned" は、1行に1つのタプルの全フィールドを、現在有効なフィールド区切り文字で区切って書き出します。これは、他のプログラムによって読み込む予定の(タブ区切りやカンマ区切りといった)出力を作成することを意図しています。デフォルトの"Aligned"モードは、標準的で、人による可読性の高い、きれいに整形されたテキスト出力です。 "HTML"と"LaTeX"モードは、対応するマークアップ言語の文書に含めることができるようにテーブルを出力します。この出力は完全な文書ではありません。(これはHTMLの場合は大したことではありませんが、LaTeXの場合は必ず完全な文書になるようにラッパーを作成しなければなりません)
2 番目の引数は数字です。通常はこの数字が多くなればなるほど、表示するテーブルが持つ境界線は太くなりますが、これは特定の形式に依存しています。HTMLモードでは、この値は直接border=... 属性に反映されます。他の形式の場合は、0(境界線なし)、1(内側の境界線)、2(テーブル枠)という数のみが有効です。
通常形式と拡張形式を切替えます。拡張形式が有効な場合、全ての出力は左にフィールド名、右にデータという2つのカラムを持ちます。このモードはデータが通常の "horizontal" モードによる画面表示に適していない場合に有用です。
拡張モードは4つの全てのモードでサポートされています。
2番目の引数は、フィールドが null の場合に表示する文字列です。デフォルトでは何も表示しません。そのため、よく空の文字列と間違うことがあります。このような場合、\pset null '(null)'と書いた方が良いでしょう。
位置揃えなしの出力モードで使用されるフィールド区切り文字を指定します。これにより、例えばタブ区切り、カンマ区切りといった他プログラムが良く使用する形式を作成することができます。タブをフィールド区切り文字として使用するには、 \pset fieldsep '\t'と入力します。デフォルトのフィールド区切り文字は'|'("パイプ"記号)です。
デフォルトのフッタ(x rows) の表示、非表示を切替えます。
位置揃えなしの出力モードで使用されるレコード(行)の区切り文字を指定します。デフォルトは改行文字です。
タプルのみ表示と完全表示を切替えます。完全表示ではカラムのヘッダやタイトル、各種フッタといった余計かもしれない情報も表示します。タプルのみのモードでは、テーブルの実データのみが表示されます。
今後表示される全てのテーブル用のテーブルタイトルを設定します。これは出力に説明的なタグを付けることに使用することができます。引数がない場合、タイトルは設定されません。
Note: 以前まではHTMLモードでしか影響しませんでした。現在では全ての出力形式においてタイトルを設定することができます。
HTMLのtableタグ内に記述する任意の属性を指定できます。これを使用して、例えば、cellpaddingや bgcolorを指定することができます。border属性は既に\pset borderによって処理されていますので、このコマンドで border を指定しない方が良いでしょう。
テーブル出力の際のページャの使用を切替えます。PAGER環境変数が設定されている場合、出力は指定したプログラムに渡されます。設定されていなければ、more が使用されます。
いかなる場合でも、そのページャが適切と見なせば、psqlはそのページャのみを使用します。これは、他にもありますが、出力が端末であること、及び、テーブルが通常画面表示に適していないことを示しています。表示ルーチンのモジュールの性質により、実際に表示する行数を常に予測することはできません。このため、psql はページャを使用している場合と使用していない場合を明確に区別することができません。
例 節に、これらの形式の違いがどのように見えるかについての図があります。
Tip: \psetには各種のショートカットコマンドがあります。 \a、\C、\H、 \t、\T、及び、 \xを参照して下さい。
Note: 引数なしで\psetを呼び出した場合はエラーになります。将来、この呼出によって、現在の全ての表示用オプションの状態を表示するようになる予定です。
psql プログラムを終了します。
このコマンドは、\echoと同じです。ただし、 \o による設定と同様に、全ての出力が問い合わせ出力チャネルに書き出される点が異なります。
問い合わせバッファをリセット(クリア)します。
コマンドラインの履歴の表示、または、filename への保存を行ないます。filename が省略された場合、履歴は標準出力に書き出されます。このオプションは、 psqlがGNU historyライブラリを使用するようにコンパイル時に設定されていた場合にのみ使用可能です。
Note: 現在のバージョンでは、プログラムの終了時に自動的に保存されるようになりましたので、コマンドの履歴を保存する必要が無くなりました。この履歴は psql の起動の度に自動的に読み込まれます。
valueを、もしくは、1つ以上のvalueが与えられた場合は、それらをまとめたものをname 内部変数に設定します。2番目の引数が無い場合は、変数は単に値が無いものとして設定されます。変数を未設定とするには、\unset コマンドを使用して下さい。
変数名には、文字、数字、アンダースコアを使用することができます。詳細については、psql の変数に関する節を参照して下さい。
必要ならばどのようなものでも任意の変数に設定できますが、 psql はいくつかの変数を特別なものとして扱っています。これらについては変数に関する節にて説明されています。
Note: このコマンドは SET SQL コマンドとは全く別のものです。
出力列名ヘッダと行数フッタの表示を切替えます。このコマンドは\pset tuples_only と同じで、簡便性のために用意されたものです。
HTML表形式出力モードにおけるtable タグ内部に記述するオプションを指定できます。このコマンドは \pset tableattr table_options と同じです。
現在の問い合わせバッファをfilename ファイルに出力、もしくは、command Unix コマンドに渡します。
拡張行形式モードを切替えます。このコマンド自体は \pset expandedと同じものです。
データベース内の全てのテーブルを適切なアクセス権限の一覧を付けて表示します。引数が指定された場合、正規表現として扱われ、それに一致するテーブルのみの一覧が表示されます。
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 ユーザはこのテーブルに対して、読み取り、書き込み (UPDATE、DELETE)"追加" (INSERT) 権限、及び、ルール作成権限を持ちます。
"group staff=ar": staffグループは SELECT、及び、INSERT 権限を持ちます。
別のシェルの起動、もしくは、command Unix コマンドを実行します。引数はこれ以上解釈されず、そのままシェルに渡されます。
スラッシュ ("\") コマンドに関するヘルプ情報を表示します。
コンパイル時に設定されていれば、psqlは、標準Unix 短縮形式オプションとGNU形式の長めのオプションの両方を受け付けることができます。後者は全てのシステムで利用できません。
読み込んだ全ての行を画面に表示します。これは対話式モードよりもスクリプト処理の際に有用です。これは ECHO 変数を all に設定することと同じです。
位置揃え無しの出力モードに切替えます。(さもなければ、デフォルトの位置揃えされた出力モードになります。)
psqlに対し、queryという1つの問い合わせ文字列を実行し、終了するよう指示します。このコマンドはシェルスクリプト内で有用です。
queryは、バックエンドで完全に解析可能な問い合わせ文字列(つまり、psqlは含みません)、もしくは、1つのバックスラッシュコマンドである必要があります。このためSQLとpsqlメタコマンドを混在させることはできません。以下の様にパイプを使ってその文字列を psql に渡すことで混在させることができます。 echo "\x \\ select * from foo;" | psql.
接続するデータベースの名前を指定します。これはコマンドラインでオプション形式でない最初の引数としてdbname を指定することと同じです。
バックエンドに送られた問い合わせを全て表示します。これはECHO変数を queriesに設定することと同じです。
\dや他のバックスラッシュコマンドによって生成される実際の問い合わせを表示します。これを使って、自作のプログラムで似たような関数機能を含めることができます。これは psql内部からECHO_HIDDEN変数を設定することと同じです。
対話式に問い合わせを読みとるのではなく、filename ファイルを問い合わせのソースとして使用します。このファイルの処理が終了した後、 psqlは終了します。これは\i内部コマンドとほとんど同じです。
filename が -(ハイフン)の場合標準入力から読み込まれます。
このオプションの使用と、psql < filename と入力することは微妙に異なります。一般的には、両者とも想像通りの動作を行ないますが、 -f を使用した場合は、行番号付きのエラーメッセージなどといった、いくつかの優れた機能が有効になります。また、このオプションを使用した場合、起動時のオーバーヘッドが減少する可能性が少しあります。一方、シェルの入力リダイレクションを使用する方法では、(理論的には) 全て手作業で入力した場合の出力と全く同一な出力になることが保証されます。
separatorをフィールド区切り文字として使用します。これは\pset fieldsepもしくは\fと同じです。
postmasterを実行しているマシンのホスト名を指定します。このオプションが無い場合、通信はローカルなUnixドメインソケットを使用して行なわれます。
HTML表形式を有効にします。これは\pset format html もしくは\Hコマンドと同じです。
利用可能な全てのデータベースを一覧表示します。この他の接続関連でないオプションは無視されます。これは\list内部コマンドと似ています。
全ての問い合わせの出力をfilename ファイルに書き込みます。これは\oコマンドと同じです。
postmaster が接続監視を行なっている、TCP/IP ポート、もしくは、(ホスト名が)省略された場合は、ローカルなUnixドメインソケットファイルの拡張子を指定します。PGPORT 環境変数の値、もし環境変数が設定されていなければ、コンパイル時に指定した値、通常は5432がデフォルト値となります。
\pset形式による表示オプションをコマンドラインから指定することができます。ここではスペースではなく等号を使って名前と値を区切っていることに注意して下さい。つまり、出力形式をLaTeXにする場合、 -P format=latexと入力します。
psqlがメッセージ出力を行なわずに処理を行なうように指示します。デフォルトでは、welcomeメッセージ、各種の出力情報を表示します。このオプションを使用した場合、このメッセージ表示がされません。 -cオプションとの併用は有用です。psql内で、 QUIET 変数を設定することでも同じことができます。
separatorをレコード区切り文字として使用します。これは\pset recordsepコマンドと同じです。
シングルステップモードで実行します。これは各問い合わせがバックエンドに送信される前に、ユーザに対して実行するかキャンセルするかについて確認を求めることを意味します。スクリプトのデバッグのためにこれを使用して下さい。
セミコロンと同様に改行が問い合わせの終端となる、シングル行モードで実行します。
Note: このモードはこの使用方法に固執しているユーザ向けに用意されたものですので、無理して使用する必要はありません。特に、1行にSQLとメタコマンドを混在させる場合、経験の浅いユーザにとってその実行順番は必ずしも分かりやすいものではありません。
カラム名と結果の行数フッタなどの表示を無効にします。これは、 \tメタコマンドと全く同じです。
HTML table タグ内に記述されるオプションを指定できます。詳細については\psetを参照して下さい。
データベース接続の前にpsql がユーザ名とパスワードを尋ねるプロンプトを表示させます。
概念的な欠陥のため、このオプションは推奨されません。(デフォルトではないユーザ名の入力とバックエンドからの要求によるパスワード入力とは全く異なるものです。)代替である、-Uと-W オプションを参照することを勧めます。
デフォルトのユーザではなくusername ユーザとしてデータベースに接続します。(当然ですが、このための権限を持っていなければなりません。)
\set 内部コマンドのように、変数の代入を行ないます。値がもしあれば、コマンドラインで名前と値を等号で区切る必要があることに注意して下さい。変数を未設定にするためには、等号を取って下さい。これらの代入は起動時の非常に早い段階で行なわれます。そのため、後で内部目的用に予約された変数によって上書きされる可能性があります。
psql のバージョンを表示します。
データベース接続前にパスワード入力を促すようにpsqlに対して要求します。\connectメタコマンドを使用して接続するデータベースを変更した場合であっても、セッション全体用の設定として保持します。
現在のバージョンでは、psqlはバックエンドがパスワード認証を要求した時は常に自動的にパスワードプロンプトを表示します。現在これは"ハック"されたものに基づいていますので、自動認識が予想できない失敗をする可能性があります。そのため、このオプションを使って強制的にプロンプトを表示させます。バックエンドがパスワード認証を要求した時にパスワードプロンプトが表示されない場合、その接続の試行は失敗します。
拡張行形式モードを有効にします。これは\xコマンドと同じです。
~/.psqlrc起動用ファイルを読み込みません。
psqlのコマンドライン引数に関するヘルプを表示します。
psqlは、一般的なUnixコマンドシェルに似た変数の置換機能を提供します。この機能は新しいためまだあまり洗練されていませんが、今後拡張していく予定です。変数は単なる名前と値の組合せです。値として任意の長さの任意の文字を使うことができます。変数の設定にはpsqlの \setメタコマンドを以下のように使用します。
testdb=> \set foo bar
これは、"foo"変数を"bar"という値に設定します。変数の内容を取り出すには、以下のようにその名前の前にコロンを付けて、任意のスラッシュコマンドの引数として使用します。
testdb=> \echo :foo bar
Note: \setの引数は他のコマンドと同様、同じ置換ルールに従います。このため、\set :foo 'something'のような興味深い参照を作成して、Perlや PHP で、それぞれ"ソフトリンク"とか "可変変数"と呼ばれるものを取得することができます。残念ながら(好運にも?)、こういった構成をうまく使用する方法はありません。一方、\set bar :fooによる変数のコピーは完全に有効な方法です。
2番目の引数を指定せずに\setを実行した場合、単に変数が値を持たずに設定されます。変数を未設定にする(削除する)方法は、\unset コマンドを使用することです。
psql の内部変数名は文字、数字、アンダースコアから構成され、順番や長さには制限がありません。多くの正規な変数はpsqlで特別に扱われます。これらは、実行時に変数の値を変更することで設定変更できる特定のオプションやアプリケーションのある状態表現を示します。これらの変数を別の目的のために使用することもできますが、プログラムの動作がとてもおかしくなったり、とても速くなったりする可能性がありますので、推奨されません。慣習に従って、特別にとり扱われる変数は全て大文字 (と数字とアンダースコア)からなります。将来の互換性が最も高くなるように、このような変数を使用しないで下さい。下記は特別にとり扱われる変数の全一覧を示します。
現在接続しているデータベース名です。この変数は(プログラム起動時も含め)データベースに接続する度に設定されます。未設定とすることもできます。
"all" に設定した場合、入力された、もしくは、スクリプトからの全ての行は、解析及び実行の前に標準出力に書き出されます。これをプログラム起動時に設定するには、-aスイッチを使用して下さい。"queries" に設定した場合、 psql は全てのバックエンドに送信された問い合わせのみを表示します。このためのオプションは -e です。
この変数が設定された場合、バックスラッシュコマンドがデータベースに問い合わせを行なう時に、その問い合わせがまず表示されます。これにより、 PostgreSQL 内部について学習することも、自作プログラム内で同様の関数機能を用意することができます。この変数を "noexec"という値に設定した場合、問い合わせは実際にバックエンドに送信、実行されずに、単に表示されるだけになります。
現在のクライアント側のマルチバイトコーディング方式。マルチバイト文字を使用するように設定していなければ、この変数は常に"SQL_ASCII"です。
この変数をignorespaceに設定した場合、スペースから始まる行は履歴リストには入りません。ignoredupsに設定した場合、これまでの履歴にある行は履歴リストに入りません。 ignorebothという値はこの2つのオプションの組合せです未設定、または、上記以外の値に設定されていた場合、対話的に入力された全ての行は履歴リストに保存されます。
Note: この機能はbashの機能を恥知らずですが、真似たものです。
コマンド履歴に保存するコマンド数。デフォルト値は500です。
Note: この機能はbashの機能を恥も外聞もなく真似たものです。
接続中のデータベースサーバホストです。この変数は(プログラム起動時も含め、)データベースに接続する度に設定され、未設定にすることもできます。
未設定ならば、psqlは、その対話式セッションへEOF文字(通常 Control-D) が送信された時、終了します。数値に設定した場合、アプリケーションの終了の前に、指定数だけ送信されたEOF文字を無視します。数値以外に設定した場合は、デフォルトの10になります。
Note: この機能はbashの機能を恥も外聞もなく真似たものです。
INSERTやlo_insertコマンドによって返された、直前に影響を受けた oid の値です。この変数は、次のSQL コマンドの結果が表示されるまでの間のみ保証されています。
PostgreSQLのラージオブジェクトインタフェースを使って、1つのタプルに収まらないデータを特別に保存した場合、その操作全体は1つのトランザクションブロック内に含まれる必要があります。(より詳細についてはラージオブジェクトインタフェースについての文書を参照して下さい。) psql には、その内部コマンド \lo_export、\lo_import、 \lo_unlinkのいずれかが呼び出された時、進行中のトランザクション内に既に入っていることを通知する方法がありませんので、何らかの独断的な動作を取らなければなりません。この動作は、既に入っている進行中のトランザクションをロールバックするか、または、そのトランザクションをコミットするか、全く何もしないかのいずれかとなります。最後の動作を取る場合は、自分で BEGIN TRANSACTION/COMMITブロックを用意する必要があります。さもないと、その結果は予期できないものになります。(大抵は、どのような場合でも思い通りの動作が行なわれないという結果になります。)
所望する動作の選択は、この変数を"rollback"、"commit"、 "nothing" のいずれかに設定することです。デフォルトはトランザクションをロールバックすることです。1つか数個のオブジェクトの読み込みの場合はこれで問題ありません。しかし、多くのラージオブジェクトの転送を行なう場合、明示的に全てのコマンドを入れる1つのトランザクションブロックを用意することを勧めます。
デフォルトでは、非対話式なスクリプトにて、おかしなSQL 問い合わせや内部メタコマンドなどといったエラーが発生した場合、処理は続行します。これはpsqlの旧来からの動作ですが、好まれない場合もあります。この変数を設定した場合、処理中のスクリプトは即座に停止します。スクリプトが他のスクリプトから呼ばれていた場合は、呼出元のスクリプトも同様に停止します。最も外部のスクリプトがpsqlの対話式セッションからではなく、-f オプションを使って呼び出されていた場合、 psqlは致命的エラー条件(エラーコード1)と区別するためにエラーコード3を返します。
接続中のデータベースサーバのポートです。この変数は(プログラム起動時も含め、)データベースに接続する度に設定され、未設定にすることもできます。
これらは psql が発行するプロンプトがどのように見えるかを指定します。後述の "プロンプト" を参照して下さい。
この変数は-qコマンドラインオプションと同じです。対話式モードでは、あまり便利ではありません。
この変数は-Sコマンドラインオプションと同じです。実行時に未設定としたりリセットしたりできます。
この変数は-sコマンドラインオプションと同じです。
接続中のデータベースユーザです。この変数は(プログラム起動時も含め、)データベースに接続する度に設定され、未設定にすることもできます。
更に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 をシェルに渡します。二重引用符内部に対してシェルがなすべきことを行ない、-e と s/'/\\'/g を引数としてsed を実行します。sed アプリケーションがこれを解析する時、2つのバックスラッシュは1つのバックスラッシュに置き換えてから、正規表現によった置換を行ないます。多分、ある時点では、全てのUnix コマンドが同一のエスケープ文字を使用することは素晴らしいと考えたでしょう。しかし、この考えはSQLのテキスト定数もある解釈に従うため、同様に全てのバックスラッシュをエスケープしなければならないということを無視しています。このような場合、ファイルの前処理を外部で行なった方が良いでしょう。
コロン(":")も問い合わせ自体に使用できますので、次のルールが適用されます。変数が未設定な場合、"colon+name"という文字の並びは変更されません。バックスラッシュでコロンをエスケープすることで、どのような場合でも解釈されないようにすることができます。(変数用のコロン構文は ecpg のような組み込み問い合わせ言語用の SQL 標準です。配列の部分、及び、型キャスト用のコロン構文は PostgreSQLの拡張であり、競合しています。)
psqlのプロンプトの発行は好みに応じてカスタマイズできます。 PROMPT1、PROMPT2、PROMPT3という3つの変数はプロンプトの表示内容を示す文字列や特別なエスケープシーケンスを持ちます。PROMPT1はpsqlが新しい問い合わせを受け付ける際に発行される通常のプロンプトです。PROMPT2は問い合わせがセミコロンで終っていない、または、引用符が閉じていないために問い合わせの入力に更なる行が要求されている際に発行されます。PROMPT3はSQL COPYを実行している際、または、端末上でタプルの入力が要求されている際に発行されます。
対応するプロンプト変数の値が文字として表示されます。ただし、パーセント("%")のある場合は例外です。その次の文字に従って、特定の他のテキストに置き換えられます。以下の置換が定義されています。
データベースサーバの(ドメイン名の付与された)完全なホスト名、または、その接続が Unix ドメインソケットの場合は [local] となります。ただし、Unixドメインソケットがコンパイル時に設定したデフォルトの場所に存在しない場合は、 [local:/dir/name] となります。
最初のドット以降を取り除いた、データベースサーバのホスト名、または、その接続が Unix ドメインソケットの場合は [local] となります。
データベースサーバが監視するポート番号。
接続中のユーザ名。(システム上のローカルなユーザ名ではありません。)
接続中のデータベース名。
デフォルトデータベースの場合に "~"(チルダ)が出力される点を除いて、%/ と同じです。
現在のユーザがデータベースのスーパーユーザである場合、"#"、さもなくば、">"。
PROMPT1 内の場合、通常は"="、シングル行モードでは"^"、(\connect が失敗した場合に起こり得る)データベースとの接続が切れたセッションでは"!"となります。PROMPT2 内の場合、 psql が問い合わせの入力が終っていない、 /* ... */というコメントの内側にある、引用符の内側にある、の内のどの理由で更なる行の入力を要求しているかに依存した、"-"、 "*"、単一引用符、二重引用符のいずれかにこの並びは置換されます。PROMPT3 内の場合のこの並びは何も生成しません。
digitsが0x から始まる場合、残った文字は16進数として解釈され、コードに対応する文字に置換されます。0から始まる場合は、8進数として解釈され、対応する文字に置換されます。これら以外は10進数と仮定されます。
psqlのname 変数の値です。詳細については" 変数" を参照して下さい。
通常の"バックティック"による置き換えに似た、 commandの出力です。
プロンプトにパーセント印を入れる場合は、%%と書きます。デフォルトのプロンプトは、プロンプト1と2に'%/%R%# ' 、プロンプト3に'>> 'を設定した場合と同じです。
Note: この機能はtcshの機能を遠慮なく真似たものです。
psqlは、正常に終了した時には、シェルに0を、(メモリ不足やファイルが見つからないといった) それ自身に致命的なエラーが発生した時に 1 を、バックエンドとの接続が不完全になった場合やセッションが対話式でない場合に2を、ON_ERROR_STOP変数が設定されている状態でスクリプトでエラーが発生した場合に3を返します。
psqlは処理を始める前に、$HOME/.psqlrc ファイル内のコマンドを読み込み、実行しようと試みます。(このファイルにて \setやSETコマンドを使用して)好みに応じたクライアントやサーバの設定を行なうことに使用されます。
psql は行内編集や繰り返し入力が簡便になるようにreadline ライブラリと history ライブラリをサポートします。コマンド履歴は、ホームディレクトリ以下に.psql_historyというファイル名で保存され、 psql 起動時に再読み込みされます。タブによる補間もサポートされていますが、タブによる補間のロジックはSQLパーサになるようにはなっていません。これらの機能は利用可能であれば、psqlは自動的に使用するように構築されます。タブによる補間を何らかの事情により使用したくなければ、ホームディレクトリ以下の.inputrcというファイルに以下を書き込むことで無効にできます。
$if psql set disable-completion on $endif
(これはpsql の機能ではなく、readline の機能です。より詳細についてはreadlineの文書を参照して下さい。)
readline ライブラリがインストールされているにも関わらず、psql がそれを使用していないように見える場合は、PostgreqSQLの最上位の configure スクリプトによって、そのライブラリが確実に検出されるようにする必要があります。configureによって libreadline.aライブラリ(もしくはそのシェアドライブラリ) 及びreadline.hとhistory.h (もしくはreadline/readline.hとreadline/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の学習や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
少し前までのpsqlでは(一文字)コマンドの直後に最初の引数を書くことができました。この機能はまだ、互換性のために少し拡張された形でサポートされていますが、この使用方法はあまり思わしくありません。そのため、ここでは詳しく説明するつもりはありません。おかしなメッセージが表示されたとしても、このことを覚えておいて下さい。例えば、
testdb=> \foo Field separator is "oo",
は多分想定したものではありません。
psql は同一バージョンのサーバとのみうまく動作します。これは、他の組合せが全く動かないという意味ではではありませんが、多少の、または、多少とはいえないような問題が起こることがあります。
"copy in"実行中(サーバにデータが送信されている間)にControl-Cを入力すると、その動作に合ったメッセージが表示されません。 "COPY state must be terminated first" といったメッセージが表示されたとしても、\c - -を入力して接続をリセットして下さい。