psql とは PostgreSQL のターミナル型フロントエンドです。 対話的に問い合わせを入力し、PostgreSQL に対して発行して、結果を確認することができます。 また、ファイルから入力を読み込むことも可能です。 それに加え、スクリプトを記述するのを簡単にするためと、様々なタスクを自動化するために、いくつものメタコマンドと各種のシェルに似た機能を備えています。
読み込んだ全ての行を画面に表示します。これは対話式モードよりもスクリプト処理の際に有用です。これは ECHO 変数を all に設定することと同じです。
位置揃え無しの出力モードに切替えます。(さもなければ、デフォルトの位置揃えされた出力モードになります。)
psql に対し、command という 1 つのコマンド文字列を実行し、終了するよう指示します。 このコマンドはシェルスクリプト内で有用です。
command は、サーバで完全に解析可能な(つまり、psql 特有の機能は含まない)コマンド文字列、もしくは、1 つのバックスラッシュコマンドである必要があります。 このため SQL と psql メタコマンドを混在させることはできません。 以下のようにパイプを使ってその文字列を psql に渡すことで混在させることができます。 echo "\x \\ select * from foo;" | psql.
コマンド文字列が複数のSQLコマンドを含む場合、その文字列内に複数のトランザクションに分けるために、BEGIN/COMMIT コマンドが含まれない限り、1つのトランザクションで処理されます。 これは、同じ文字列をpsqlの標準入力として渡した場合の動作とは異なります。
接続するデータベースの名前を指定します。 これはコマンドラインでオプション形式でない最初の引数として dbname を指定することと同じです。
サーバに送られたコマンドを全て表示します。 これは ECHO 変数を queries に設定することと同じです。
\d やその他のバックスラッシュコマンドによって生成される実際の問い合わせを表示します。 これを使って、自作のプログラムに似たような機能を含めることができます。 これは psql 内部から ECHO_HIDDEN 変数を設定することと同じです。
対話式にコマンドを読み取るのではなく、filename ファイルをコマンドのソースとして使用します。 このファイルの処理が終了した後、psql は終了します。 これは \i 内部コマンドとほとんど同じです。
filename が - (ハイフン) の場合標準入力から読み取られます。
このオプションの使用と、psql < filename と入力することは微妙に異なります。一般的には、両者とも期待通りの動作を行ないますが、-f を使用した場合は、行番号付きのエラーメッセージなどといった、いくつかの優れた機能が有効になります。また、このオプションを使用した場合、起動時のオーバーヘッドが減少する可能性が少しあります。一方、シェルの入力リダイレクションを使用する方法では、(理論的には) 全て手作業で入力した場合の出力と全く同一な出力になることが保証されます。
separator をフィールド区切り文字として使用します。これは \pset fieldsep もしくは \f と同じです。
サーバを実行しているマシンのホスト名を指定します。 この値がスラッシュから始まる場合、Unix ドメインソケット用のディレクトリとして使用されます。
HTML 表形式を有効にします。 これは \pset format html もしくは \H コマンドと同じです。
利用可能な全てのデータベースを一覧表示します。 この他の接続関連でないオプションは無視されます。 これは \list 内部コマンドと似ています。
全ての問い合わせの出力を filename ファイルに書き込みます。 これは \o コマンドと同じです。
サーバが接続監視を行なっている、TCP ポート、もしくは、ローカルな Unix ドメインソケットファイルの拡張子を指定します。 PGPORT 環境変数の値、もし環境変数が設定されていなければ、コンパイル時に指定した値、通常は 5432 がデフォルト値となります。
\pset 形式による表示オプションをコマンドラインから指定することができます。ここではスペースではなく等号を使って名前と値を区切っていることに注意して下さい。つまり、出力形式を LaTeX にする場合、-P format=latex と入力します。
psql がメッセージ出力なしで処理を行なうように指示します。デフォルトでは、ウェルカム (welcome) メッセージや各種の出力情報を表示します。このオプションを使用した場合、このメッセージ表示がされません。-c オプションとの併用は有用です。psql 内で、QUIET 変数を設定することでも同じことができます。
separator をレコード区切り文字として使用します。これは \pset recordsep コマンドと同じです。
シングルステップモードで実行します。 これは各コマンドがサーバに送信される前に、ユーザに対して実行するかキャンセルするかについて確認を求めることを意味します。 スクリプトのデバッグのためにこれを使用して下さい。
セミコロンと同様に改行がSQLコマンドの終端となる、シングル行モードで実行します。
注意: このモードはこの使用方法に固執しているユーザ向けに用意されたものですので、無理して使用する必要はありません。特に、1 行に SQL とメタコマンドを混在させる場合、経験の浅いユーザにとってその実行順番は必ずしも分かりやすいものではありません。
カラム名と結果の行数フッタなどの表示を無効にします。 これは、\t メタコマンドと全く同じです。
HTML table タグ内に記述されるオプションを指定できます。詳細については \pset を参照して下さい。
データベース接続の前に psql がユーザ名とパスワードを尋ねるプロンプトを表示します。
概念的な欠陥のため、このオプションは推奨されません。 (デフォルトではないユーザ名の入力とサーバからの要求によるパスワード入力とは全く異なるものです。) 代替である、-U と -W オプションを参照することを勧めます。
デフォルトのユーザではなく username ユーザとしてデータベースに接続します。 (当然ですが、このための権限を持っていなければなりません。)
\set 内部コマンドのように、変数の代入を行ないます。値がもしあれば、コマンドラインで名前と値を等号で区切る必要があることに注意して下さい。変数を未設定にするためには、等号を取って下さい。値なしの変数を設定するためには、値なしで等号のみ使用して下さい。これらの代入は起動時の非常に早い段階で行なわれます。そのため、内部目的用に予約された変数は後で上書きされる可能性があります。
psql のバージョンを表示します。
データベース接続前にパスワード入力を促すように psql に対して要求します。\connect メタコマンドを使用して接続するデータベースを変更した場合であっても、セッション全体用の設定として保持します。
現在のバージョンでは、psql はサーバがパスワード認証を要求した時は常に自動的にパスワードプロンプトを表示します。 現在これは ハックされたものに基づいていますので、自動認識が予想できない失敗をする可能性があります。 そのため、このオプションを使って強制的にプロンプトを表示させます。 サーバがパスワード認証を要求した時にパスワードプロンプトが表示されない場合、その接続の試行は失敗します。
拡張テーブル形式モードを有効にします。 これは \x コマンドと同じです。
~/.psqlrc 起動用ファイルを読み込みません。
psql のコマンドライン引数に関するヘルプを表示します。
psql は、正常に終了した時には、シェルに 0 を、(メモリ不足やファイルが見つからないといった) それ自身に致命的なエラーが発生した時に 1 を、サーバとの接続が不完全になった場合やセッションが対話式でなかった場合に 2 を、ON_ERROR_STOP 変数が設定されている状態でスクリプトでエラーが発生した場合に 3 を返します。
psql は PostgreSQL の正式なクライアントアプリケーションです。 データベースに接続するためには、接続するデータベース名、ホスト名、サーバのポート番号、接続する際に使用するユーザ名が分かっている必要があります。 psql では、それらをコマンドラインオプションで指定することができ、それぞれ -d、-h、-p、および -U を使用します。オプションに属さない引数がある場合、それはデータベース名 (データベース名がある場合にはユーザ名) と見なされます。これらのオプションすべてが必ず指定されている必要はなく、指定されていない時はデフォルト値が使用されます。 ホスト名を省略した場合、psql は Unix ドメインソケット経由でローカルホストにあるサーバに接続します。デフォルトのポート番号はコンパイル時に設定されます。データベースサーバは同じデフォルト値を使用するので、多くの場合、ポートは指定する必要はありません。 デフォルトのユーザ名とデータベース名は、Unix のユーザ名です。 任意のユーザ名ですべてのデータベースに接続できるわけではありません。データベース管理者は、接続権限をユーザに知らせておかなければなりません。入力する手間を省くために、環境変数 PGDATABASE、PGHOST、PGPORT、PGUSER に適当な値を設定することもできます。
何かの原因 (権限がない、指定したホストでサーバが稼働していないなど) で接続ができなかった場合には psql は、エラーメッセージを表示し、終了します。
通常の操作において、psqlは、psqlが現在接続しているデータベース名の後に=>の文字列がついたプロンプトを表示します。以下に例を示します。
$ psql testdb
Welcome to psql 7.4.6, 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 コマンドを入力することができます。 通常、入力された行は問い合わせ終了を意味するセミコロンに達した時にサーバへと送信されます。 つまり、改行は問い合わせの終了を意味しません。 したがって、コマンドはわかりやすくするために、複数の行に渡って記述することができます。 コマンドが問題なく送られたら、画面にコマンドの結果が表示されます。
また、コマンドが実行される度に、psql は LISTEN と NOTIFY によって生成された非同期通知イベントをチェックします。
psql 内で、入力されたもので、引用符で囲まれておらず、バックスラッシュで始まるものは psql 自身によって実行される、psql のメタコマンドです。これらのコマンドは管理のためやスクリプトのために、psql を興味深いものとします。メタコマンドは一般的にスラッシュコマンド、またはバックスラッシュコマンドと呼ばれます。
psql コマンドの形式はバックスラッシュ、その直後にコマンドの動詞、その次に引数がきます。引数と動詞コマンド、またそれぞれの動詞コマンドは空白文字によって区別します。
引数に空白を含める場合、これらは単一引用符で囲みます。単一引用符を引数に含める場合には、その単一引用符の前にバックスラッシュをつけて下さい。単一引用符で囲われたものは、\n (改行)、\t (タブ)、\digits、\0digits、\0xdigits (与えられた10進数、8進数、16進数の文字) の C 言語風の置換文字の対象となります。
引用符で囲われておらず、かつコロン (:) で開始される引数は、psql 変数として扱われ、変数の値が引数として扱われます。
逆引用符 (`) で囲まれた引数は、コマンドラインとして認識され、シェルに渡されます。 コマンドの結果 (後続の改行は削除されます) は引数の値として見なされます。 逆引用符に対しても上記のエスケープシーケンスが該当します。
コマンドには、引数として SQL の (テーブル名などの) 識別子を取るものがあります。 これらの引数は SQL の構文規則に従います。 例えば引用符を伴わない文字は強制的に小文字になり、二重引用符(")で括ることで大文字小文字変換を防止でき、空白文字を識別子内に含めることができる、などです。 二重引用符内では、連続する二重引用符は結果名では1つの二重引用符に減ります。 例えば、FOO"BAR"BAZ は fooBARbazと解釈され、"A weird"" name" は A weird" name になります。
引数の解析は別の引用符で括られていないバックスラッシュがあるところで終了します。 これは、新たなメタコマンドの始まりと認識されます。 \\ (バックスラッシュ 2 つ) という特別な文字の並びは引数の終りを意味し、SQL コマンドの続きがある場合は、その解析を行います。 このような方法で、SQL コマンドと psql コマンドは 1 つの行に合わせて記述することができます。 しかし、あらゆる場合において、メタコマンドの引数は行をまたぐことはできません。
以下のメタコマンドが定義されています。
現在のテーブルの出力形式が「揃えない」になっていれば、「揃える」に切り替えます。「揃えない」でない場合は、「揃えない」に設定します。 このコマンドは下位互換性のためにあります。 一般的な解決策は \pset を参照して下さい。
現在の作業ディレクトリを directory に変更します。 引数がない場合は、現在のユーザのホームディレクトリに変更します。
ティップ: 現在の作業ディレクトリを表示するには、\!pwd を使用して下さい。
問い合わせ結果として表示される全てのテーブルタイトルの設定、または、タイトルの設定解除を行ないます。 このコマンドは、\pset title title と同じです。 (このコマンドの名前は "caption" に由来し、以前は HTML のテーブルの標題 (caption) を設定するためだけに使われていました。)
新しいデータベースへの接続または、指定ユーザ名での接続を行ないます。それまでの接続は閉じられます。dbname が - の場合、現在のデータベース名が使われます。
username が省略された場合、現在のユーザ名が使用されます。
特別な規則として、引数がない \connect の場合は、デフォルトのデータベースにデフォルトのユーザで接続します (何も引数なしで psql を起動した場合と同じことになります)。
接続の試行が (ユーザ名の間違いやアクセスが拒否された場合などの理由で) 失敗した場合、psql が対話式モードである場合に限って、それまでの接続が保持されます。非対話式スクリプトを実行している場合は、処理はエラーとなり、即座に停止します。この違いは、片方は入力ミスに対するユーザの簡便性を、もう片方は、スクリプトが間違ったデータベースを操作してしまう事故を防ぐ安全な機構を考慮して実装されています。
フロントエンド (クライアント) コピーを行ないます。 これは SQL COPY コマンドを実行する操作ですが、サーバで指定ファイルに対する読み込みまたは書き込みを行うのではなく、psql がファイルの読み書きを行い、サーバとローカルファイルシステム間でデータを送ります。 つまり、ファイルへのアクセス権限はサーバではなくローカルユーザのものを使用するので、SQL のスーパーユーザ権限は必要ありません。
このコマンドの構文は SQL COPY コマンドに似ています (詳細はその説明を参照して下さい)。 このため、\copy コマンドには特別な解析ルールが適用されていることに注意して下さい。 特に、変数の置換規則やバックスラッシュエスケープは適用されません。
ティップ: この操作は SQL COPY コマンドほど効率よくはありません。 というのは、全てのデータがクライアント/サーバ接続を通じてやりとりされなくてはならないからです。 データ量が多いときは他の手法を使用する方がよいでしょう。
注意: クライアントコピーとサーバコピーとでは、stdin 及び stdout の解釈に違いがあることに注意して下さい。 クライアントコピーでは、これらは常に psql の入出力ストリームを参照します。 サーバコピーでは、stdin は COPY 自体が読みとるところから読みとります (例えば、-f オプションで実行するスクリプト)。 そして stdout は、問い合わせ出力ストリーム (後述の \o メタコマンドを参照して下さい) を参照します。
PostgreSQL の著作権および配布条項を表示します。
pattern に一致する各リレーションについて、すべての列、それらの型、そして NOT NULL やデフォルトなどの特別な属性を表示します。 ビューリレーションの場合は、ビューの定義に従い、関連付けられているインデックス、制約、ルールおよびトリガも表示されます。 ("パターンのマッチング" は下記で説明します。)
\d+ という形のコマンドも同じですが、テーブルの列に関連付けられた全てのコメントも表示されます。
注意: \d が pattern 引数なしで使用された場合は、\dtvs と同じ意味となり、全てのテーブル、ビュー、シーケンスの一覧が表示されます。これは単に便宜のためのものです。
利用できる全ての集約関数と、その操作対象となるデータ型の一覧を表示します。 pattern が指定された場合、そのパターンに名前が一致する集約のみが表示されます。
利用できる全ての変換と文字セット符号化方式の一覧を表示します。 pattern が指定された場合、そのパターンに名前が一致する変換のみが表示されます。
利用できる型キャストの一覧を表示します。
pattern に一致するオブジェクトの説明を表示します。引数が指定されていない場合は、可視的なオブジェクトすべての説明を表示します。 どちらの場合でも、説明があるオブジェクトのみがリストされます。 ("オブジェクト" には、集約、関数、演算子、型、リレーション (テーブル、ビュー、インデックス、シーケンス、ラージオブジェクト) が含まれます)。例を下記に示します。
=> \dd version
Object descriptions
Schema | Name | Object | Description
------------+---------+----------+---------------------------
pg_catalog | version | function | PostgreSQL version string
(1 row)
オブジェクトの説明は COMMENT SQL コマンドを使用して作成することができます。
使用可能なドメインをすべて表示します。 pattern が指定されている場合は、一致するドメインのみが表示されます。
利用できる全ての関数と、その引数と戻り値の型の一覧を表示します。 pattern が指定されている場合は、そのパターンに名前が一致する関数のみが表示されます。 \df+ という形で使われた場合、各関数の言語や説明を含む付加的情報も表示されます。
注意: 不要な情報を減らすため、\df はデータ型 I/O 関数を表示しません。 これは、cstring データ型を受け入れたり返したりする関数を無視することで実装されます。
これは実際のコマンドの名前ではなく、i、s、t、v、S という文字はそれぞれ、インデックス、シーケンス、テーブル、ビュー、システムテーブルを意味します。 これらの文字のうち任意のものまたはすべてを、任意の順番で指定して、一致するすべてのオブジェクトの一覧を表示することができます。 文字 S を指定すると、システムオブジェクトのみが表示されます。 S を指定しなければ、システムオブジェクト以外のオブジェクトのみが表示されます。 コマンド名の後に + を付加すると、各オブジェクトに関連付けられている説明が、もし存在すれば表示されます。
pattern を指定すると、パターンに名前が一致するオブジェクトのみが表示されます。
これは \lo_list の別名で、ラージオブジェクトの一覧を表示します。
利用できる全てのスキーマ(名前空間)の一覧を表示します。 pattern (正規表現)を指定すると、パターンに名前が一致するスキーマのみが表示されます。
利用できる演算子と、その演算項目と戻り値を一覧表示します。 pattern を指定すると、パターンに名前が一致する演算子のみが表示されます。
使用可能なすべてのテーブルを、関連付けられているアクセス権限とともに一覧表示します。 pattern を指定すると、パターンに名前が一致するテーブルのみが表示されます。
GRANT コマンドと REVOKE コマンドは、アクセス権限の設定に使われます。 詳細については GRANT を参照して下さい。
全てのデータ型、または、pattern に一致する型のみを一覧表示します。 \dT+ という形式のコマンドは補足情報も表示します。
すべてのデータベースユーザ、もしくは、pattern に一致するユーザのみを一覧表示します。
filename が指定された場合、このファイルが編集されます。 エディタの終了後、その内容は問い合わせバッファにコピーされます。引数なしの場合、現在の問い合わせバッファは一時ファイルにコピーされ、そして同様に編集されます。
次に、新しい問い合わせバッファは、通常の psql のルールに従い、バッファ全体を 1 行として再解析されます。(このため、この方法では "スクリプト" を作成できません。この目的のためには \i を使用して下さい。) これはまた、問い合わせの終端がセミコロンである (もしくは問い合わせがセミコロンを含む) 場合、すぐに実行されることを意味しています。これ以外の場合は、単に問い合わせバッファ内に保持されるだけです。
ティップ: psql は環境変数 PSQL_EDITOR、EDITOR、VISUAL を (この順番に) 検索し、使用するエディタを決定します。これら全てが未設定である場合は、/bin/vi が実行されます。
引数をスペースで区切り、標準出力に出力し、改行します。スクリプトの出力に、情報を点在させる場合に有用です。例を下記に示します。
=> \echo `date` Tue Oct 26 21:40:57 CEST 1999
最初の引数が引用符で括られていない -n である場合、最後の改行は出力されません。
ティップ: \o コマンドを使用して問い合わせの出力先を変更していた場合、このコマンドではなく、\qecho を使用した方が良いでしょう。
クライアント側の文字セット符号化方式を設定します。 引数なしの場合、このコマンドは現在の符号化方式を表示します。
位置揃えされていない問い合わせの出力用のフィールドの区切り文字を設定します。 デフォルトは、縦棒("|")です。 一般的な出力オプションの設定方法については、\pset を参照して下さい。
現在の問い合わせ入力バッファをサーバに送ります。 また、オプションでその出力を filename に保存したり、その出力を別の Unix シェルに渡し、command を実行したりすることもできます。単なる \g はセミコロンと実質的に同じです。引数がある \g は、\o コマンドの "一度限りの" 代替手段です。
指定した SQL コマンドの構文に関するヘルプを表示します。command が指定されていない場合は、psql は構文ヘルプが存在する全てのコマンドの一覧を表示します。 command をアスタリスク (*) にすると、すべての SQL コマンドの構文ヘルプが表示されます。
注意: 入力を簡単にするため、複数単語からなるコマンドを引用符で括る必要はありません。従って、\help alter table と入力するだけで十分です。
HTML 問い合わせ出力形式を有効にします。既に HTML 形式が有効であった場合、デフォルトの位置揃えされたテキスト形式に戻します。このコマンドは互換性と簡便性のために存在します。 他の出力オプションについては、\pset を参照して下さい。
filename ファイルから入力を読みとり、キーボードから入力された場合と同じように実行します。
注意: 読みとられた行を画面上に表示させたい場合は、ECHO 変数を all に設定する必要があります。
サーバ上のすべてのデータベースの名前、所有者、文字セット符号化方式の一覧を表示します。 このコマンド名に + を追加することで、そのデータベースに関する全ての説明も表示することができます。
データベースから loid という OID を持つラージオブジェクトを読み取り、filename に書き出します。これは lo_export サーバ関数とは微妙に異なります。 こちらの関数はデータベースサーバを実行しているユーザ権限で、サーバ上のファイルシステムに対して動作します。
ティップ: ラージオブジェクトの OID を確認するためには、\lo_list を使用して下さい。
ファイルを PostgreSQL のラージオブジェクトに保存します。オプションとして、指定したコメントをそのオブジェクトに関連づけます。下記に例を示します。
foo=> \lo_import '/home/peter/pictures/photo.xcf' 'a picture of me' lo_import 152801
上の応答は、そのラージオブジェクトをオブジェクト ID 152801 として受け付けられたことを示します。 今後再びそのラージオブジェクトにアクセスしたい場合はこの番号を記憶しておかなければなりません。このため、全てのオブジェクトに人間がわかるようなコメントを常に関連づけることを推奨します。このコメントは \lo_list コマンドを使用して参照することができます。
このコマンドは、ローカルなユーザによってローカルなファイルシステムに対して動作しますが、サーバ側の lo_import は、サーバのユーザによりサーバ上のファイルシステムに対して動作します。 このため、このコマンドはサーバ側の lo_import とは微妙に異なります。
現在データベースに保存されている全ての PostgreSQLラージオブジェクト の一覧を、そのオブジェクトに付けられたコメントと一緒に表示します。
loid という OID が示すラージオブジェクトをデータベースから削除します。
ティップ: ラージオブジェクトの OID を確認するためには、\lo_list を使用して下さい。
以降の問い合わせの結果を filename ファイルに保存、もしくは、以降の問い合わせの結果を別個の Unix シェルに渡し、command を実行します。 引数がない場合、問い合わせの出力は標準出力にリセットされます。
"問い合わせの結果" には全てのテーブル、コマンドの応答、データベースサーバからの注意はもちろん、データベースに問い合わせを行なう (\d のような) 各種バックスラッシュコマンドの出力が含まれますが、エラーメッセージは含まれません。
ティップ: 問い合わせの結果の間にテキストを点在させるためには、\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) の表示、非表示を切替えます。
位置揃えなしの出力モードで使用されるレコード (行) の区切り文字を指定します。デフォルトは改行文字です。
タプルのみの表示と完全表示を切替えます。完全表示ではカラムのヘッダやタイトル、各種フッタといった余計かもしれない情報も表示します。タプルのみのモードでは、テーブルの実データのみが表示されます。
今後表示される全てのテーブル用のテーブルタイトルを設定します。これは出力に説明的なタグを付けることに使用することができます。引数がない場合、タイトルは設定されません。
HTML の table タグ内に記述する任意の属性を指定できます。これを使用して、例えば、cellpadding や bgcolor を指定することができます。border 属性は既に \pset border によって処理されていますので、このコマンドで border を指定しなくても良いでしょう。
問い合わせ、および psql ヘルプ出力の際の、ページャの使用を制御します。 PAGER 環境変数が設定されている場合、出力は指定したプログラムにパイプで渡されます。 PAGER が設定されていない場合は、プラットフォーム依存のデフォルト(more など)が使用されます。
ページャが無効の時、ページャは使用されません。 ページャが有効の時、ページャは適切な時、つまり、出力端末かつ画面に納まらない場合にのみ使用されます。 (psqlによるページャを使用すべきかどうかの判断は完全ではありません。) \pset pager はページャの有効／無効を切替えます。 また、ページャを常時使用することを意味する、alwaysにページャを設定することもできます。
例 節に、これらの形式の違いがどのように見えるかについての図があります。
ティップ: \pset には各種のショートカットコマンドがあります。\a、\C、\H、\t、\T、及び、\x を参照して下さい。
注意: 引数なしで \pset を呼び出した場合はエラーになります。将来、この呼出によって、現在の全ての表示用オプションの状態を表示するようになる予定です。
psql プログラムを終了します。
このコマンドは、\echo と同じです。 ただし、\o による設定と同様に、全ての出力が問い合わせ出力チャネルに書き出される点が異なります。
問い合わせバッファをリセット (クリア) します。
コマンドラインの履歴の表示、または、filename への保存を行ないます。filename が省略された場合、履歴は標準出力に書き出されます。このオプションは、psql が GNU 履歴ライブラリを使用するようにコンパイル時に設定されていた場合にのみ使用可能です。
注意: 現在のバージョンでは、プログラムの終了時に自動的に保存されるようになりましたので、コマンドの履歴を保存する必要が無くなりました。この履歴は psql の起動の度に自動的に読み込まれます。
value を、もしくは、複数の value が与えられた場合は、それらを連結したものを name 内部変数に設定します。2 番目の引数が無い場合は、変数は単に値が無いものとして設定されます。変数を未設定とするには、\unset コマンドを使用して下さい。
変数名には、文字、数字、アンダースコアを使用することができます。 詳細については、後述の変数を参照して下さい。
必要ならばどのようなものでも任意の変数に設定できますが、psql はいくつかの変数を特別なものとして扱っています。これらについては変数に関する節にて説明されています。
注意: このコマンドは SET SQL コマンドとは全く別のものです。
出力列名ヘッダと行数フッタの表示を切替えます。このコマンドは \pset tuples_only と同じで、簡便性のために用意されたものです。
HTML 表形式出力モードにおける table タグ内部に記述する属性を指定できます。 このコマンドは \pset tableattr table_options と同じです。
各 SQL 文にかかる時間 (ミリ秒) の表示を切り替えます。
現在の問い合わせバッファを filename ファイルに出力、もしくは、command Unix コマンドにパイプで渡します。
拡張テーブル形式モードを切替えます。 このコマンドは \pset expanded と同じものです。
使用可能なすべてのテーブルを、関連付けられているアクセス権限とともに表示します。 pattern を指定すると、パターンに名前が一致するテーブルのみが表示されます。
GRANT コマンドと REVOKE コマンドは、アクセス権限の設定に使われます。 詳細については GRANT を参照して下さい。
これは \dp ("display privileges") の別名です。
別のシェルの起動、もしくは、command Unix コマンドを実行します。引数はこれ以上解釈されず、そのままシェルに渡されます。
バックスラッシュ ("\") コマンドに関するヘルプ情報を表示します。
さまざまな \d コマンドは pattern パラメータを受け入れ、表示されるオブジェクト名を指定できます。 * は "任意の連続した文字" を表し、? は "任意の単一文字" を表します。 (この表記は Unix シェルのファイル名パターンと同様です。) 上級ユーザであれば、文字クラスなどの正規表現表記 (例えば"任意の数字" に一致する [0-9]) を使用することもできます。 これらのパターンマッチング文字が文字通り解釈されるようにするには、これらを二重引用符で囲みます。
(引用符なしの) ドットを含むパターンは、スキーマ名にオブジェクト名が続くパターンとして解釈されます。 例えば、 \dt foo*.bar* は、foo で始まるスキーマ内の bar で始まるテーブルをすべて表示します。 ドットがない場合、パターンは現行のスキーマ検索パス内で可視的であるオブジェクトのみに一致します。
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 で特別に扱われます。 これらは、実行時に変数の値を変更することで、設定変更できる特定のオプションやアプリケーションのある状態表現を示します。 これらの変数を別の目的のために使用することもできますが、プログラムの動作がすぐにとてもおかしくなる可能性がありますので、推奨されません。 慣習に従って、特別にとり扱われる変数は全て大文字 (と数字とアンダースコア) からなります。 将来の互換性が最も高くなるように、このような変数名を独自の目的に使用しないで下さい。 以下に特別にとり扱われる変数の全一覧を示します。
(デフォルトの)onの時、各SQLコマンドの実行が成功すると、自動的にコミットされます。 このモードでコミットを延期させるには、BEGIN もしくは START TRANSACTION SQL コマンドを入力する必要があります。 off もしくは未設定の場合、明示的にCOMMIT もしくは ENDを発行するまで、SQLコマンドはコミットされません。 自動コミット無効モードは、トランザクションブロック外から BEGIN や他のトランザクション制御コマンド以外の任意のコマンドを実行する前に、暗黙的なBEGINを発行することで動作します。
注意: 自動コミット無効モードでは、ABORT や ROLLBACKを発行して、明示的に失敗したトランザクションを放棄しなければなりません。 また、コミットせずにセッションを終了させた場合に作業が失われることには注意してください。
注意: 自動コミット有効モードはPostgreSQLの伝統的な振る舞いですが、自動コミット無効の方がよりSQLの仕様に近いものです。 自動コミット無効を好むのであれば、.psqlrcにそれを記載することで実現できます。
現在接続しているデータベース名です。この変数は (プログラム起動時も含め) データベースに接続する度に設定され、未設定にすることもできます。
all に設定した場合、入力された、もしくは、スクリプトからの全ての行は、解析及び実行の前に標準出力に書き出されます。 この動作をプログラム起動時に設定するには、-a スイッチを使用して下さい。 queries に設定した場合、psql はサーバに送信された全ての問い合わせのみを表示します。 このためのオプションは -e です。
この変数が設定された場合、バックスラッシュコマンドでデータベースに問い合わせを行なう時に、その問い合わせがまず表示されます。 これにより、PostgreSQL 内部について学習することも、自作プログラム内で同様の関数機能を用意することもできます。 (この動作をプログラム起動時に選択するには -E スイッチを使用してください。) この変数を noexec という値に設定した場合、問い合わせは実際にサーバに送信、実行されずに、単に表示されるだけになります。
現在のクライアント側の文字セット符号化方式です。
この変数を ignorespace に設定した場合、スペースから始まる行は履歴リストには入りません。ignoredups に設定した場合、これまでの履歴にある行は履歴リストに入りません。 ignoreboth の値は 2 つのオプションを組み合わせます。 この変数を設定しない場合、または上記以外の値を設定する場合は、対話モードで読まれるすべての行が履歴リストに保存されます。
注意: この機能は Bash の機能を恥も外聞もなく真似たものです。
コマンド履歴に保存するコマンド数です。デフォルト値は 500 です。
注意: この機能は Bash の機能を恥も外聞もなく真似たものです。
接続中のデータベースサーバホストです。この変数は (プログラム起動時も含め) データベースに接続する度に設定され、未設定にすることもできます。
未設定ならば、psql は、その対話式セッションへ EOF 文字 (通常 Control+D) が送信された時に終了します。 数値に設定した場合、終了の前に、指定数だけ送信された EOF 文字を無視します。数値以外に設定した場合は、デフォルトの 10 になります。
注意: この機能は Bash の機能を恥も外聞もなく真似たものです。
INSERT や lo_insert コマンドによって返された、最後に影響を受けた OID の値です。この変数は、次の SQL コマンドの結果が表示されるまでの間のみ保証されています。
デフォルトでは、非対話式なスクリプトにて、おかしな SQL コマンドや内部メタコマンドなどといったエラーが発生した場合、処理は続行します。 これは psql の旧来からの動作ですが、好まれない場合もあります。 この変数を設定した場合、処理中のスクリプトは即座に停止します。 スクリプトが他のスクリプトから呼ばれていた場合は、呼出元のスクリプトも同様に停止します。 最も外部のスクリプトが psql の対話式セッションからではなく、-f オプションを使って呼び出されていた場合、psql は致命的エラー条件 (エラーコード1) と区別するためにエラーコード 3 を返します。
接続中のデータベースサーバのポートです。この変数は (プログラム起動時も含め) データベースに接続する度に設定され、未設定にすることもできます。
これらは psql が発行するプロンプトがどのように見えるかを指定します。 後述の プロンプト を参照して下さい。
この変数は -q コマンドラインオプションと同じです。対話式モードでは、あまり便利ではありません。
この変数は -S コマンドラインオプションと同じです。
この変数は -s コマンドラインオプションと同じです。
接続中のデータベースユーザです。この変数は (プログラム起動時も含め) データベースに接続する度に設定され、未設定にすることもできます。
エラー報告の冗長度を制御するために、この変数をdefault、verbose、terse のいずれかに設定することができます。
更に 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 に単一引用符が含まれるかも知れないという問題が起こり得ます。 2 行目を処理する時の構文エラーを防ぐためには、この文字はエスケープする必要があります。 以下のように 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 のテキスト定数もある解釈に従うため、同様に全てのバックスラッシュをエスケープしなければならないということを無視しています。このような場合、ファイルの前処理を外部で行なった方が良いでしょう。
コロン (":") もSQLコマンド自体に使用できますので、次のルールが適用されます。 "name"が現時点で設定されている変数の名前で無い限り、":name" という文字の並びは変更されません。 バックスラッシュでコロンをエスケープすることで、どのような場合でも解釈されないようにすることができます。 (変数用のコロン構文は ECPG のような組み込み問い合わせ言語用の SQL 標準です。 配列のスライス、及び、型キャスト用のコロン構文は PostgreSQLの拡張であり、競合しています。)
psql のプロンプトの発行は好みに応じてカスタマイズできます。 PROMPT1、PROMPT2、PROMPT3 という 3 つの変数はプロンプトの表示内容を示す文字列や特別なエスケープシーケンスを持ちます。 プロンプト1は psql が新しいコマンドを受け付ける際に発行される通常のプロンプトです。 プロンプト2 はコマンドがセミコロンで終っていない、または、引用符が閉じていないためにコマンドの入力に更なる行が要求されている際に発行されます。 プロンプト3 はSQL COPY を実行している際、または、端末上で行の値の入力が要求されている際に発行されます。
選択されたプロンプト変数の値はそのまま文字として表示されます。 ただし、パーセント (%) のある場合は例外です。 その次の文字に従って、特定の他のテキストに置き換えられます。 以下の置換が定義されています。
データベースサーバの (ドメイン名の付きの) 完全なホスト名、または、その接続が Unix ドメインソケットの場合は [local] となります。 ただし、Unix ドメインソケットがコンパイル時に設定したデフォルトの場所に存在しない場合は、[local:/dir/name] となります。
最初のドットで取り除いたデータベースサーバのホスト名、または、その接続が Unix ドメインソケットの場合は [local] となります。
データベースサーバが監視するポート番号です。
データベースセッションユーザの名前です。 (この値の展開結果は、データベースセッション中に、SET SESSION AUTHORIZATION コマンドの結果として変わることがあります。 )
接続中のデータベース名です。
デフォルトデータベースの場合に ~ (チルダ) が 出力される点を除いて、%/ と同じです。
セッションユーザがデータベーススーパーユーザである場合、#、さもなくば、> となります。 (この値の展開結果は、データベースセッション中に、SET SESSION AUTHORIZATION コマンドの結果として変わることがあります。 )
プロンプト1 内の場合、通常は =、シングル行モードでは ^、(\connect が失敗した場合に起こり得る) データベースとの接続が切れたセッションでは ! となります。 プロンプト2 内の場合、psql がコマンドの入力が終っていない、/* ... */というコメントの内側にある、引用符の内側にある、の内のどの理由で更なる行の入力を要求しているかに依存した、-、*、単一引用符、二重引用符のいずれかにこの並びは置換されます。 プロンプト3 内の場合のこのシーケンスは何も生成しません。
トランザクションの状態です。 トランザクションブロック外の場合は空文字列に、トランザクションブロック内の場合は * に、失敗したトランザクションブロック内の場合は ! に、(例えば、未接続のために)トランザクションの状態が不定の場合は?になります。
指定数値コードの文字に置換されます。 digits が 0x から始まる場合、残った文字は 16 進数として解釈されます。 また、0 から始まる場合は、8 進数として解釈されます。 これら以外は 10 進数と見なされます。
psql の name 変数の値です。 詳細については 変数 を参照して下さい。
通常の "バッククオート" による置き換えに似た、command の出力です。
プロンプトにパーセント印を入れる場合は、%% と書きます。 デフォルトのプロンプトは、プロンプト 1 と 2 に'%/%R%# '、プロンプト 3 に '>> ' を設定した場合と同じです。
注意: この機能は tcsh の機能を遠慮なく真似たものです。
psql は行内編集や繰り返し入力が簡便になるように Readline ライブラリをサポートします。コマンド履歴は、ホームディレクトリ以下に .psql_history というファイル名で保存され、psql 起動時に再読み込みされます。タブによる補間もサポートされていますが、タブによる補間のロジックは SQL パーサになるようにはなっていません。 タブによる補間を何らかの事情により使用したくなければ、ホームディレクトリ以下の .inputrc というファイルに以下を書き込むことで無効にできます。
$if psql set disable-completion on $endif
(これは psql の機能ではなく、readline の機能です。詳細については Readline の文書を参照して下さい。)
初期化ファイル (.psqlrc) およびコマンド履歴ファイル (.psql_history) 用のディレクトリです。
問い合わせ結果が画面に入らない場合、このコマンドによってその結果をパイプします。 一般的な値は、more または less です。 デフォルトはプラットフォームによって異なります。 ページャの使用を禁止するには \pset コマンドを使用します。
デフォルトで接続先となるデータベースです。
デフォルトの接続パラメータです。
\e コマンドが使用するエディタです。 変数は表示されている順番に検索されます。つまり最初に設定されたものが使用されます。
\! コマンドが実行するコマンドです。
一時ファイルを格納するディレクトリです。 デフォルトは /tmp です。
psql は処理を始める前に、$HOME/.psqlrc ファイル内のコマンドを読み込み、実行しようと試みます。(このファイルで (\set や SET コマンドを使用して) 好みに応じたクライアントやサーバの設定を行なうことに使用されます。
コマンドライン履歴はファイル $HOME/.psql_history に格納されます。
旧バージョンの psql では、単一文字のバックスラッシュコマンドの後に、空白を入れずに直接最初の引数を入力することができました。 この機能は、現在でも互換性のためにある程度はサポートされていますが、この使用は推奨されないためここでは詳しく説明するつもりはありません。 おかしなメッセージが表示された場合は、このことを思い出してください。例えば、
testdb=> \foo Field separator is "oo".
はおそらく期待通りのものではありません。
psql は、同一バージョンのサーバのみとだけ円滑に動作します。これは、他の組合せが全く動かないという意味ではありませんが、多少の、または、多少とはいえないような問題が起こることがあります。 サーバのバージョンが異なると、バックスラッシュコマンドが特に失敗しやすくなります。
最初の例では、どのように複数行に渡るコマンドを入力するのかを示します。 プロンプトの変化に注意して下さい。
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