psqlとはPostgreSQLのターミナル型フロントエンドです。 対話的に問い合わせを入力し、それをPostgreSQLに対して発行して、結果を確認することができます。 また、ファイルから入力を読み込むことも可能です。 さらに、スクリプトの記述を簡便化したり、様々なタスクを自動化したりする、いくつものメタコマンドとシェルに似た各種の機能を備えています。
読み込んだ全ての行を標準出力に表示します。 これは対話式モードよりもスクリプト処理の際に有用です。 ECHO変数をallに設定するのと同じ意味を持ちます。
位置揃えなしの出力モードに切り替えます (デフォルトの出力モードは位置揃えありです)。
psqlに対し、commandという1つのコマンド文字列を実行し、終了するよう指示します。 このコマンドはシェルスクリプト内で有用です。 このオプションを使用すると起動ファイル(psqlrc and ~/.psqlrc)は無視されます。
commandは、サーバで完全に解析可能な(つまり、psql特有の機能は含まない)コマンド文字列、もしくは、バックスラッシュコマンド1つである必要があります。 このため、このオプションではSQLとpsqlメタコマンドを混在させることはできません。 これらを同時に使用するには、echo '\x \\ SELECT * FROM foo;' | psqlのようにパイプを使って文字列をpsqlに渡します(\\はメタコマンドの区切り文字です。)。
コマンド文字列が複数のSQLコマンドを含む場合、トランザクションを複数に分けるBEGIN/COMMITコマンドが明示的に文字列内に含まれない限り、それらのコマンドは1つのトランザクションで処理されます。 これは、同じ文字列をpsqlの標準入力として渡した場合の動作とは異なります。 また最後のSQLコマンドの結果のみが返されます。
接続するデータベースの名前を指定します。 コマンドラインでオプション以外の最初の引数としてdbnameを指定するのと同じ効力を持ちます。
このパラメータに=記号が含まれる場合、または有効なURI接頭辞(postgresql://またはpostgres://)から始まる場合conninfo文字列として扱われます。 詳しくは項31.1を参照してください。
サーバに送られたコマンドを標準出力にも送ります。 ECHO変数をqueriesに設定するのと同じ効力を持ちます。
\dやその他のバックスラッシュコマンドによって生成される実際の問い合わせを表示します。 これを使って、psqlの内部動作を調べることができます。 psql内部からECHO_HIDDEN変数を設定するのと同じ効力を持ちます。
対話式にコマンドを読み取るのではなく、filenameファイルをコマンドのソースとして使用します。 このファイルの処理が終了した後、psqlは終了します。 これは\iメタコマンドとほぼ同じ効力を持ちます。
filenameに-(ハイフン)を指定すると、標準入力から読み取られます。
このオプションを指定するのと、psql < filenameと入力するのでは、微妙に動作が異なります。 一般的には、両者とも期待通りの動作を行いますが、-fを使用した場合は、エラーメッセージに行番号を付けるなどの機能がいくつか有効になります。 また、このオプションを使用した場合、起動時のオーバーヘッドが減少する可能性が若干あります。 一方、シェルの入力リダイレクションを使用する方法では、(理論的には)全て手作業で入力した場合の出力とまったく同一な出力になることが保証されます。
separatorを位置揃えを行わない出力におけるフィールド区切り文字として使用します。 \pset fieldsepもしくは\fと同じ効力を持ちます。
サーバを実行しているマシンのホスト名を指定します。 この値がスラッシュから始まる場合、Unixドメインソケット用のディレクトリとして使用されます。
HTML表形式を有効にします。 \pset format htmlもしくは\Hコマンドと同じ効力を持ちます。
利用可能な全てのデータベースを一覧表示し、終了します。 この他の接続に関連しないオプションは無視されます。 \listメタコマンドと似た効力を持ちます。
すべての問い合わせの出力を通常の出力先に出力し、さらにファイルfilenameに書き出します。
行編集用のreadlineを使用しません。また履歴も使用しません。 コピー&ペースト時のタブ展開を無効にするために有用かもしれません。
全ての問い合わせの出力を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を参照してください。
デフォルトのユーザではなくusernameユーザとしてデータベースに接続します (当然、指定したユーザがデータベースに接続する権限を持っていなければなりません)。
\setメタコマンドのように、変数の代入を行います。 値がある場合、コマンド上では、名前と値を等号(=)で区切る必要があることに注意してください。 等号を指定しないと変数が未設定の状態になります。 値が空の変数を設定するには、値を指定しないで等号のみ使用してください。 これらの代入は起動時の非常に早い段階で行われます。 そのため、内部で使用するために予約されている変数は後で上書きされる可能性があります。
psqlのバージョンを表示し、終了します。
パスワードの入力を促しません。 サーバがパスワード認証を必要とし、かつ、.pgpassファイルなどの他の方法が利用できない場合、接続試行は失敗します。 バッチジョブやパスワードを入力するユーザが存在しない場合にこのオプションは有用かもしれません。
このオプションがセッション全体にわたって設定され続けることに注意してください。 このため\connectメタコマンドの使用に関しても初期接続試行と同様に影響します。
データベースに接続する前に、psqlは強制的にパスワード入力を促します。
サーバがパスワード認証を要求する場合psqlは自動的にパスワード入力を促しますので、これが重要になることはありません。 しかし、psqlは、サーバにパスワードが必要かどうかを判断するための接続試行を無駄に行います。 こうした余計な接続試行を防ぐために-Wの入力が有意となる場合もあります。
このオプションがセッション全体に対して残ることに注意してください。 このため初期接続試行と同様に\connectメタコマンドの使用にも影響を与えます。
拡張テーブル形式モードを有効にします。 これは\xコマンドと同じです。
起動用ファイル(psqlrcファイルもしくはユーザ用の~/.psqlrcファイル)を読み込みません。
位置揃えを行わない出力用のフィールド区切り文字をゼロバイトに設定します。
位置揃えを行わない出力用のレコード区切り文字をゼロバイトに設定します。 これは例えばxargs -0と連携する時に有用です。
-fオプションを使用してpsqlがスクリプトを実行する時、このオプションを併記すると、スクリプトをBEGIN/COMMITで囲み、単一トランザクション内でスクリプトを実行します。 これにより確実にすべてのコマンドが完全に成功するか、変更がまったく行われないかのいずれかになります。
スクリプト内部でBEGIN、COMMIT、ROLLBACKを使用している場合、このオプションは想定した効果をもたらしません。 また、スクリプト内部にトランザクションブロック内部で実行することができないコマンドが含まれている場合、このオプションを指定することで、そのコマンドは失敗(そしてそのためにトランザクション全体が失敗)します。
psqlのコマンドライン引数に関するヘルプを表示し、終了します。
psqlは、正常に終了した時には0を、psqlにとって致命的なエラー(メモリ不足やファイルが見つからないなど)が発生した時には1を、セッションが対話式でない状態でサーバとの接続が不完全になった時には2を、ON_ERROR_STOP変数が設定されている状態でスクリプトでエラーが発生した時には3をシェルに返します。
psqlはPostgreSQLの正式なクライアントアプリケーションです。 データベースに接続するには、接続するデータベース名、ホスト名、サーバのポート番号、接続する際に使用するユーザ名がわかっていなければなりません。 psqlでは、それらをコマンドラインオプションで指定することができます。接続するデータベース名は-d、ホスト名は-h、サーバのポート番号は-p、接続するユーザ名は-Uを使用してそれぞれ指定します。 オプションに属さない引数がある場合、それはデータベース名(データベース名が与えられている場合にはユーザ名)とみなされます。 これらのオプションは全て指定されている必要はありません。指定されていない時はデフォルト値が使用されます。 ホスト名を省略した場合、psqlはUnixドメインソケット経由でローカルホストにあるサーバに、Unixドメインソケットを持たないマシンではlocalhostへのTCP/IP経由で接続します。 デフォルトのポート番号はコンパイル時に設定されます。 データベースサーバは同じデフォルト値を使用するので、多くの場合、ポートは指定する必要はありません。 デフォルトのユーザ名とデータベース名は、Unixのユーザ名です。 任意のユーザ名で全てのデータベースに接続できるわけではありません。 データベース管理者は、接続権限をユーザに知らせておかなければなりません。
デフォルトがまったく適用できない時は、入力の手間を省くために、環境変数PGDATABASE、PGHOST、PGPORT、PGUSERに適当な値を設定することもできます。 (この他の環境変数については、項31.14を参照してください。) また、~/.pgpassファイルを使用すれば、定常的なパスワードの入力を防ぐことができ、便利です。 詳細は項31.15を参照してください。
他の接続パラメータの指定方法としてconninfo文字列またはURIがあります。 これは、データベース名の代わりに使用されます。 この機構により、接続全体に関する非常に幅広い制御を行うことができます。
$ psql "service=myservice sslmode=require" $ psql postgresql://dbmaster:5433/mydb?sslmode=require
この方法では接続パラメータの検索に、項31.17で説明するLDAPを使用することもできます。 利用できる接続オプションのすべてについての詳細は、項31.1を参照してください。
何らかの原因(権限がない、指定したホストでサーバが稼働していないなど)で接続ができなかった場合は、psqlはエラーメッセージを表示し、終了します。
標準入力または標準出力の内最低1つが端末である場合、psqlはクライアントの符号化方式を"auto"に設定します。 これはロケール設定(UnixシステムではLC_CTYPE環境変数)から適切なクライアント符号化方式を決定します。 想定した通りに動作しない場合、PGCLIENTENCODING環境変数を使用してクライアント符号化方式を上書きすることができます。
通常の操作において、psqlは、psqlが現在接続しているデータベース名の後に=>の文字列が付いたプロンプトを表示します。 以下に例を示します。
$ psql testdb psql (9.2.0) Type "help" for help. testdb=>
プロンプトに対しユーザはSQLコマンドを入力することができます。 通常、入力された行は問い合わせ終了を意味するセミコロンに達した時点でサーバへと送信されます。 つまり、改行は問い合わせの終了とはみなされません。 したがって、わかりやすくするために、コマンドは複数の行にわたって記述することができます。 コマンドが送信され問題なく実行されると、画面にコマンドの結果が表示されます。
psql内で入力されたコマンドのうち、バックスラッシュで始まり、引用符で囲まれていないものは、psql自身が実行するpsqlのメタコマンドとして扱われます。 これらのコマンドを使うと、データベースを管理したりスクリプトを作成するにあたって、psqlがより便利になります。 メタコマンドはよくスラッシュコマンド、またはバックスラッシュコマンドと呼ばれます。
psqlコマンドは、バックスラッシュ、コマンド本体、引数の順につなげた形式になっています。 引数とコマンド本体の間と引数間は、空白文字によって分割されています。
引数に空白を含める場合は単一引用符で囲みます。 単一引用符を引数に含める場合には、その単一引用符を二重にし、単一引用符で括ってください。 単一引用符で囲われた文字は、C言語と同じような置換の対象となります。 このような文字には、\n(改行)、\t(タブ)、\b (後退)、\r(復帰)、\f (改頁)、\digits(8進数で表された文字)、\xdigits(16進数で表された文字)があります。 単一引用符で括られたテキスト内でその他の任意の文字の前にバックスラッシュを付けた場合は、その文字が何であろうとその一文字だけとして扱われます。
引数の中で逆引用符(`)で囲まれたテキストは、コマンドラインとして認識され、シェルに渡されます。 コマンドの結果(末尾の改行は削除されます)で逆引用符で囲まれたテキストを置き換えます。
SQL差し替えに示すように、引数の中で引用符で囲まれていないコロン(:)の後にpsql変数名が存在する場合、そこは変数の値に置換されます。
コマンドには、引数としてSQLの(テーブル名などの)識別子を取るものがあります。 これらの引数は次のようなSQLの構文規則に従います。 引用符を伴わない文字は強制的に小文字になります。しかし、二重引用符(")で囲まれると、大文字小文字変換が行われず、空白文字を識別子内に含めることができます。 さらに、二重引用符内では、連続する2つの二重引用符は1つの二重引用符とみなされます。 例えば、FOO"BAR"BAZはfooBARbazと解釈され、"A weird"" name"はA weird" nameになります。
引数の解析は行末または引用符で囲まれていないもう1つのバックスラッシュが見つかると終了します。 引用符がないバックスラッシュは新しいメタコマンドの始まりと解釈されます。 \\(バックスラッシュ2つ)という特別な文字の並びは引数の終わりを意味するので、SQLコマンドが残されている場合は、その解析を続けます。 このように、SQLコマンドとpsqlコマンドは1つの行に自由に混合して記述することができます。 しかし、あらゆる場合において、メタコマンドの引数は行をまたぐことはできません。
メタコマンドとして、以下のものが定義されています。
現在のテーブルの出力形式が「揃えない」になっていれば「揃える」に、 「揃える」になっていれば「揃えない」に設定します。 このコマンドは後方互換性を保持するためにあります。 より一般的な解決策は\psetを参照してください。
PostgreSQLサーバへの接続を新規に確立します。 新規接続に成功した場合、以前の接続は閉ざされます。 dbname、username、host、portのいずれかが省略、あるいは -と指定された場合、対応するパラメータの値はこれまでの接続の値が使用されます。 これまで接続されていない場合は、そのパラメータの値にはlibpqのデフォルト値が使用されます。
接続の試行が(ユーザ名の間違いやアクセス拒否などの理由で)失敗した場合、psqlが対話式モードである場合に限って、それまでの接続が保持されます。 非対話式スクリプトを実行している場合は、処理はエラーとなり、即座に停止します。 この実装の違いは、対話モードでは入力ミスに対するユーザの簡便性を考慮し、非対話モードではスクリプトによって間違ったデータベースを操作することを防ぐための安全策を考慮した結果生じています。
問い合わせ結果として表示されるテーブルタイトルの設定、または、タイトルの設定解除を行います。 このコマンドは、\pset title titleと同じ効力を持ちます。 (このコマンド名は"caption"に由来します。 以前はHTMLのテーブルの標題(caption)を設定するためだけに使われていたためです。)
現在の作業ディレクトリをdirectoryに変更します。 引数がない場合は、現在のユーザのホームディレクトリに変更します。
ティップ: 現在の作業ディレクトリを表示するには、\! pwdを使用してください。
現在のデータベース接続に関する情報を出力します。
フロントエンド(クライアント)コピーを行います。 これはCOPY SQLコマンドを実行する操作ですが、サーバで指定ファイルに対する読み込みまたは書き込みを行うのではなく、psqlがファイルの読み書きや、サーバとローカルファイルシステム間のデータ送信を行います。 この場合、ファイルへのアクセス権限はサーバではなくローカルユーザのものを使用するので、SQLのスーパーユーザ権限は必要ありません。
このコマンドの構文はCOPY SQLコマンドに似ています(詳細はこのコマンドの説明を参照してください)。 このため、\copyコマンドには特別な解析規則が適用されていることに注意してください。 特に、変数の置換規則やバックスラッシュエスケープは適用されません。
\copy ... from stdin | to stdoutはそれぞれコマンドの入力と出力を元に読み書きを行います。 コマンドの発行源と同じところから、\.を読み取るまで、あるいは、ストリームがEOFに達するまで全ての行を読み続けます。 出力はコマンドの出力と同じところに送られます。 psqlの標準入力や標準出力を使用するには、pstdinやpstdoutを使用してください。 これは、SQLスクリプトファイルの内部でテーブルにデータを投入する場合に便利です。
ティップ: この操作はSQLのCOPYコマンドほど効率が良いわけではありません。 これは、全てのデータをクライアント/サーバ接続を通じてやり取りしなければならないからです。 データ量が多い時はSQLコマンドを使用する方が良いでしょう。
PostgreSQLの著作権および配布条項を表示します。
patternに一致する各リレーション(テーブル、ビュー、インデックス、シーケンス、外部テーブル)または複合型について、全ての列、列の型、テーブル空間(デフォルト以外を使用している場合)、NOT NULLやデフォルトなどの特別な属性を表示します。 関連付けられているインデックス、制約、ルールおよびトリガも表示されます。 外部テーブルでは関連する外部サーバも表示されます。 ("パターンのマッチング"については後述のパターンで定義されています。)
リレーションの一部の種類では、\dは各列について追加の情報を表示します。 例えば、シーケンスでは列の値、インデックスではインデックス式、外部テーブルでは外部データラッパのオプションです。
\d+という形式も同一のコマンドを表しますが、より多くの情報を表示します。 こちらでは、テーブルの列に関連付けられたコメントやテーブルにOIDが存在するかどうか、さらにリレーションがビューの場合はビューの定義も表示されます。
デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。
注意: \dがpattern引数なしで使用された場合は、\dtvsEと同じ意味となり、可視である全てのテーブル、ビュー、シーケンス、外部テーブルの一覧が表示されます。 これは単に便宜上のものです。
全ての集約関数と、その操作対象となるデータ型、戻り値のデータ型の一覧を表示します。 patternが指定された場合、そのパターンに名前が一致する集約のみが表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。
テーブル空間を一覧表示します。 patternが指定された場合、そのパターンに名前が一致するテーブル空間のみが表示されます。 コマンド名に+が付与された場合、各オブジェクトに関連付けされた権限についても表示します。
文字セット符号化方式間の変換の一覧を表示します。 patternが指定された場合、そのパターンに名前が一致する変換のみが表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 システムオブジェクトを含めるためには、パターンまたはS修飾子を付与してください。 コマンド名に+を付与すると、各オブジェクトに関連する説明を付けて列挙します。
型キャストの一覧を表示します。 patternが指定された場合、そのパターンに元データ型または変換先データ型が一致するキャストのみが表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。 コマンド名に+を付与すると、各オブジェクトに関連する説明を付けて列挙します。
constraint、operator class、operator family、rule、triggerという種類のオブジェクトについての説明を表示します。 他のコメントはすべて、これらのオブジェクト種類用の対応するバックスラッシュコマンドによって表示されます。
\ddはpatternに一致するオブジェクトの説明を表示します。 引数が指定されていない場合は、適切な種類の可視なオブジェクトの説明を表示します。 どちらの場合でも、一覧に表示されるのは説明を持つオブジェクトのみです デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。
オブジェクトの説明はCOMMENT SQLコマンドを使用して作成することができます。
デフォルトのアクセス権限設定を列挙します。 組み込みのデフォルトから権限設定が変更されたロール(もし適切ならばスキーマ)ごとに1項目示されます。 patternが指定された場合、パターンに一致するロール名またはスキーマ名の項目のみが列挙されます。
ALTER DEFAULT PRIVILEGESコマンドを使用して、デフォルトのアクセス権限を設定します。 権限表示の意味はGRANTで説明します。
ドメインを一覧表示します。 patternが指定されている場合は、パターンに名前が一致するドメインのみが表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。 コマンド名に+を付与すると、各オブジェクトに関連する権限と説明を付けて列挙します。
このコマンド群において、E、i, s、t、vという文字はそれぞれ、外部テーブル、インデックス、シーケンス、テーブル、ビューを表します。 これらの種類のオブジェクトのリストを入手するために、これらの文字の中の任意の文字またはすべてを指定することができます。 例えば、\ditはインデックスとテーブルを列挙します。 +がコマンド名に付与された場合、各オブジェクトは、もしあればディスク上の物理容量と関連する説明をつけて列挙されます。 patternが指定されている場合は、パターンに名称が一致する項目のみが表示されます。 デフォルトでは、ユーザが作成したオブジェクトのみが表示されます。 システムオブジェクトを含めるためにはパターンまたはS修飾子を付与してください。
外部サーバ(分かりやすく言うと"external servers")を列挙します。 patternが指定されている場合は、名前がパターンに一致するサーバのみが表示されます。 \des+構文が使用された場合、各サーバの完全な説明、サーバのACL、型、バージョン、オプション、説明が表示されます。
外部テーブル(ニーモニック"external tables")を列挙します。 patternが指定された場合、パターンにテーブル名またはスキーマ名が一致する項目のみが列挙されます。 \det+が使用された場合、汎用オプションと外部テーブルの説明も表示されます。
ユーザマップ(分かりやすく言うと"外部ユーザ")を列挙します。 patternが指定されている場合は、名前がパターンに一致するユーザのみが表示されます。 \deu+構文が使用された場合、各マップについて追加情報が表示されます。
注意 |
\deu+ではリモートユーザのユーザ名とパスワードも表示される可能性があります。 これらを外部に曝さないように注意しなければなりません。 |
外部データラッパ(分かりやすく言うと"外部ラッパ")を列挙します。 patternが指定されている場合、名前がパターンに一致する外部データラッパのみが表示されます。 \dew+構文が使用された場合、外部データラッパのACL、オプションおよび説明も表示されます。
関数とその引数と戻り値の型、および、"agg" (集約)、"normal"、"trigger"、"window"で分類される関数の種類の一覧を表示します。 特定種類の関数のみを表示させるには、対応する文字a、n、t、wをコマンドに付けて下さい。 patternが指定されている場合は、そのパターンに名前が一致する関数のみが表示されます。 \df+構文が使われた場合、各関数の、揮発性、言語、ソースコードや説明を含む付加的情報も表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。
ティップ: 特定の型を引数とする関数や特定の型を返す関数を検索するには、ページャの検索機能を使用して\dfの出力をスクロールしてください。
全文検索設定を列挙します。 patternが指定された場合、このパターンにマッチする名前の設定のみが表示されます。 \dF+形式が使用された場合、背後の全文検索パーサや各パーサトークン型についての辞書リストなど各設定の完全な説明が表示されます。
全文検索辞書を列挙します。 patternが指定された場合、このパターンにマッチする名前の辞書のみが表示されます。 \dFd+形式が使用された場合、選択された辞書それぞれについて背後の全文検索テンプレートやオプション値など更なる情報が表示されます。
全文検索パーサを列挙します。 patternが指定された場合、このパターンにマッチする名前のパーサのみが表示されます。 \dFp+形式が使用された場合、背後の関数や認知されるトークン型のリストなど各パーサの完全な説明が表示されます。
テキスト検索テンプレートを列挙します。 patternが指定された場合、このパターンにマッチする名前のテンプレートのみが表示されます。 \dFt+形式が使用された場合、テンプレートそれぞれについて背後の関数名など更なる情報が表示されます。
データベースロールを一覧表示します。 ("ユーザ"と"グループ"という概念は"ロール"に統合されましたので、このコマンドは\duと同じものになりました。) patternが指定されている場合は、そのパターンに名前が一致するロールのみが表示されます。 \dg+構文が使用された場合、ロールそれぞれについて更なる情報が表示されます。 現時点では各ロールのコメントが追加されます。
\lo_listの別名で、ラージオブジェクトの一覧を表示します。
手続き言語を列挙します。 patternを指定すると、パターンに名前が一致する言語のみが表示されます。 デフォルトではユーザが作成した言語のみが表示されます。 S修飾子を追加すると、システムオブジェクトが表示に追加されます。 +がコマンド名に追加すると、呼び出しハンドラ、有効性検証関数、アクセス権限、システムオブジェクトか否かという情報を付けて各言語が列挙されます。
スキーマ(名前空間)の一覧を表示します。 patternを指定すると、パターンに名前が一致するスキーマのみが表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたはS修飾子を追加すると、システムオブジェクトが表示に追加されます。 コマンド名の後に+を付加すると、各オブジェクトに関連付けられている権限と説明が(存在すれば)表示されます。
演算子と、その演算項目と戻り値を一覧表示します。 patternを指定すると、パターンに名前が一致する演算子のみが表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。
照合順序を列挙します。 patternを指定すると、パターンに名前が一致する照合順序のみが表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたはS修飾子を追加すると、システムオブジェクトが表示に追加されます。 コマンド名の後に+を付加すると、各照合順序に関連付けられている説明が(存在すれば)表示されます。 現在のデータベースの符号化方式で使用できる照合順序のみが表示されます。 このため結果は同じインストレーションにあるデータベースによって異なる可能性があります。
テーブル、ビュー、シーケンスを、関連付けられているアクセス権限とともに一覧表示します。 patternを指定すると、パターンに名前が一致するテーブル、ビュー、シーケンスのみが表示されます。
GRANTコマンドとREVOKEコマンドは、アクセス権限の設定に使われます。 権限の表示に関する意味はGRANTで説明します。
定義済み設定に関する設定を列挙します。 これらの設定はロール固有、データベース固有、または両者に対して行うことができます。 role-patternおよびdatabase-patternはそれぞれ特定のロールやデータベースを選択するために使用します。 省略された、または*が指定された場合、それぞれロール固有でない、または、データベース固有でない設定を含むすべての設定を列挙します。
ALTER ROLEおよびALTER DATABASEコマンドを使用してロール単位およびデータベース単位の設定を設定します。
データ型を一覧表示します。 patternを指定すると、パターンに一致する名前を持つ型のみを表示します。 +をコマンド名に付けると、型ごとに、型の内部名、サイズ、enum型では許される値、関連する権限も表示されます。 デフォルトではユーザが作成したオブジェクトのみが表示されます。 パターンまたは文字S修飾子を追加すると、システムオブジェクトが表示に追加されます。
データベースロールを一覧表示します。 ("ユーザ"と"グループ"という概念は"ロール"に統合されましたので、このコマンドは\duと同じものになりました。) patternが指定されている場合は、そのパターンに名前が一致するロールのみが表示されます。 \dg+構文が使用された場合、ロールそれぞれについて更なる情報が表示されます。 現時点では各ロールのコメントが追加されます。
インストールされた拡張を列挙します。 patternを指定すると、パターンに一致する名前の拡張のみを表示します。 \dx+形式が使用された場合、一致する拡張それぞれについて拡張に属するすべてのオブジェクトが表示されます。
filenameが指定された場合、このファイルが編集されます。 エディタを終了した後、その内容は問い合わせバッファにコピーされます。 filenameがない場合、現在の問い合わせバッファが一時ファイルにコピーされ、同様に編集されます。
次に、新しい問い合わせバッファは、通常のpsqlの規則に従い、全体を1行として再解析されます (このため、この方法では"スクリプト"を作成できません。 この目的のためには\iを使用してください)。 これは問い合わせの終端がセミコロンである(もしくは問い合わせがセミコロンを含む)場合、すぐに実行されることを意味しています。 さもなければ、単に問い合わせバッファ内に保持されるだけです。 送信するためにはセミコロンまたは\gを入力、キャンセルするためには\rを入力してください。
行番号が指定された場合、psqlはファイルまたは問い合わせバッファ内の指定行にカーソルを移します。 すべてが数字の単一引数が指定された場合、psqlはそれをファイル名ではなく行番号であると仮定することに注意してください。
ティップ: 使用するエディタを設定、調整する方法については環境を参照してください。
引数を空白で区切り、標準出力に出力し、改行します。 出力するスクリプトのところどころに情報を記載する場合に有用です。 使用例を次に示します。
=> \echo `date` Tue Oct 26 21:40:57 CEST 1999
最初の引数が引用符で囲まれていない-nである場合、最後の改行は出力されません。
ティップ: \oコマンドを使用して問い合わせの出力先を変更した場合、このコマンドではなく、\qechoを使用した方が良いでしょう。
このコマンドは指名された関数定義をCREATE OR REPLACE FUNCTIONコマンド構文で取り出し、編集します。 編集は\editと同様の方法で行われます。 エディタ終了後、更新されたコマンドは問い合わせバッファ内で待機しています。 それを送信するためにはセミコロンか\gを入力してください。 取り消す場合は\rを入力してください。
対象の関数を名前単体、または、たとえばfoo(integer, text)のように名前と引数で指定することができます。 同じ名前の関数が複数存在する場合、引数の型を指定しなければなりません。
関数が指定されなかった場合、空のCREATE FUNCTIONのテンプレートが編集用に表示されます。
行番号が指定された場合、psqlは関数本体における指定行にカーソルを移動します。 (関数本体は通常ファイルの先頭から始まらないことに注意してください。)
ティップ: 使用するエディタを設定、調整する方法については環境を参照してください。
クライアント側の文字セット符号化方式を設定します。 引数を指定しない場合、このコマンドは現在の符号化方式を表示します。
位置揃えされていない問い合わせの出力用に、フィールドの区切り文字を設定します。 デフォルトは、縦棒("|")です。 一般的な出力オプションの設定方法については、\psetを参照してください。
現在の問い合わせ入力バッファをサーバに送ります。 オプションを指定すれば、問い合わせ出力をfilenameに格納したり、その出力を別のUnixシェルに渡し、commandを実行したりすることもできます。 \gだけを指定した場合は、セミコロンと実質的に同じです。 \gに引数を指定した場合は、\oコマンドの"一度限りの"代替手段として使用できます。
指定したSQLコマンドの構文に関するヘルプを表示します。 commandが指定されていない場合は、psqlは構文ヘルプが存在する全てのコマンドの一覧を表示します。 commandをアスタリスク(*)にすると、全てのSQLコマンドの構文ヘルプが表示されます。
注意: 入力を簡単にするため、複数の単語からなるコマンドを引用符で囲む必要はありません。 \help alter tableと入力するだけで十分です。
HTML問い合わせ出力形式を有効にします。 HTML形式が有効になっている場合は、デフォルトの位置揃えされたテキスト形式に戻します。 このコマンドは互換性と簡便性のために存在します。 他の出力オプションについては、\psetを参照してください。
filenameファイルから入力を読み取り、キーボードから入力された場合と同じように実行します。
注意: 読み取られた行を画面に表示させる場合は、ECHO変数をallに設定する必要があります。
\irコマンドは\iと似ていますが、相対ファイル名の解決方法が異なります。 対話モードで実行している場合は2つのコマンドの動作は同一です。 しかし、スクリプトから呼び出す場合、\irは、現在の作業ディレクトリではなく、そのスクリプトの格納ディレクトリから見た相対ファイル名として解釈します。
サーバ上の全てのデータベースの名前、所有者、文字セット符号化方式、アクセス権限の一覧を表示します。 コマンド名に+を付けると、データベースのサイズ、デフォルトのテーブル空間、説明も表示します。 (サイズ情報は現在のユーザが接続可能なデータベースでのみ表示されます。)
データベースからloidというOIDを持つラージオブジェクトを読み取り、filenameに書き出します。
これはlo_export
サーバ関数とは微妙に異なります。
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コマンドではOIDとコメントの両方が表示されます。
このコマンドは、ローカルなユーザによってローカルなファイルシステムに対して動作します。一方、サーバ側のlo_import
は、サーバのユーザによってサーバ上のファイルシステムに対して動作します。
このコマンドとサーバ側のlo_import
は、この点で微妙に異なっています。
現在データベースに保存されている全てのPostgreSQLラージオブジェクトの一覧を、そのオブジェクトに付けられたコメントと一緒に表示します。
loidというOIDが示すラージオブジェクトをデータベースから削除します。
ティップ: ラージオブジェクトのOIDを確認するには、\lo_listを使用してください。
以降の問い合わせの結果を、filenameで指定されたファイルに保存するか、または、別のUnixシェルに渡し、commandを実行します。 引数がない場合、問い合わせの出力は標準出力にリセットされます。
"問い合わせの結果"には、全てのテーブル、コマンドの応答、データベースサーバからの注意メッセージだけでなく、データベースに問い合わせを行う(\dのような)各種バックスラッシュコマンドの出力が含まれます。ただし、エラーメッセージは含まれません。
ティップ: 問い合わせの結果の間にテキストを挿入するには、\qechoを使用してください。
現在の問い合わせバッファを標準出力に書き出します。
指定したユーザ(デフォルトは現在のユーザ)のパスワードを変更します。 このコマンドは、新しいパスワード、暗号化するかどうかを問い合わせ、それをALTER ROLEコマンドとしてサーバに送信します。 これによりコマンド履歴やサーバログなどどこにも新しいパスワードが平文で残りません。
変数nameに代入するテキストを入力するようにユーザを促します。 省略可能ですがプロンプトtextを指定することができます。 (複数の単語をプロンプトで使用する場合はそのテキストを単一引用符でくくってください。)
デフォルトでは\promptは入出力に端末を使用します。 しかし、-fコマンドラインスイッチが使用されている場合、\promptは標準入力、標準出力を使用します。
このコマンドは問い合わせ結果のテーブル出力に影響するオプションを設定します。 optionには、どのオプションを設定するのかを記述します。 valueの意味は選択したオプションにより変わります。 以下のオプション別の説明の通り、オプションの中にはvalueを省略することでトグルや設定解除を行うものがあります。 こうした動作の記載がなければ、valueを省略すると、単に現在の設定値が表示されることになります。
次は、表示の調整に関するオプションです。
valueは数値でなければなりません。 基本的には、この数字が多くなればなるほど、表示するテーブルが持つ境界線は増えますが、具体的にはそれぞれの出力形式に依存しています。 HTML書式では、この値は直接border=...属性に反映されます。 他の書式の場合は、0(境界線なし)、1(内側の境界線)、2(テーブル枠)という3つの数値のみ有効です。
wrapped書式の対象幅を設定し、そして、ページャを必要とする、拡張自動モードにおける縦表示への切替えに十分な幅で出力するかどうかを決定する幅制限を設定します。 ゼロ(デフォルト)では、環境変数COLUMNS、もしCOLUMNSが設定されていなければ、検出したスクリーンの幅、により対象幅が制御されます。 さらにcolumnsがゼロの場合、wrapped書式がスクリーン出力にのみ影響を与えることになります。 columnsが非ゼロの場合は、ファイルやパイプへの出力も同様に折り返されます。
valueを指定する場合は、拡張モードを有効または無効にするonまたはoff、あるいはautoのいずれかでなければなりません。 valueを省略した場合、このコマンドは通常モードと拡張モードをトグルします。 拡張モードを有効にした場合、問い合わせ結果は左に列名、右にデータという2つの列で出力されます。 このモードは、データが通常の"horizontal(水平)"モードによる画面表示に適していない場合に有用です。 自動設定の場合、問い合わせの出力が画面幅より広ければ拡張モードが使用され、さもなければ通常モードが使用されます。 自動設定は位置揃え書式または折り返し書式でのみ効果があります。 この他の書式では、常に拡張モードが無効の場合と同様に動作します。
位置揃えなしの出力書式で使用されるフィールド区切り文字を指定します。 これにより、例えばタブ区切り、カンマ区切りといった他プログラムがよく使用する形式を作成することができます。 タブをフィールド区切り文字として使用するには、\pset fieldsep '\t'と入力します。 デフォルトのフィールド区切り文字は'|'(縦棒)です。
位置揃えなしの出力書式で使用されるフィールド区切り文字をゼロバイトに指定します。
valueが指定された場合、それぞれテーブルフッタの表示((n rows)数)を有効または無効にするonまたはoffのいずれかでなければなりません。 valueを省略した場合、このコマンドはフッタの表示、非表示をトグルします。
出力形式をunaligned、aligned、wrapped、html、latex、troff-msのいずれかに設定します。 一意に判別できる範囲で省略が可能です (この場合、1文字でも十分であることを意味します)。
unaligned書式は、表示行の1行に1つの行の全列を、現在有効なフィールド区切り文字で区切って書き出します。 これは他のプログラムに読み込ませることを目的とした出力(例えばタブ区切りやカンマ区切り書式)を生成する場合に有用です。
aligned書式は、人間が読みやすいように、美しく整形されたテキスト出力です。 これがデフォルトです。
wrapped書式はalignedと似ていますが、データ値を複数行に折り返して対象の列幅に合うように出力します。 対象の幅は後述のcolumnsオプションにより決定されます。 psqlは列ヘッダタイトルを折り返さないことに注意して下さい。 このためwrapped書式は列ヘッダに必要とする幅全体が対象より長い場合、alignedと動作が同じになります。
html、latexおよびtroff-ms書式は対応するマークアップ言語を使用する文書内に含めることを目的とした表を出力します。 出力自体は完全な文書ではありません。 (HTMLでは大して問題にはならないでしょうが、LaTeXでは完全な文書ラッパを持たせなければなりません。)
境界線の表示形式をascii、old-asciiまたはunicodeのいずれかに設定します。 一意になれば省略形が許されます。(つまり一文字で十分であることを意味します。) デフォルトの設定はasciiです。 このオプションはalignedおよびwrapped出力書式のみで有効です。
ascii形式は通常のASCIIを使用します。 データ内部の改行は右側余白に+を使用して表します。 wrapped書式では、改行文字を使わずに、先頭行の右側余白にドット(.)を示し、以降の行の左側余白に繰り返してドットを示して、データを改行します。
old-ascii形式は通常のASCII文字を使用して、PostgreSQL 8.4以前で使用されていた方法で整形します。 データ内部の改行は列区切りの左側に:記号を使用して表します。 データを折り返す際には改行文字を使わず、列区切りの左側に;記号を使用して表します。
unicode形式はUnicode矩形描画文字を使用します。 データ内部の改行は右側の余白に復帰記号を使用して表します。 データを折り返す際には改行文字を使わず、省略記号を先頭行の右側余白に表し、以降の行の左側余白にも繰り返し表します。
border設定がゼロより大きい場合、このオプションはまた、境界線を描画する文字も決定します。 通常のASCII文字はどのような場合でも動作しますが、Unicode文字の方が認識しやすいという点で表示に優れていると思います。
null値の代わりに表示する文字列を設定します。 デフォルトでは何も表示しません。 そのため、よく空の文字列と間違うことがあります。 このような場合、\pset null '(null)'を使用する方が良いでしょう。
valueが指定された場合、それぞれ10進数マーカの左に桁のくくりを分離するロケール固有の文字を表示するか否かを指定する、onまたはoffのいずれかでなければなりません。 valueを省略した場合、このコマンドは通常出力かロケール固有の数値出力かをトグルします。
問い合わせおよびpsqlヘルプ出力の際の、ページャプログラムの使用を制御します。 PAGER環境変数が設定されている場合、出力は指定したプログラムにパイプで渡されます。 PAGERが設定されていない場合は、プラットフォーム依存のデフォルト(moreなど)が使用されます。
pagerオプションがoffの場合、ページャプログラムは使用されません。 pagerオプションがonの場合、ページャは適切な場合、つまり出力先が端末であり、その画面に合わない場合に使用されます。 またpagerオプションはalwaysに設定することもできます。 こうすると画面に合うかどうかに関わらずすべての端末出力でページャが使用されます。 valueを持たない\pset pagerはページャの使用をトグルします。
位置揃えなしの出力書式で使用されるレコード(行)の区切り文字を指定します。 デフォルトは改行文字です。
位置揃えなしの出力書式で使用されるレコードの区切り文字をゼロバイトに指定します。
html出力書式においてHTMLのtable
タグ内に記述する属性を指定します。
これを使用して、例えば、cellpaddingやbgcolorを指定することができます。
border属性は既に\pset borderによって処理されているので、このコマンドでborderを指定する必要はありません。
valueの指定がない場合、テーブル属性の設定は解除されます。
今後表示される全てのテーブル用にテーブルタイトルを設定します。 これは出力に説明のためのタグを付けたい場合に有用です。 valueがない場合、タイトルの設定が解除されます。
valueが指定された場合、それぞれタプルのみの表示を有効または無効にする、onまたはoffのいずれかでなければなりません。 valueを省略した場合、このコマンドはタプルのみの表示と通常表示をトグルします。 通常表示では列のヘッダ、タイトル、各種フッタなどのその他の情報が追加されます。 タプルのみのモードでは、テーブルの実データのみが表示されます。
例節に、これらの書式がどのように見えるかを示した図があります。
ティップ: \psetには各種のショートカットコマンドがあります。 \a、\C、\H、\t、\T、\xを参照してください。
注意: 引数なしで\psetを呼び出した場合はエラーになります。 今後のバージョンでは、現在の表示用オプションの状態が全て表示されるようになる予定です。
psqlプログラムを終了します。 スクリプトファイルでは、そのスクリプトの実行のみが終了します。
このコマンドは、\echoと同じです。 ただし、\oによる設定と同様に、出力が問い合わせ出力チャネルに書き出される点が異なります。
問い合わせバッファをリセット(クリア)します。
コマンドラインの履歴の表示、またはfilenameへの保存を行います。 filenameが省略された場合、履歴は標準出力に書き出されます。 このオプションは、コンパイル時に、psqlがGNU Readlineライブラリを使用するように設定されている場合のみ使用可能です。
value、または複数のvalueが与えられた場合はそれらを連結したものを、name psql変数に設定します。 第一引数しか指定されない場合は、変数に空の値を設定されます。 変数を未設定とするには、\unsetコマンドを使用してください。
引数をまったく取らない\setは、現在設定されているpsql変数すべての名前と値を表示します。
変数名には、文字、数字、アンダースコアを使用することができます。 詳細は、後述の変数を参照してください。 変数名は大文字小文字を区別します。
必要ならばどのようなものでも任意の変数に設定できますが、psqlはいくつかの変数を特別なものとして扱っています。 これらについては変数に関する節にて説明します。
注意: このコマンドはSQLのSETコマンドとは関係ありません。
name環境変数をvalueに設定します。 もしvalueが与えられない場合は、その環境変数を未設定状態にします。 以下に例を示します。
testdb=> \setenv PAGER less testdb=> \setenv LESS -imx4F
このコマンドは、CREATE OR REPLACE FUNCTIONコマンドの形式で、指定された関数の定義を抽出し表示します。 この定義は、\oで設定されるように、現在の問い合わせ出力チャネルに出力されます。
対象の関数は、名前だけまたは、例えばfoo(integer, text)のように名前と引数で指定することができます。 同じ名前の関数が複数存在する場合は、引数の型を指定しなければなりません。
コマンド名に+を付けると、出力行に関数本体の先頭行を1行目と数える行番号が付けられます。
出力列名ヘッダと行数フッタの表示を切り替えます。 このコマンドは\pset tuples_onlyと同じで、簡便性のために用意されています。
HTML出力書式におけるtable
タグ内部に記述する属性を指定します。
このコマンドは\pset tableattr table_optionsと同じ効力を持ちます。
パラメータがない場合、各SQL文にかかる時間(ミリ秒単位)の表示の有無を切り替えます。 パラメータがある場合、同じことを設定します。
name psql変数を未設定状態にします(削除します)。
現在の問い合わせバッファを、filenameファイルに出力するか、もしくは、command Unixコマンドにパイプで渡します。
拡張テーブル形式モードを設定またはトグルします。 このコマンドは\pset expandedと同じ効力を持ちます。
テーブル、ビュー、シーケンスを、関連付けられているアクセス権限とともに一覧表示します。 patternを指定すると、パターンに名前が一致するテーブル、ビュー、シーケンスのみが表示されます。
これは\dp("権限の表示(display privileges)")の別名です。
別のシェルを起動するか、もしくは、Unixのcommandコマンドを実行します。 引数はこれ以上解釈されず、そのままシェルに渡されます。
バックスラッシュ("\")コマンドに関するヘルプ情報を表示します。
\dコマンドでは、patternパラメータを渡して、表示するオブジェクト名を指定することができます。 パターンが正確にオブジェクト名に一致するというのが最も単純な場合です。 パターン内の文字は、SQL名と同様、通常小文字に変換されます。 例えば\dt FOOはfooという名前のテーブルを表示します。 SQL名と同様、パターンを二重引用符で括ることで小文字への変換が取り止められます。 二重引用符自体をパターン内に含めなければならない場合、二重引用符で括った文字列の中で二重引用符を二重に記載してください。 繰り返しますが、これはSQLの引用符付き識別子の規則に従ったものです。 例えば、\dt "FOO""BAR"はFOO"BARという名前のテーブルを表示します(foo"barではありません)。 SQL名と異なる点は、パターンの一部を二重引用符で括ることができる点です。 例えば、\dt FOO"FOO"BARはfooFOObarという名前のテーブルを表示します。
patternパラメータが完全に省略されている場合、\dコマンドは現在のスキーマ検索パス内で可視的なオブジェクトを全て表示します。 これは*というパターンを使用することと同じです。 (オブジェクトを含むスキーマが検索パス上にあり、同じ種類かつ同じ名前のオブジェクトが検索パス上前に存在しない場合、そのオブジェクトは可視であるといいます。 これは文において明示的なスキーマ修飾がない名前でオブジェクトを参照できることと同じです。) 可視か否かに関わらずデータベース内の全てのオブジェクトを表示するには、*.*というパターンを使用します。
パターン内部では、*は(0文字を含む)任意の文字の並びに一致し、?は任意の1文字に一致します。 (この記法はUnixシェルのファイル名パターンと似ています。) 例えば、\dt int*は、intから始まる名前を持つテーブルを表示します。 しかし、二重引用符の中では、*と?はその特別な意味を失い、文字そのものに一致することになります。
ドット(.)を含むパターンは、スキーマ名にオブジェクト名が続くパターンとして解釈されます。 例えば、\dt foo*.*bar*は、fooで始まるスキーマ内のbarを含むテーブルを全て表示します。 ドットがない場合、パターンは現行のスキーマ検索パス内で可視的なオブジェクトのみに一致します。 繰り返しますが、二重引用符で括られた文字列内のドットは特別な意味を失い、文字そのものに一致することになります。
上級者は文字クラスに、例えば任意の数に一致する[0-9]などの正規表現を使用することができます。 上述のように.が区切り文字となる点、*は正規表現の.*記法になる点、?が.になる点、$がそのまま扱われる点は例外ですが、すべての正規表現の特殊文字が項9.7.3の規定通りに動作します。 .は?と、R*は(R+|)と、R?は(R|)と記述することで、これらのパターン文字を模擬することができます。 $を正規表現文字として扱う必要はありません。 通常の正規表現の解釈と異なり、パターンは常に名前全体に一致するためです。 (言い替えると、$は自動的にパターンに追加されます。) パターンの適用位置を決められない場合は、*を先頭や末尾に記載してください。 二重引用符の内側では、正規表現の特殊文字はその意味を失い、文字そのものに一致することになる点に注意してください。 また、正規表現の特殊文字は、演算子名パターン( つまり\doの引数)では文字そのものに一致します。
psqlは一般的なUnixコマンドシェルに似た変数の置換機能を提供します。 変数とは名前と値の組み合わせです。 値として任意の長さの任意の文字列を使用できます。 名前は文字(非ラテン文字を含む)、数字、アンダースコアから構成されなければなりません。
変数を設定するには、psqlの\setメタコマンドを以下のように使用します。
testdb=> \set foo bar
この例では、foo変数をbarという値に設定しています。 変数の内容を取り出すには、以下のように変数名の前にコロンを付けます。
testdb=> \echo :foo bar
これは通常のSQLコマンド内とメタコマンド内の両方で動作します。 後述のSQL差し替えで詳しく説明します。
第二引数を持たない\setを呼び出すと、空文字列を値として持つ変数が設定されます。 変数を未設定状態にする(つまり削除する)ためには、\unsetコマンドを使用してください。 すべての変数の値を表示するためには、引数をまったく取らない\setを呼び出してください。
注意: \setの引数は他のコマンドと同じ置換規則に従います。 このため、\set :foo 'something'のような参照を作成して、Perlにおける"ソフトリンク"やPHPにおける"可変変数"に当たるものを得られます。 しかし、残念ながら(あるいは好運にも)、このような構成をうまく使用する方法はありません。 一方、\set bar :fooのようにして変数をコピーするのは、完全に有効な方法です。
これらの変数の多くは、psqlに特別扱いされています。 これらは、変数の値を変更することにより、実行時に変更可能なオプションの設定を表現します。 またpsqlの変更可能な状態を表現しているものもあります。 これらの変数を別の目的で使用することもできますが、即座にプログラムの動作がおかしくなる可能性があるため、推奨されません。 慣習上、特別視される変数の名前はすべてASCII大文字(と数字とアンダースコア)からなります。 将来的な互換性を最大限考慮するために、自分で作成した変数にはこのような変数名を使用しないでください。 以下に特別に取り扱われる変数の一覧を示します。
この変数の値がonの場合(自動コミット有効モード:デフォルト)、各SQLコマンドの実行が成功すると、自動的にコミットされます。 コミットを延期するには、BEGINもしくはSQLのSTART TRANSACTIONコマンドを入力する必要があります。 値がoffもしくは未設定の場合(自動コミット無効モード)、明示的にCOMMITもしくはENDを発行するまで、SQLコマンドはコミットされません。 自動コミット無効モードでは、トランザクションブロック以外でコマンドが発行されると、そのコマンドを実行する前に、自動的にBEGINコマンドが発行されます(ただし、そのコマンド自体がBEGINコマンドやその他のトランザクション制御コマンドである場合、トランザクションブロック内で実行することができないコマンド(VACUUMなど)である場合は除きます)
注意: したがって、自動コミット無効モードでは、ABORTやROLLBACKを発行して、明示的に失敗したトランザクションを放棄しなければなりません。 また、コミットせずにセッションを終了した場合は、作業が失われてしまうので注意してください。
注意: PostgreSQLは、伝統的に自動コミット有効モードで動作していましたが、自動コミット無効モードの方がよりSQLの仕様に近いものです。 自動コミット無効モードは、システム全体に対するpsqlrcファイル、もしくは、個人用の.psqlrcファイルで設定すれば実現できます。
SQLキーワードを補完する時に大文字小文字のどちらを使用するかを決定します。 lowerまたはupperが設定された場合、補完された単語はそれぞれ小文字または大文字になります。 preserve-lowerまたはpreserve-upper(デフォルト)が設定された場合、 補完された単語は入力済みの文字の大文字小文字を引き継ぎますが、何も入力されていない場合はそれぞれ小文字または大文字に補完されます。
現在接続しているデータベース名です。 この変数は(プログラム起動時も含め)データベースに接続する度に設定されますが、これを未設定にすることもできます。
allを設定した場合、キーボード、もしくは、スクリプトからの取得された全ての行は、解析/実行の前に標準出力に書き出されます。 この動作をプログラム起動時に設定するには、-aスイッチを使用してください。 queriesを設定した場合、psqlはサーバに送信された問い合わせのみを表示します。 これらを切り替えるオプションは-eです。
この変数が設定されている場合、バックスラッシュコマンドでデータベースに問い合わせを行う時、最初にその問い合わせが表示されます。 これにより、PostgreSQL内部動作について調べたり、自作プログラム内で同様の関数機能を用意したりすることが可能になります (この動作をプログラム起動時に選択するには-Eスイッチを使用してください)。 この変数をnoexecという値に設定した場合、問い合わせは実際にサーバに送信、実行されずに、単に表示されるだけになります。
現在のクライアント側の文字セット符号化方式です。
この変数が0より大きな整数値に設定されている場合、SELECT問い合わせの結果は、指定した行数の集合として取り出され、表示されます。 デフォルトの動作では、表示する前にすべての結果が取り出されます。 したがって、結果セットの大きさに比例する形でメモリの使用量が限定されます。 この機能を有効とする場合に100から1000までの値がよく使用されます。 この機能を使用する際には、既に一部の行が表示されている場合、問い合わせが失敗する可能性があることに注意してください。
ティップ: 任意の出力書式でこの機能を使用することができますが、デフォルトのaligned書式は適していません。 FETCH_COUNT行のグループそれぞれが別々に整形されてしまい、行のグループによって列幅が異なることになるためです。 他の出力書式は適切に動作します。
この変数をignorespaceに設定した場合、空白文字から始まる行は履歴リストには入りません。 ignoredupsに設定した場合、これまでの履歴にある行は履歴リストに入りません。 ignorebothに設定した場合は、上記の2つを組み合わせたものになります。 この変数を設定しない場合、または上記以外の値を設定する場合は、対話モードで読まれる全ての行が履歴リストに保存されます。
注意: この機能はBashの機能を真似たものです。
履歴を格納するために使用されるファイルの名前です。 デフォルトは~/.psql_historyです。 例えば、~/.psqlrcで以下を記述すると、psqlはデータベース毎に分けて履歴を管理します。
\set HISTFILE ~/.psql_history- :DBNAME
注意: この機能はBashの機能を真似たものです。
コマンド履歴に保存するコマンド数です。 デフォルト値は500です。
注意: この機能はBashの機能を真似たものです。
接続中のデータベースサーバホストです。 この変数は(プログラム起動時も含め)データベースに接続する度に設定されますが、未設定にすることもできます。
この変数を未設定にすると、対話式セッションにEOF文字(通常Control+D)が送信された時、psqlが終了します。 数値を設定すると、指定された数だけ、送信されたEOF文字を無視してから終了します。 数値以外を設定した場合は、デフォルトの10になります。
注意: この機能はBashの機能を真似たものです。
INSERTや\lo_insertコマンドによって返された、最後に影響を受けたOIDの値です。 この変数は、次のSQLコマンドの結果が表示されるまでの間のみ保証されています。
onの場合、トランザクションブロック内である文がエラーとなった時に、そのエラーは無視され、トランザクションは継続します。 interactiveの場合、対話式セッション内の場合にのみエラーは無視されます。スクリプトファイルを読み込んでいる場合は無視されません。 off(デフォルト)の場合、トランザクションブロック内の文がエラーになると、トランザクション全体をアボートします。 ON_ERROR_ROLLBACKがonという状態は、トランザクションブロック内で各コマンドの実行直前に暗黙的なSAVEPOINTを行い、エラーが起きた時にこのセーブポイントにロールバックすることで実現されています。
デフォルトではエラーの後もコマンド処理は続行されます。 この変数が設定されると、代わりに即座に停止します。 対話モードではpsqlはコマンドプロンプトに戻ります。 これ以外ではpsqlは終了し、エラーコード1を返す致命的エラー条件と区別できるように、エラーコード3を返します。 どちらの場合でも、現在実行中のスクリプト(トップレベルのスクリプト、もしあれば関連性を持つ他のスクリプトすべて)は即座に終了します。 トップレベルのコマンド文字列が複数のSQLコマンドを含む場合、その時点のコマンドで処理は終了します。
接続中のデータベースサーバのポートです。 この変数は(プログラム起動時も含め)データベースに接続する度に設定されますが、未設定にすることもできます。
これらの変数は、psqlが発行するプロンプトの見た目を指定します。 後述のプロンプトを参照してください。
この変数は-qコマンドラインオプションと同じ効力を持ちます。 対話式モードではあまり役立ちません。
この変数は-Sコマンドラインオプションと同じ効力を持ちます。
この変数は-sコマンドラインオプションと同じ効力を持ちます。
接続中のデータベースユーザです。 この変数は(プログラム起動時も含め)データベースに接続する度に設定されますが、未設定にすることもできます。
この変数をdefault、verbose、terseのいずれかに設定することで、エラー報告の冗長性を制御できます。
psqlの変数には、通常のSQL文やメタコマンドの引数の中で使用("差し替え:interpolate")できるという重要な機能があります。 さらにpsqlは、 SQLリテラルと識別子として使用される変数の値が適切に引用符付けされていることを確実にするための機能を提供します。 引用符付けをまったく行わずに差し替えるための構文は、変数名の前にコロン(:)を付けることです。 以下に例を示します。
testdb=> \set foo 'my_table' testdb=> SELECT * FROM :foo;
この例では、問い合わせはmy_tableテーブルに対して行われます。 これが安全ではない場合があることに注意して下さい。 変数の値はそのままコピーされるので、対応のとれていない引用符やバックスラッシュコマンドさえも含めることができます。 挿入した場所で変数が展開された時に、確実に正しい意味になるようにしなければなりません。
値がSQLリテラルや識別子内で使用される場合、それが引用符付けされるように調整することがもっとも安全です。 SQLリテラルとして変数値を引用符付けするためには、単一引用符内にコロン、その後に変数名を記述してください。 SQL識別子として値を引用符付けするためには、二重引用符内にコロン、その後に変数名を記述してください。 これらの式は正しく引用符と変数値内に埋め込まれた特殊文字を扱います。 前の例は以下のように記述することでより安全になります。
testdb=> \set foo 'my_table' testdb=> SELECT * FROM :"foo";
変数差し替えは、引用符付けされたSQLリテラルと識別子の中では行われません。 したがって':foo'などの式は、変数の値から引用符付けしたリテラルを生成するようには動作しません。 (値の中に埋め込まれた引用符を正しく取り扱えませんので、もし動作したとしたら安全ではありません。)
この機能の有効な利用方法の例は、ファイルの内容をテーブル列にコピーする場合も利用することができます。 その際は、ファイルをまず変数に読み込み、引用符付けした文字列として変数名を差し替えます。
testdb=> \set content `cat my_file.txt` testdb=> INSERT INTO my_table VALUES (:'content');
標準非準拠の文字列を使用しているのであれば、さらにバックスラッシュを二重にしなければなりません。 以下のように多少ややこしくなります。
testdb=> \set content '''' `sed -e "s/'/''/g" -e 's/\\/\\\\/g' < my_file.txt` ''''
(my_file.txtにNULバイトが含まれている場合、これはうまく動作しないことに注意してください。 psqlは変数値内に埋め込まれたNULバイトをサポートしません。)
コロン(:)もSQLコマンド内で正規に使用できますので、 指定した変数が現在設定されていない場合、差し替え時の見かけの置換(:name、:'name'、:"name")は行われません。 コロンをバックスラッシュでエスケープすれば、常に差し替えから保護することができます。
The colon syntax for variables is standard SQL for embedded query languages, such as ECPG. The colon syntaxes for array slices and type casts are PostgreSQL extensions, which can sometimes conflict with the standard usage. The colon-quote syntax for escaping a variable's value as an SQL literal or identifier is a psql extension. --> 変数用のコロン構文は、ECPGのような組み込みの問い合わせ言語用の標準SQLとして規定されています。 配列の一部の切り出し、および型キャスト用のコロン構文はPostgreSQLの拡張であり、標準での使用方法と競合することがあります。 SQLリテラルまたは識別子として変数の値をエスケープさせる引用符付きコロン構文はpsqlの拡張です。
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の場合、何も表示されません。
トランザクションの状態です。 トランザクションブロックの外にいる場合は空文字列に、トランザクションブロックの中にいる場合は*に、失敗したトランザクションブロックの中にいる場合は!に、(接続されていないなど)トランザクションの状態が不定の場合は?になります。
指定8進数値コードの文字に置換されます。
psqlのname変数の値です。 詳細は変数を参照してください。
通常の"逆引用符"による置き換えに似た、commandの出力です。
プロンプトには端末制御文字を含めることができます。 具体的には、色の変更、背景、プロンプトテキストの様式、端末ウィンドウのタイトルなどが指定できます。 Readlineの行編集機能を適切に動作させるためには、印字されない制御文字を%[と%]で囲んで、不可視であることを明示しなければなりません。 この記号の組み合わせはプロンプト内に複数記述することができます。 以下に例を示します。
testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# '
これにより、VT100互換の配色可能な端末では、ボールドフォントで(1;)、黄色で点滅する(33;40)プロンプトが表示されます。
プロンプトにパーセント記号を入れる場合は、%%と記述してください。 デフォルトのプロンプトは、プロンプト1と2に'%/%R%# '、プロンプト3に'>> 'を設定した場合と同じです。
注意: この機能はtcshの機能を真似たものです。
psqlは行内編集や繰り返し入力が簡便になるようにReadlineライブラリをサポートしています。 コマンド履歴は、psqlの終了時に自動的に保存され、psqlの起動時に再読み込みされます。 タブによる補間もサポートされていますが、SQLのパーサとしてコマンドを解釈して判断してくれるわけではありません。 タブによる補間を何らかの事情により使用したくなければ、ホームディレクトリ以下の.inputrcというファイルに以下のように書き込むことで無効にできます。
$if psql set disable-completion on $endif
(これはpsqlの機能ではなく、Readlineの機能です。 詳細についてはReadlineのドキュメントを参照してください)。
\pset columnsがゼロの場合、wrapped書式の幅、および、幅出力がページャを必要とするかどうかを決める幅を制御します。 また自動拡張モードでは縦書式に切り替えるべきかどうかを制御します。
問い合わせ結果が画面に入り切らない場合、このコマンドによって結果をパイプします。 一般的に指定される値は、more、またはlessです。 デフォルトはプラットフォームによって異なります。 ページャの使用を禁止するには\psetコマンドを使用します。
デフォルトの接続パラメータです(項31.14を参照)。
\eおよび\efコマンドで使用されるエディタです。 変数はこのリスト順に検索されます。 つまり最初に設定されたものが使用されます。
組込みのデフォルトエディタは、Unixシステムではvi、Windowsシステムではnotepad.exeです。
\eまたは\efが行番号引数を付けて使用された場合、この変数は、ユーザのエディタに開始行番号を渡すために使用されるコマンドライン引数を指定します。 Emacsまたはviのようなエディタでは、これはプラス(+)記号です。 オプション名と行番号の間に空白文字が必要な場合は、変数の値の最後に空白文字を含めてください。 以下に例を示します。
PSQL_EDITOR_LINENUMBER_ARG='+' PSQL_EDITOR_LINENUMBER_ARG='--line '
Unixシステム上のデフォルトは+です。 (デフォルトのエディタviに対応するものですが、他のよく使われる多くのエディタでも役に立ちます。) 一方Windowsシステムではデフォルトはありません。
コマンド履歴ファイルの場所を指定します。 チルダ(~)展開が行われます。
ユーザの.psqlrcファイルの場所を指定します。 チルダ(~)展開が行われます。
\!コマンドが実行するコマンドです。
一時ファイルを格納するディレクトリです。 デフォルトは/tmpです。
また、このユーティリティは、他のほとんどのPostgreSQLユーティリティと同様、libpqでサポートされる環境変数を使用します(項31.14を参照してください)。
-Xまたは-cオプションが渡されない限り、psqlは処理を始める前に、システム全体用のpsqlrcファイルとユーザ用の~/.psqlrcファイルのコマンドを読み込み、実行しようとします (Windowsにおける、ユーザ用の起動ファイルの名前は%APPDATA%\postgresql\psqlrc.confです)。 システム全体用のファイルの設定に関する情報についてはPREFIX/share/psqlrc.sampleを参照してください。 \setやSETコマンドを使用して、好みに応じたクライアントやサーバを設定するために使用することができます。
ユーザの~/.psqlrcファイルの場所もPSQLRC環境変数を介して明示的に設定することができます。
システム全体用のpsqlrcファイルとユーザ用の~/.psqlrcファイルに、例えば、~/.psqlrc-9.2や~/.psqlrc-9.2.5のように、ハイフン記号とPostgreSQLのメジャーリリース番号またはpsqlのマイナーリリース番号を付与することで、特定バージョンのpsql向けのファイルとすることができます。 一致するバージョンのファイルはバージョン指定のないファイルよりも優先して読み込まれます。
コマンドライン履歴は~/.psql_historyファイル、Windowsの場合は%APPDATA%\postgresql\psql_historyに格納されます。
履歴ファイルの場所もPSQL_HISTORY環境設定を介して明示的に設定することができます。
旧バージョンのpsqlでは、単一文字のバックスラッシュコマンドの後に、空白を入れずに直接最初の引数を入力することができました。 PostgreSQL 8.4からこれは許されなくなりました。
psqlが円滑に動作することを保証できるのは、同一バージョンのサーバが対象の時のみです。 異なるバージョンの組み合わせではまったく動かないという意味ではありませんが、大小の様々な問題が発生する可能性があります。 特にバックスラッシュコマンドは、サーバがpsql自身のバージョンより新しいと失敗しやすくなります。 しかし、psql自身よりもサーバが新しくなければならないということなく、\d系列のバックスラッシュコマンドは7.4までさかのぼるバージョンのサーバで動作するはずです。
psqlは"コンソールアプリケーション"としてコンパイルされます。 Windowsのコンソールウィンドウは、システムの他の部分とは異なる符号化方式を使用しているので、psqlで8ビット文字を使用する時には特別な配慮が必要です。 psqlは、コンソール用コードページとして問題があることを検出すると、起動時に警告を発します。 コンソール用コードページを変更するためには、以下の2つが必要です。
cmd.exe /c chcp 1252と入力して、コードページを設定します (1252はドイツ圏における適切なコードページです。システムに合わせて変更してください)。 Cygwinを使用しているのであれば、このコマンドを/etc/profileに追加してください。
コンソール用フォントをLucida Consoleに設定してください。 ラスタフォントは、ANSIコードページでは正しく動作しないためです。
最初に、複数行にわたるコマンドの入力例を示します。 プロンプトの変化に注意してください。
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