psql — PostgreSQLの対話的ターミナル
psql
[option
...] [dbname
[username
]]
psqlとはPostgreSQLのターミナル型フロントエンドです。 対話的に問い合わせを入力し、それをPostgreSQLに対して発行して、結果を確認することができます。 また、ファイルまたはコマンドライン引数から入力を読み込むことも可能です。 さらに、psqlは、スクリプトの記述を簡便化したり、様々なタスクを自動化したりする、いくつものメタコマンドとシェルに似た各種の機能を備えています。
-a
--echo-all
読み込んだ全ての空でない入力行を標準出力に表示します。
(これは対話式に読み込まれる行には適用されません。)
これはECHO
変数をall
に設定するのと同じ意味を持ちます。
-A
--no-align
位置揃えなしの出力モードに切り替えます。
(デフォルトの出力モードはaligned
(位置揃えあり)です。)
これは\pset format unaligned
と同等です。
-b
--echo-errors
失敗したSQLコマンドを標準エラー出力に出力します。
これはECHO
変数をerrors
に設定するのと同等です。
-c command
--command=command
psqlに対し、指定のコマンド文字列command
を実行するよう指示します。
このオプションは繰り返すことができ、また-f
オプションと任意の順序で組み合わせることができます。
-c
または-f
が指定されると、psqlは標準入力からコマンドを読み取りません。
その代わりに、すべての-c
オプションおよび-f
オプションを順に処理した後、終了します。
command
は、サーバで完全に解析可能な(つまり、psql特有の機能は含まない)コマンド文字列、もしくは、バックスラッシュコマンド1つである必要があります。
このため、-c
オプション内ではSQLとpsqlメタコマンドを混在させることはできません。
これらを同時に使用するには、-c
オプションを繰り返し利用するか、あるいはパイプを使って文字列をpsqlに渡します。
例えば、
psql -c '\x' -c 'SELECT * FROM foo;'
あるいは
echo '\x \\ SELECT * FROM foo;' | psql
のようにします(\\
はメタコマンドの区切り文字です)。
-c
に渡される各SQLのコマンド文字列は、単一の要求としてサーバに送信されます。
このため、トランザクションを複数に分けるBEGIN
/COMMIT
コマンドが明示的に文字列内に含まれない限り、文字列内に複数のSQLコマンドが含まれていたとしても、サーバはそれを1つのトランザクションとして実行します。
(複数問い合わせの文字列をどのようにサーバが処理するかについて、詳しくは53.2.2.1を参照してください。)
また、psqlは文字列内の最後のSQLコマンドの結果しか出力しません。
同じ文字列をファイル、あるいはpsqlの標準入力として渡した場合、psqlは各SQLコマンドを別々に送信しますので、この場合とは動作が異なります。
この動作のため、1つの-c
の文字列に2つ以上のSQLコマンドを指定すると、予期しない結果をもたらすことがあります。
-c
のコマンドを繰り返し使うか、あるいは、上記のようにechoを使うか、以下の例のようにシェルのヒアドキュメントを使うことで、psqlの標準入力に複数のコマンドを入力する方が良いでしょう。
psql <<EOF \x SELECT * FROM foo; EOF
--csv
CSV(コンマ区切り値)出力モードに切り替えます。
これは\pset format csv
と同等です。
-d dbname
--dbname=dbname
接続するデータベースの名前を指定します。
コマンドラインでオプション以外の最初の引数としてdbname
を指定するのと同じ効力を持ちます。
dbname
は接続文字列でも構いません。
その場合、接続文字列パラメータは衝突するコマンドラインオプションに優先します。
-e
--echo-queries
サーバに送られるすべてのSQLコマンドを標準出力にも送ります。
ECHO
変数をqueries
に設定するのと同じ効力を持ちます。
-E
--echo-hidden
\d
やその他のバックスラッシュコマンドによって生成される実際の問い合わせを表示します。
これを使って、psqlの内部動作を調べることができます。
これは変数ECHO_HIDDEN
をon
に設定するのと同じ効力を持ちます。
-f filename
--file=filename
標準入力ではなく、ファイルfilename
からコマンドを読み取ります。
このオプションは繰り返すことができ、また-c
オプションと任意の順序で組み合わせることができます。
-c
または-f
が指定されると、psqlは標準入力からコマンドを読み取りません。
その代わりに、すべての-c
オプションおよび-f
オプションを順に処理した後、終了します。
その点を除けば、このオプションは\i
メタコマンドとほぼ同等です。
filename
に-
(ハイフン)を指定すると、標準入力からEOFを示すもの、または\q
メタコマンドまで読み取られます。
これは対話的入力をファイルからの入力と混在させるために使うことができます。
ただし、この場合、Readlineは使われないことに注意してください(-n
が指定された場合と同様です)。
このオプションを指定するのと、psql <
と入力するのでは、微妙に動作が異なります。
一般的には、両者とも期待通りの動作を行いますが、filename
-f
を使用した場合は、エラーメッセージに行番号を付けるなどいくつか便利な機能が有効になります。
また、このオプションを使用した場合、起動時のオーバーヘッドが減少する可能性が若干あります。
一方、シェルの入力リダイレクションを使用する方法では、(理論的には)全て手作業で入力した場合の出力とまったく同一な出力になることが保証されます。
-F separator
--field-separator=separator
separator
を位置揃えを行わない出力におけるフィールド区切り文字として使用します。
\pset fieldsep
もしくは\f
と同じ効力を持ちます。
-h hostname
--host=hostname
サーバを実行しているマシンのホスト名を指定します。 この値がスラッシュから始まる場合、Unixドメインソケット用のディレクトリとして使用されます。
-H
--html
HTML出力モードに切り替えます。
これは、\pset format html
もしくは\H
コマンドと同等です。
-l
--list
利用可能な全てのデータベースを一覧表示し、終了します。
この他の接続に関連しないオプションは無視されます。
\list
メタコマンドと似た効力を持ちます。
このオプションが使用されるときは、別のデータベース名がコマンドラインで指定されない限り(オプション-d
または、環境変数ではない非オプション引数、おそらくサービスエントリーを通じて)、psqlは、postgres
データベースに接続します。
-L filename
--log-file=filename
すべての問い合わせの出力を通常の出力先に出力し、さらにファイルfilename
に書き出します。
-n
--no-readline
行編集用のReadlineを使用しません。 またコマンド履歴も使用しません。 コピー&ペースト時のタブ展開を無効にするために有用かもしれません。
-o filename
--output=filename
全ての問い合わせの出力をfilename
ファイルに書き込みます。
これは\o
コマンドと同じ効力を持ちます。
-p port
--port=port
サーバが接続監視を行っているTCPポートもしくはローカルUnixドメインソケットファイルの拡張子を指定します。
環境変数PGPORT
の値、環境変数が設定されていない場合はコンパイル時に指定した値(通常は5432)がデフォルト値となります。
-P assignment
--pset=assignment
\pset
形式により表示オプションを指定します。
ここでは空白ではなく等号を使って名前と値を区切っていることに注意してください。
たとえば、出力形式をLaTeXにする場合、-P format=latex
と入力します。
-q
--quiet
psqlがメッセージ出力なしで処理を行うように指示します。
デフォルトでは、ウェルカム(welcome)メッセージや各種の情報が表示されますが、
このオプションを使用した場合、これらのメッセージが表示されません。
-c
オプションと併用すると便利です。
これは変数QUIET
をon
に設定するのと同じ効力を持ちます。
-R separator
--record-separator=separator
separator
を位置揃えを行わない出力におけるレコード区切り文字として使用します。
これは\pset recordsep
と同じです。
-s
--single-step
シングルステップモードで実行します。 これは各コマンドがサーバに送信される前に、ユーザに対して実行するかキャンセルするかについて確認を求めることを意味します。 スクリプトのデバッグを行う時に使用してください。
-S
--single-line
シングル行モードで実行します。このモードでは、セミコロンと同じように改行もSQLコマンドの終端として扱われます。
このモードはどうしてもこのような方式を使用したいユーザ向けに用意されたもので、必ずしも使用が推奨されるわけではありません。 特に、1行にSQLとメタコマンドを混在させる場合、経験の浅いユーザにとってその実行順番は必ずしもわかりやすいものではありません。
-t
--tuples-only
列名と結果の行数フッタなどの表示を無効にします。
これは、\t
および\pset tuples_only
と同等です。
-T table_options
--table-attr=table_options
HTMLのtable
タグで使用されるオプションを指定します。
詳細は\pset tableattr
を参照してください。
-U username
--username=username
デフォルトのユーザではなくusername
ユーザとしてデータベースに接続します
(当然、そうする権限を持っていなければなりません)。
-v assignment
--set=assignment
--variable=assignment
\set
メタコマンドのように、変数の代入を行います。
値がある場合、コマンド行上では、名前と値を等号(=)で区切る必要があることに注意してください。
変数を未設定の状態にするには、等号を指定しないでください。
値が空の変数を設定するには、値を指定しないで等号のみ使用してください。
これらの代入はコマンド行処理の段階で行われます。
そのため、接続状態を表す変数は後で上書きされる可能性があります。
-V
--version
psqlのバージョンを表示し、終了します。
-w
--no-password
パスワードの入力を促しません。
サーバがパスワード認証を必要とし、かつ、.pgpass
ファイルなどの他の情報源からパスワードが入手可能でない場合、接続試行は失敗します。
バッチジョブやスクリプトなどパスワードを入力するユーザが存在しない場合にこのオプションは有用かもしれません。
このオプションはセッション全体にわたって設定されたままであることに注意してください。
このため\connect
メタコマンドの使用に関しても初期接続試行と同様に影響します。
-W
--password
パスワードが使われない場合であっても、データベースに接続する前にpsqlは強制的にパスワード入力を促します。
サーバがパスワード認証を必要とし、かつ、.pgpass
ファイルなどの他の情報源からパスワードが入手可能でない場合、psqlは常にパスワード入力を促します。
しかし、psqlは、サーバにパスワードが必要かどうかを判断するための接続試行を無駄に行います。
こうした余計な接続試行を防ぐために-W
の入力が有意となる場合もあります。
このオプションはセッション全体に対して設定されたままであることに注意してください。
このため初期接続試行と同様に\connect
メタコマンドの使用にも影響を与えます。
-x
--expanded
拡張テーブル形式モードを有効にします。
これは\x
および\pset expanded
と同じです。
-X,
--no-psqlrc
起動用ファイル(psqlrc
ファイルおよびユーザ用の~/.psqlrc
ファイルのどちらも)を読み込みません。
-z
--field-separator-zero
位置揃えを行わない出力用のフィールド区切り文字をゼロバイトに設定します。
これは\pset fieldsep_zero
と同じです。
-0
--record-separator-zero
位置揃えを行わない出力用のレコード区切り文字をゼロバイトに設定します。
これは例えばxargs -0
と連携する時に有用です。
これは\pset recordsep_zero
と同じです。
-1
--single-transaction
このオプションは、1つ以上の-c
オプションや-f
オプションと組み合わせてのみ使うことができます。
これによりpsqlは、最初のそのようなオプションの前にBEGIN
コマンドを発行し、最後のオプションの後にCOMMIT
コマンドを発行するようになります。
そうすることで、全てのコマンドが単一のトランザクションに囲まれます。
これによりすべてのコマンドが成功して完了するか、変更がまったく行われないかのいずれかになります。
コマンド自体がBEGIN
、COMMIT
、ROLLBACK
を含んでいる場合、このオプションは期待した効果を得ることができません。
また、個別のコマンドがトランザクションブロック内部で実行できない場合、このオプションを指定することで、そのトランザクション全体が失敗します。
-?
--help[=topic
]
psqlに関するヘルプを表示し、終了します。
オプションのtopic
パラメータ(デフォルトはoptions
)はpsqlのどの部分を説明するかを選択します。
commands
はpsqlのバックスラッシュコマンドについて、options
はpsqlに渡すことができるコマンド行オプションについて、variables
はpsqlの設定変数についてのヘルプを表示します。
psqlは、正常に終了した時には0を、psqlにとって致命的なエラー(メモリ不足やファイルが見つからないなど)が発生した時には1を、セッションが対話式でない状態でサーバとの接続が不完全になった時には2を、ON_ERROR_STOP
変数が設定されている状態でスクリプトでエラーが発生した時には3をシェルに返します。
psqlはPostgreSQLの正式なクライアントアプリケーションです。
データベースに接続するには、接続するデータベース名、ホスト名、サーバのポート番号、接続する際に使用するユーザ名がわかっていなければなりません。
psqlでは、それらをコマンドラインオプションで指定することができます。接続するデータベース名は-d
、ホスト名は-h
、サーバのポート番号は-p
、接続するユーザ名は-U
を使用してそれぞれ指定します。
オプションでない引数がある場合、それはデータベース名(データベース名が与えられている場合にはユーザ名)とみなされます。
これらのオプションは全て指定されている必要はありません。便利なデフォルト値があります。
ホスト名を省略した場合、psqlはUnixドメインソケット経由でローカルホスト上のサーバに、Unixドメインソケットを持たないマシンではlocalhost
にTCP/IP経由で接続します。
デフォルトのポート番号はコンパイル時に設定されます。
データベースサーバは同じデフォルト値を使用するので、多くの場合、ポートは指定する必要はありません。
デフォルトのユーザ名とデータベース名は、OSのユーザ名です。
任意のユーザ名で全てのデータベースに接続できるわけではありません。
データベース管理者は、接続権限をユーザに知らせておかなければなりません。
デフォルトが完全には適用できない時は、入力の手間を省くために、環境変数PGDATABASE
、PGHOST
、PGPORT
、PGUSER
に適当な値を設定することもできます。
(この他の環境変数については、34.15を参照してください。)
また、~/.pgpass
ファイルを使用すれば、定常的なパスワードの入力を省略でき、便利です。
詳細は34.16を参照してください。
他の接続パラメータの指定方法としてconninfo
文字列またはURIがあります。
これは、データベース名の代わりに使用されます。
この機構により、接続全体に関する非常に幅広い制御を行うことができます。
以下に例を示します。
$psql "service=myservice sslmode=require"
$psql postgresql://dbmaster:5433/mydb?sslmode=require
この方法では接続パラメータの検索に、34.18で説明するLDAPを使用することもできます。 利用できる接続オプションのすべてについての詳細は、34.1.2を参照してください。
何らかの原因(権限がない、指定したホストでサーバが稼働していないなど)で接続ができなかった場合は、psqlはエラーメッセージを表示し、終了します。
標準入力および標準出力の両方が端末である場合、psqlはクライアントの符号化方式を「auto」に設定します。
これはロケール設定(Unixシステムでは環境変数LC_CTYPE
)から適切なクライアント符号化方式を決定します。
想定した通りに動作しない場合、環境変数PGCLIENTENCODING
を使用してクライアント符号化方式を上書きすることができます。
通常の操作において、psqlは、psqlが現在接続しているデータベース名の後に=>
の文字列が付いたプロンプトを表示します。
以下に例を示します。
$ psql testdb
psql (14.5)
Type "help" for help.
testdb=>
プロンプトに対しユーザはSQLコマンドを入力することができます。 通常、入力された行はコマンド終了を意味するセミコロンに達した時点でサーバへと送信されます。 改行はコマンドの終了とはみなされません。 したがって、わかりやすくするために、コマンドは複数の行にわたって記述することができます。 コマンドが送信され問題なく実行されると、画面にコマンドの結果が表示されます。
安全なスキーマの利用パターンを適用していないデータベースに信頼できないユーザがアクセス可能な場合は、セッションの開始時にsearch_path
から、誰でも書き込みができるスキーマを削除してください。
options=-csearch_path=
を接続文字列に追加するか、SELECT pg_catalog.set_config('search_path', '', false)
を他のSQLの前に発行することができます。
この配慮はpsqlに固有のものではありません。
任意のSQLを実行するすべてのインタフェースに適用されるものです。
また、コマンドが実行される度に、psqlはLISTEN
とNOTIFY
によって生成された非同期通知イベントを検査します。
Cの形式のブロックコメントは、サーバに送信され、サーバによって取り除かれますが、SQL標準のコメントはpsqlによって取り除かれます。
psql内で入力されたコマンドのうち、引用符で囲まれていないバックスラッシュで始まるものは、psql自身が実行するpsqlのメタコマンドとして扱われます。 これらのコマンドを使うと、データベースを管理したりスクリプトを作成するにあたって、psqlがより便利になります。 メタコマンドはよくスラッシュコマンド、またはバックスラッシュコマンドとも呼ばれます。
psqlコマンドは、バックスラッシュ、コマンド本体、引数の順につなげた形式になっています。 引数とコマンド本体の間および引数と引数の間は、空白文字によって分割されています。
引数に空白を含める場合は単一引用符で囲みます。
単一引用符を引数に含める場合には、単一引用符で括られた文字列の中で、その単一引用符を2つ続けてください。
単一引用符で囲われた文字は、C言語と同じような置換の対象となります。
このような文字には、\n
(改行)、\t
(タブ)、\b
(後退)、\r
(復帰)、\f
(改頁)、\
digits
(8進数で表された文字)、\x
digits
(16進数で表された文字)があります。
単一引用符で括られたテキスト内でその他の任意の文字の前にバックスラッシュを付けた場合は、その文字が何であろうとその一文字だけとして扱われます。
SQL Interpolationで説明されているとおり、引数の中に引用符で囲まれていないコロン(:
)とそれに続くpsql変数がある場合、その部分は変数の値で置換されます。
そこで説明されている:'
およびvariable_name
':"
という形式も同様に機能します。
variable_name
":{?
構文は、変数が定義済みかどうかをテストできます。
これはTRUEかFALSEに置き換えられます。
コロンをバックスラッシュでエスケープすると置換が防止されます。
variable_name
}
引数の中で逆引用符(`
)に囲まれた文字列は、シェルに渡されるコマンド行として解釈されます。
逆引用符に囲まれた文字列は、コマンドの出力(行末の改行はすべて削除されます)で置換されます。
逆引用符に囲まれた文字列内では、:
という形式でvariable_name
variable_name
がpsqlの変数名であるものが、その変数の値で置換されることを除いて、特別な引用やその他の処理は起きません。
また:'
という形式なら、それが変数値で置換された上で、それがシェルコマンドの単一の引数となるよう適切に引用符が付けられます。
(変数に何が入っているのか正確に理解しているのでなければ、ほとんどすべての場合で後者の形式の方が望ましいでしょう。)
復帰文字、改行文字をすべてのプラットフォームで安全に引用することはできないので、そのような文字が変数値に含まれていた場合は、variable_name
':'
はエラーメッセージを表示し、変数値による置換を行いません。
variable_name
'
コマンドには、引数として(テーブル名などの)SQLの識別子を取るものがあります。
これらの引数は次のようなSQLの構文規則に従います。
引用符を伴わない文字は強制的に小文字になります。しかし、二重引用符("
)で囲まれると、大文字小文字変換が行われず、空白文字を識別子内に含めることができます。
さらに、二重引用符内では、連続する2つの二重引用符は1つの二重引用符とみなされます。
例えば、FOO"BAR"BAZ
はfooBARbaz
と解釈され、"A weird"" name"
はA weird" name
になります。
引数の解析は行末または引用符で囲まれていないもう1つのバックスラッシュが見つかると終了します。
引用符がないバックスラッシュは新しいメタコマンドの始まりと解釈されます。
\\
(バックスラッシュ2つ)という特別な文字の並びは引数の終わりを意味するので、SQLコマンドが残されている場合は、その解析を続けます。
このように、SQLコマンドとpsqlコマンドは1つの行に自由に混合して記述することができます。
しかし、あらゆる場合において、メタコマンドの引数は行をまたぐことはできません。
メタコマンドの多くは問い合わせバッファの上で動作します。 これは入力されたSQLコマンド文字列で、まだ実行のためにサーバに送信されていないものをすべて保持するだけのバッファです。 これには以前の入力行や、同じ行のメタコマンドより前に入力されたすべての文字列も含まれます。
以下のメタコマンドが定義されています。
\a
現在のテーブルの出力形式が「揃えない」になっていれば「揃える」に、
「揃える」になっていれば「揃えない」に設定します。
このコマンドは後方互換性を保持するためにあります。
より一般的な解決策は\pset
を参照してください。
\c
または \connect [ -reuse-previous=on|off
] [ dbname
[ username
] [ host
] [ port
] | conninfo
]
PostgreSQLサーバへの新規の接続を確立します。
接続のパラメータは、位置の構文(1つ以上のデータベース名、ユーザ、ホスト、ポート)、あるいはconninfo
接続文字列で指定できます。後者の詳細は34.1.1で説明します。
引数が与えられなければ、新しい接続は以前と同じパラメータを使って作られます。
dbname
、username
、host
、port
のいずれについても-
を指定するのは、パラメータを省略するのと同じになります。
新しい接続では以前の接続での接続パラメータを再利用できます。データベース名、ユーザ、ホスト、ポートだけでなく、sslmode
のようなその他の設定もです。
デフォルトでは、パラメータは位置の構文では再利用されますが、conninfo
文字列が与えられた場合はそうではありません。
第一引数で-reuse-previous=on
あるいは-reuse-previous=off
を渡すことで、このデフォルトと異なる動作をさせることができます。
パラメータが再利用される場合、位置パラメータとして明示的に指定されなかったパラメータやconninfo
文字列で指定されていないパラメータは、既存の接続のパラメータから取得されます。
例外は、host
設定が位置の構文を使った以前の値から変更された場合に、既存の接続のパラメータにあるhostaddr
設定が削除されることです。
また、既存の接続で使われたパスワードは、ユーザ、ホスト、ポート設定が変更されていない場合にのみ再利用されます。
コマンドで特定のパラメータを指定せず、かつ再利用もしない場合は、libpqのデフォルトが使用されます。
新規接続に成功した場合、以前の接続は閉じられます。
接続の試行が(ユーザ名の間違いやアクセス拒否などの理由で)失敗した場合、psqlが対話式モードである場合、それまでの接続が保持されます。
非対話式スクリプトを実行している場合は、古い接続は閉じられエラーが報告されます。
これはスクリプトを終了させるかもしれませんし、させないかもしれません。終了させない場合、別の\connect
コマンドが実行に成功するまで、データベースにアクセスするコマンドはすべて失敗します。
この実装の違いは、対話モードでは入力ミスに対するユーザの利便性を考慮し、非対話モードではスクリプトによって間違ったデータベースを操作することを防ぐための安全策を考慮した結果決められました。
\connect
コマンドがパラメータの再利用を試す場合には、再利用する値は必ず最後に接続に成功したものであり、その後で試して失敗したものではないことに注意してください。
しかしながら、非対話モードで\connect
が失敗した場合には、スクリプトは失敗した\connect
から再利用する値を得ようとしますので、パラメータを後で再利用できません。
例:
=> \c mydb myuser host.dom 6432 => \c service=foo => \c "host=localhost port=5432 dbname=mydb connect_timeout=10 sslmode=disable" => \c -reuse-previous=on sslmode=require -- sslmodeのみ変更 => \c postgresql://tom@localhost/mydb?application_name=myapp
\C [ title
]
問い合わせ結果として表示されるテーブルのタイトルの設定、または、タイトルの設定解除を行います。
このコマンドは、\pset title
と同じ効力を持ちます。
(このコマンド名は「標題(caption)」に由来します。
以前はHTMLのテーブルの標題を設定するためだけに使われていたためです。)
title
\cd [ directory
]
現在の作業ディレクトリをdirectory
に変更します。
引数がない場合は、現在のユーザのホームディレクトリに変更します。
現在の作業ディレクトリを表示するには、\! pwd
を使用してください。
\conninfo
現在のデータベース接続に関する情報を出力します。
\copy { table
[ ( column_list
) ] }
from
{ 'filename'
| program 'command'
| stdin | pstdin }
[ [ with ] ( option
[, ...] ) ]
[ where condition
]
\copy { table
[ ( column_list
) ] | ( query
) }
to
{ 'filename'
| program 'command'
| stdout | pstdout }
[ [ with ] ( option
[, ...] ) ]
フロントエンド(クライアント)コピーを行います。
これはCOPY
SQLコマンドを実行する操作ですが、サーバで指定ファイルに対する読み込みまたは書き込みを行うのではなく、psqlがファイルの読み書きや、サーバとローカルファイルシステム間のデータ送信を行います。
この場合、ファイルへのアクセス権限はサーバではなくローカルユーザのものを使用するので、SQLのスーパーユーザ権限は必要ありません。
program
が指定された場合、command
がpsqlにより実行され、command
から、または、command
へのデータはサーバとクライアント間を行き来します。
ここでも、実行権限はローカル側のユーザであり、サーバ側ではなく、SQLスーパーユーザ権限は必要とされません。
\copy ... from stdin
では、データ行は、コマンドの発行源と同じところから、\.
を読み取るまで、あるいは、ストリームがEOFに達するまで読み続けます。
このオプションは、SQLスクリプトファイルの内部でテーブルにデータを投入する場合に便利です。
\copy ... to stdout
では、出力はpsqlコマンドの出力と同じところに送られますが、COPY
コマンドのステータスは表示されません(これはデータ行と混同してしまうかもしれないからです)。
コマンドの入力元やcount
\o
オプションに関わらず、psqlの標準入力や標準出力を読み書きするには、from pstdin
あるいはto pstdout
と書いてください。
このコマンドの構文はSQLのCOPY
コマンドに似ています。
データの入力元と出力先以外のすべてのオプションはCOPY
と同じです。
このため\copy
メタコマンドには特別な解析規則が適用されていることに注意してください。
他のほとんどのメタコマンドとは異なり、行の残り部分の全体は常に\copy
の引数として解釈され、引数内の変数の置換や逆引用符の展開は行われません。
\copy ... to
と同じ結果を得る他の方法はSQLのCOPY ... TO STDOUT
コマンドを使って、\g
かfilename
\g |
で終了することです。
program
\copy
と違い、この方法はコマンドが複数行にわたっても良いですし、変数の置換や逆引用符の展開式も使用できます。
全データがクライアント/サーバ接続を通らなければならないため、これらの操作は、ファイルやデータソースまたは宛先のプログラムを指定したSQLのCOPY
コマンドほどには効率的ではありません。
大量のデータにはSQLコマンドがより望ましいでしょう。
\copyright
PostgreSQLの著作権および配布条項を表示します。
\crosstabview [
colV
[ colH
[ colD
[ sortcolH
] ] ] ]
問い合わせのバッファを実行し(\g
と同様)、その結果をクロス表形式で表示します。
問い合わせは少なくとも3つの列を返す必要があります。
colV
で特定される出力列が縦方向のヘッダになり、colH
で特定される出力列が横方向のヘッダになります。
colD
は表内に表示される出力列を特定します。
オプションのsortcolH
で水平方向のヘッダをソートする列を指定できます。
それぞれの列の指定は、列番号(1から始まります)でも列名でも可能です。
列名については、通常のSQLの大文字小文字変換および引用の規則が適用されます。
省略した場合、colV
は列1、colH
は列2となります。
colH
はcolV
とは異なるものでなければなりません。
colD
を指定しない場合、問い合わせの結果にはちょうど3つの列がなければならず、colV
でもcolH
でもない列がcolD
となります。
縦方向のヘッダは一番左の列に表示され、colV
の列にある値が問い合わせ結果と同じ順序で現れますが、重複するものは除かれます。
横方向のヘッダは1行目に表示され、colH
の列にある値が現れますが、重複するものは除かれます。
デフォルトでは、これらは問い合わせの結果と同じ順序で表示されます。
しかしオプションのsortcolH
引数が指定された場合は、colH
の値は対応するsortcolH
の値に従ってソートされて横方向のヘッダに現れますが、sortcolH
の列の値は整数値でなければなりません。
クロス表の内側では、colH
のそれぞれの個別値x
とcolV
のそれぞれの個別値y
に対して、その交点(x,y)
に位置するセルに、問い合わせの結果のcolH
の値がx
でcolV
の値がy
である行のcolD
列の値が現れます。
そのような行がなければ、セルは空欄になります。
そのような行が複数あると、エラーが報告されます。
\d[S+] [ pattern
]
pattern
にマッチする各リレーション(テーブル、ビュー、マテリアライズドビュー、インデックス、シーケンス、外部テーブル)または複合型について、全ての列、列の型、テーブル空間(デフォルト以外を使用している場合)、NOT NULL
やデフォルトなどの特別な属性を表示します。
関連付けられているインデックス、制約、ルールおよびトリガも表示されます。
外部テーブルでは関連する外部サーバも表示されます。
(「パターンのマッチング」については後述のPatternsで定義されています。)
一部の種類のリレーションでは、\d
は各列について追加の情報を表示します。
例えば、シーケンスでは列の値、インデックスではインデックス式、外部テーブルでは外部データラッパのオプションです。
\d+
というコマンド形式も同一ですが、より多くの情報を表示します。
こちらでは、テーブルの列に関連付けられたコメントやテーブルにOIDが存在するかどうか、リレーションがビューの場合はビューの定義、デフォルトと異なるreplica identityの設定、リレーションにアクセスメソッドがあるならアクセスメソッド名も表示されます。
デフォルトではユーザが作成したオブジェクトのみが表示されます。
システムオブジェクトを含めるためには、パターンまたはS
修飾子を付与してください。
\d
がpattern
引数なしで使用された場合は、\dtvmsE
と同じ意味となり、可視である全てのテーブル、ビュー、マテリアライズドビュー、シーケンス、外部テーブルの一覧が表示されます。
これは純粋に利便性のためです。
\da[S] [ pattern
]
集約関数と、その戻り値のデータ型、演算対象となるデータ型の一覧を表示します。
pattern
が指定された場合、そのパターンに名前がマッチする集約のみが表示されます。
デフォルトではユーザが作成したオブジェクトのみが表示されます。
システムオブジェクトを含めるためには、パターンまたはS
修飾子を付与してください。
\dA[+] [ pattern
]
アクセスメソッドの一覧を表示します。
pattern
が指定された場合は、そのパターンにマッチする名前のアクセスメソッドのみが表示されます。
コマンド名の後に+
が付加された場合は、各メソッドに関連付けられたハンドラ関数および説明も表示されます。
\dAc[+]
[access-method-pattern
[input-type-pattern
]]
演算子クラスの一覧を表示します(38.16.1を参照してください)。
access-method-pattern
が指定されていれば、そのパターンにマッチする名前のアクセスメソッドと関係する演算子クラスのみが表示されます。
input-type-pattern
が指定されていれば、そのパターンにマッチする名前の入力型と関係する演算子クラスのみが表示されます。
コマンド名の後に+
が付加された場合は、各演算子クラスに関連付けられた演算子族および所有者も表示されます。
\dAf[+]
[access-method-pattern
[input-type-pattern
]]
演算子族の一覧を表示します(38.16.5を参照してください)。
access-method-pattern
が指定されていれば、そのパターンにマッチする名前のアクセスメソッドと関係する演算子族のみが表示されます。
input-type-pattern
が指定されていれば、そのパターンにマッチする名前の入力型と関係する演算子族のみが表示されます。
コマンド名の後に+
が付加された場合は、各演算子族に関連付けられた所有者も表示されます。
\dAo[+]
[access-method-pattern
[operator-family-pattern
]]
演算子族に関連する演算子の一覧を表示します(38.16.2を参照してください)。
access-method-pattern
が指定されていれば、そのパターンにマッチする名前のアクセスメソッドと関係する演算子族のメンバーのみが表示されます。
operator-family-pattern
が指定されていれば、そのパターンにマッチする名前の演算子族のメンバーのみが表示されます。
コマンド名の後に+
が付加された場合は、(順序演算子であれば)ソート演算子族も表示されます。
\dAp[+]
[access-method-pattern
[operator-family-pattern
]]
演算子族に関連するサポート関数の一覧を表示します(38.16.3を参照してください)。
access-method-pattern
が指定されていれば、そのパターンにマッチする名前のアクセスメソッドと関係する演算子族の関数のみが表示されます。
operator-family-pattern
が指定されていれば、そのパターンにマッチする名前の演算子族の関数のみが表示されます。
コマンド名の後に+
が付加された場合は、実際のパラメータの一覧を伴って、冗長に表示されます。
\db[+] [ pattern
]
テーブル空間を一覧表示します。
pattern
が指定された場合、そのパターンに名前がマッチするテーブル空間のみが表示されます。
コマンド名に+
が付与された場合、各テーブル空間に関連付けされたオプション、ディスク上のサイズ、権限、摘要についても表示します。
\dc[S+] [ pattern
]
文字セット符号化方式間の変換の一覧を表示します。
pattern
が指定された場合、そのパターンに名前がマッチする変換のみが表示されます。
デフォルトではユーザが作成したオブジェクトのみが表示されます。
システムオブジェクトを含めるためには、パターンまたはS
修飾子を付与してください。
コマンド名に+
を付与すると、各オブジェクトに関連する説明を付けて表示します。
\dC[+] [ pattern
]
型キャストの一覧を表示します。
pattern
が指定された場合、そのパターンに元データ型または変換先データ型がマッチするキャストのみが表示されます。
コマンド名に+
を付与すると、各オブジェクトに関連する説明を付けて表示します。
\dd[S] [ pattern
]
constraint
、operator class
、operator family
、rule
、trigger
という種類のオブジェクトについての説明を表示します。
他のコメントはすべて、これらのオブジェクト種類用の対応するバックスラッシュコマンドによって表示されます。
\dd
はpattern
にマッチするオブジェクトの説明を表示します。
引数が指定されていない場合は、適切な種類の可視なオブジェクトの説明を表示します。
どちらの場合でも、一覧に表示されるのは説明を持つオブジェクトのみです
デフォルトではユーザが作成したオブジェクトのみが表示されます。
システムオブジェクトを含めるためには、パターンまたはS
修飾子を付与してください。
オブジェクトの説明はCOMMENT
SQLコマンドを使用して作成することができます。
\dD[S+] [ pattern
]
ドメインの一覧を表示します。
pattern
が指定された場合、ドメイン名がそのパターンにマッチするもののみが表示されます。
デフォルトではユーザが作成したオブジェクトのみが表示されます。
システムオブジェクトを含めるには、パターンを指定するか、あるいはS
修飾子を付けてください。
コマンド名の後に+
を付けた場合は、各オブジェクトの権限と説明も表示されます。
\ddp [ pattern
]
デフォルトのアクセス権限設定を一覧表示します。
組み込みのデフォルトから権限設定が変更されたロール(および適切ならばスキーマも)ごとに1項目示されます。
pattern
が指定された場合、パターンにマッチするロール名またはスキーマ名の項目のみが表示されます。
ALTER DEFAULT PRIVILEGES
コマンドを使用して、デフォルトのアクセス権限を設定します。
権限表示の意味は5.7で説明します。
\dE[S+] [ pattern
]
\di[S+] [ pattern
]
\dm[S+] [ pattern
]
\ds[S+] [ pattern
]
\dt[S+] [ pattern
]
\dv[S+] [ pattern
]
このコマンド群において、E
、i
、m
、s
、t
、v
という文字はそれぞれ、外部テーブル、インデックス、マテリアライズドビュー、シーケンス、テーブル、ビューを表します。
これらの種類のオブジェクトの一覧を表示するために、これらの文字の中の任意の文字またはすべてを任意の順番で指定することができます。
例えば、\dti
はテーブルとインデックスを列挙します。
+
がコマンド名に付与された場合、各オブジェクトは、もしあれば永続性の状態(permanent、temporary、またはunlogged)、ディスク上の物理容量、関連する説明をつけて表示されます。
pattern
が指定されている場合は、パターンに名称がマッチする項目のみが表示されます。
デフォルトでは、ユーザが作成したオブジェクトのみが表示されます。
システムオブジェクトを含めるためにはパターンまたはS
修飾子を付与してください。
\des[+] [ pattern
]
外部(foreign)サーバ(つまり「external servers」)を一覧表示します。
pattern
が指定されている場合は、名前がパターンにマッチするサーバのみが表示されます。
\des+
構文が使用された場合、サーバのアクセス権限、型、バージョン、オプション、説明など各サーバの完全な説明が表示されます。
\det[+] [ pattern
]
外部(foreign)テーブル(つまり「external tables」)を一覧表示します。
pattern
が指定された場合、パターンにテーブル名またはスキーマ名がマッチするもののみが表示されます。
\det+
が使用された場合、汎用オプションと外部テーブルの説明も表示されます。
\deu[+] [ pattern
]
ユーザマップ(つまり「external users」)を一覧表示します。
pattern
が指定されている場合は、名前がパターンにマッチするユーザのみが表示されます。
\deu+
構文が使用された場合、各マップについて追加情報が表示されます。
\deu+
ではリモートユーザのユーザ名とパスワードも表示される可能性があります。
これらを外部に曝さないように注意しなければなりません。
\dew[+] [ pattern
]
外部データラッパ(つまり「external wrappers」)を一覧表示します。
pattern
が指定されている場合、名前がパターンにマッチする外部データラッパのみが表示されます。
\dew+
構文が使用された場合、外部データラッパのアクセス権限、オプションおよび説明も表示されます。
\df[anptwS+] [ pattern
[ arg_pattern
... ] ]
関数とその結果のデータ型、引数のデータ型、および、「agg」 (集約)、「normal」、「procedure」、「trigger」、「window」で分類される関数の種類の一覧を表示します。
特定種類の関数のみを表示させるには、対応する文字a
、n
、p
、t
、w
をコマンドに付けて下さい。
pattern
が指定されている場合は、そのパターンに名前がマッチする関数のみが表示されます。
追加の引数は、型名のパターンで、関数の第1、第2などの引数の型名にマッチします。
(マッチする関数は指定したものよりも多くの引数を取るかもしれません。
それを防ぐには、arg_pattern
の最後にダッシュ-
を書いてください。)
デフォルトではユーザが作成したオブジェクトのみが表示されます。
システムオブジェクトを含めるためには、パターンまたはS
修飾子を付与してください。
\df+
構文が使われた場合、各関数の、揮発性、並列処理での安全性、所有者、セキュリティ分類、アクセス権限、言語、ソースコードや説明を含む付加的情報も表示されます。
\dF[+] [ pattern
]
全文検索設定を一覧表示します。
pattern
が指定された場合、このパターンにマッチする名前の設定のみが表示されます。
\dF+
形式が使用された場合、使用される全文検索パーサや各パーサトークン型についての辞書リストなど各設定の完全な説明が表示されます。
\dFd[+] [ pattern
]
全文検索辞書を一覧表示します。
pattern
が指定された場合、このパターンにマッチする名前の辞書のみが表示されます。
\dFd+
形式が使用された場合、選択された辞書それぞれについて使用される全文検索テンプレートやオプション値など更なる情報が表示されます。
\dFp[+] [ pattern
]
全文検索パーサを一覧表示します。
pattern
が指定された場合、このパターンにマッチする名前のパーサのみが表示されます。
\dFp+
形式が使用された場合、使用される関数や認知されるトークン型のリストなど各パーサの完全な説明が表示されます。
\dFt[+] [ pattern
]
テキスト検索テンプレートを一覧表示します。
pattern
が指定された場合、このパターンにマッチする名前のテンプレートのみが表示されます。
\dFt+
形式が使用された場合、テンプレートそれぞれについて使用される関数名など更なる情報が表示されます。
\dg[S+] [ pattern
]
データベースロールを一覧表示します。
(「ユーザ」と「グループ」という概念は「ロール」に統合されましたので、このコマンドは\du
と同じものになりました。)
デフォルトでは、ユーザによって作成されたロールのみが表示されます。
システムロールを含めるにはS
修飾子を付与してください。
pattern
が指定されている場合は、そのパターンに名前がマッチするロールのみが表示されます。
\dg+
構文が使用された場合、ロールそれぞれについて更なる情報が表示されます。
現時点では各ロールのコメントが追加されます。
\dl
\lo_list
の別名で、ラージオブジェクトの一覧を表示します。
\dL[S+] [ pattern
]
手続き言語を一覧表示します。
pattern
を指定すると、パターンに名前がマッチする言語のみが表示されます。
デフォルトではユーザが作成した言語のみが表示されます。
システムオブジェクトを含めるためには、パターンまたはS
修飾子を付与してください。
+
をコマンド名に追加すると、呼び出しハンドラ、有効性検証関数、アクセス権限、システムオブジェクトか否かという情報を付けて各言語が表示されます。
\dn[S+] [ pattern
]
スキーマ(名前空間)の一覧を表示します。
pattern
を指定すると、パターンに名前がマッチするスキーマのみが表示されます。
デフォルトではユーザが作成したオブジェクトのみが表示されます。
パターンまたはS
修飾子を追加すると、システムオブジェクトが表示に追加されます。
コマンド名の後に+
を付加すると、各オブジェクトに関連付けられている権限と説明が(存在すれば)表示されます。
\do[S+] [ pattern
[ arg_pattern
[ arg_pattern
] ] ]
演算子と、その演算項目と結果の型を一覧表示します。
pattern
を指定すると、パターンに名前がマッチする演算子のみが表示されます。
arg_pattern
を1つ指定すると、パターンに右辺の引数の型名がマッチする前置演算子のみが表示されます。
arg_pattern
を2つ指定すると、パターンに引数の型名がマッチする二項演算子のみが表示されます。
(あるいは、単項演算子の使われない引数に対して-
と書いてください。)
デフォルトではユーザが作成したオブジェクトのみが表示されます。
システムオブジェクトを含めるためには、パターンまたはS
修飾子を付与してください。
コマンド名に+
を付加すると、各演算子についての追加情報が表示されますが、現在はその元になっている関数の名前だけです。
\dO[S+] [ pattern
]
照合順序を一覧表示します。
pattern
を指定すると、パターンに名前がマッチする照合順序のみが表示されます。
デフォルトではユーザが作成したオブジェクトのみが表示されます。
システムオブジェクトを含めるためには、パターンまたはS
修飾子を付与してください。
コマンド名の後に+
を付加すると、各照合順序に関連付けられている説明が(存在すれば)表示されます。
現在のデータベースの符号化方式で使用できる照合順序のみが表示されることに注意してください。
このため同じインストレーションであってもデータベースによって結果が異なる可能性があります。
\dp [ pattern
]
テーブル、ビュー、シーケンスを、関連付けられているアクセス権限とともに一覧表示します。
pattern
を指定すると、パターンに名前がマッチするテーブル、ビュー、シーケンスのみが表示されます。
アクセス権限の設定にはGRANT
コマンドとREVOKE
コマンドが使われます。
権限の表示に関する意味は5.7で説明します。
\dP[itn+] [ pattern
]
パーティション化されたリレーションの一覧を表示します。
pattern
が指定されている場合は、名前がパターンにマッチするエントリのみが表示されます。
修飾子t
(テーブル)とi
(インデックス)をコマンドに付けて、表示されるリレーションの種類を限定できます。
デフォルトでは、パーティション化されたテーブルとインデックスの一覧が表示されます。
修飾子n
(「nested」)が使われた、もしくはパターンが指定された場合、ルートでないパーティション化されたリレーションが含められ、各パーティション化されたリレーションの親を表示しながら列が表示されます。
コマンド名の後に+
が付けられた場合、リレーションの説明と一緒に、各リレーションのパーティションの大きさの合計も表示されます。
n
が+
と組み合わされた場合、大きさが2つ表示されます。1つは直接アタッチされたリーフパーティションの合計の大きさで、もう1つは間接的にアタッチされたサブパーティションを含む全パーティションの合計の大きさです。
\drds [ role-pattern
[ database-pattern
] ]
定義済み設定に関する設定を一覧表示します。
これらの設定はロール固有、データベース固有、またはその両方です。
role-pattern
およびdatabase-pattern
はそれぞれ特定のロールやデータベースを選択するために使用します。
パターンが省略された場合、または*
が指定された場合、ロール固有ではない、または、データベース固有ではない設定を含め、すべての設定を表示します。
ロール単位およびデータベース単位の設定を定義するにはALTER ROLE
およびALTER DATABASE
コマンドを使用します。
\dRp[+] [ pattern
]
レプリケーションのパブリケーションを一覧表示します。
pattern
が指定された場合、名前がそのパターンにマッチするパブリケーションのみが表示されます。
コマンド名の後に+
が付けられた場合、各パブリケーションに関連付けられているテーブルも表示されます。
\dRs[+] [ pattern
]
レプリケーションのサブスクリプションを一覧を表示します。
pattern
が指定された場合、名前がそのパターンにマッチするサブスクリプションのみが表示されます。
コマンド名の後に+
が付けられた場合、サブスクリプションの追加属性も表示されます。
\dT[S+] [ pattern
]
データ型を一覧表示します。
pattern
を指定すると、パターンにマッチする名前を持つ型のみを表示します。
+
をコマンド名に付けると、型ごとに、型の内部名、サイズ、enum
型では許される値、関連する権限も表示されます。
デフォルトではユーザが作成したオブジェクトのみが表示されます。
システムオブジェクトを含めるためには、パターンまたはS
修飾子を付与してください。
\du[S+] [ pattern
]
データベースロールを一覧表示します。
(「ユーザ」と「グループ」という概念は「ロール」に統合されましたので、このコマンドは\dg
と同じものになりました。)
pattern
が指定されている場合は、そのパターンに名前がマッチするロールのみが表示されます。
デフォルトでは、ユーザによって作成されたロールのみが表示されます。
システムロールを含めるにはS
修飾子を付与してください。
\du+
構文が使用された場合、ロールそれぞれについて更なる情報が表示されます。
現時点では各ロールのコメントが追加されます。
\dx[+] [ pattern
]
インストールされた拡張を一覧表示します。
pattern
を指定すると、パターンにマッチする名前の拡張のみを表示します。
\dx+
形式が使用された場合、マッチする拡張それぞれについて拡張に属するすべてのオブジェクトが表示されます。
\dX [ pattern
]
拡張統計情報を一覧表示します。
pattern
が指定されている場合は、そのパターンに名前がマッチする拡張統計情報のみが表示されます。
拡張統計情報の各種の状態は、その統計値の種類(例えば、Ndistinct)にちなんだ名前の列に表示されます。
defined
はその統計情報の作成が要求されたことを意味し、NULLは要求されていないことを意味します。
ANALYZE
が実行され、統計情報がプランナで利用可能であるかどうかを知るには、pg_stats_ext
が使えます。
\dy[+] [ pattern
]
イベントトリガを一覧表示します。
pattern
を指定すると、パターンにマッチする名前のイベントトリガのみを表示します。
+
をコマンド名に追記すると、関連する説明を付けて各オブジェクトを表示します。
\e
または\edit
[ filename
] [ line_number
]
filename
が指定された場合、このファイルが編集されます。
エディタを終了した後、ファイルの内容は問い合わせバッファにコピーされます。
filename
が指定されない場合、現在の問い合わせバッファが一時ファイルにコピーされ、同様に編集されます。
現在の問い合わせバッファが空の場合、最も最近に実行された問い合わせが一時ファイルにコピーされ、同様に編集されます。
ファイルや以前の問い合わせを編集していて、ファイルを変更せずにエディタを終了した場合には、問い合わせバッファはクリアされます。
そうでなければ、問い合わせバッファの新しい内容が、psqlの通常の規則に従い、全体を1行として再解析されます。
完全な問い合わせはすべて即座に実行されます。
つまり、問い合わせバッファにセミコロンが含まれるか、セミコロンで終わっている場合、そこまでの部分すべてが実行され、問い合わせバッファから削除されます。
問い合わせバッファ内に残ったものはすべて再表示されます。
送信するにはセミコロンまたは\g
を、問い合わせバッファをクリアしてキャンセルするには\r
を入力してください。
バッファ全体を1行として扱うので、特にメタコマンドに影響があります。
バッファ内でメタコマンドより後にある部分はすべて、それが複数行にまたがっていたとしても、メタコマンドの引数として解釈されます。
(従って、この方法ではメタコマンドを使用するスクリプトを作成できません。
その目的の場合は、\i
を使ってください。)
行番号(line_number)が指定された場合、psqlはファイルまたは問い合わせバッファ内の指定行にカーソルを位置づけます。 すべてが数字の引数が1つだけ指定された場合、psqlはそれをファイル名ではなく行番号であるとみなすことに注意してください。
使用するエディタを設定、カスタマイズする方法については、下記のEnvironmentを参照してください。
\echo text
[ ... ]
評価された引数を空白で区切り、標準出力に出力し、改行します。 スクリプトが出力するところどころに情報を記載する場合に有用です。 使用例を次に示します。
=> \echo `date`
Tue Oct 26 21:40:57 CEST 1999
最初の引数が引用符で囲まれていない-n
である場合、最後の改行は出力されません(し、最初の引数も出力されません)。
\o
コマンドを使用して問い合わせの出力先を変更した場合、このコマンドではなく、\qecho
を使用した方が良いかもしれません。
\warn
コマンドも参照してください。
\ef [ function_description
[ line_number
] ]
このコマンドは指定された関数やプロシージャの定義をCREATE OR REPLACE FUNCTION
やCREATE OR REPLACE PROCEDURE
コマンド構文で取り出し、編集します。
編集は\edit
と同様の方法で行われます。
保存しないでエディタを終了すると、その文は捨てられます。
保存してエディタを終了すると、更新されたコマンドはセミコロンを付けていれば即座に実行されます。
そうでなければ再表示されます。送信するにはセミコロンあるいは\g
を、キャンセルするには\r
を入力してください。
対象の関数は名前だけ、または、たとえばfoo(integer, text)
のように名前と引数で指定することができます。
同じ名前の関数が複数存在する場合、引数の型を指定しなければなりません。
関数が指定されなかった場合、空のCREATE FUNCTION
のテンプレートが編集用に表示されます。
行番号が指定された場合、psqlは関数本体における指定行にカーソルを移動します。 (関数本体は通常、ファイルの先頭から始まらないことに注意してください。)
他のほとんどのメタコマンドと異なり、行の残り部分はすべて\ef
の引数であると常に解釈され、引数内の変数の置換も逆引用符の展開も行われません。
使用するエディタを設定、カスタマイズする方法については下記のEnvironmentを参照してください。
\encoding [ encoding
]
クライアント側の文字セット符号化方式を設定します。 引数を指定しない場合、このコマンドは現在の符号化方式を表示します。
\errverbose
最も最近のサーバのエラーメッセージを最大の冗長さ、つまりVERBOSITY
がverbose
に、そしてSHOW_CONTEXT
がalways
に設定されているかのようにして、繰り返します。
\ev [ view_name
[ line_number
] ]
このコマンドは、指定したビューの定義をCREATE OR REPLACE VIEW
コマンドの形式で取得して、編集します。
編集は\edit
の場合と同じ方法で行われます。
保存しないでエディタを終了すると、その文は捨てられます。
保存してエディタを終了すると、更新されたコマンドはセミコロンを付けていれば即座に実行されます。
そうでなければ再表示されます。送信するにはセミコロンあるいは\g
を、キャンセルするには\r
を入力してください。
ビューを指定しなかった場合は、空のCREATE VIEW
テンプレートが編集用に提供されます。
行番号を指定した場合、psqlはカーソルをビュー定義の指定した行に位置づけます。
他のほとんどのメタコマンドと異なり、行の残り部分はすべて\ev
の引数であると常に解釈され、引数内の変数の置換も逆引用符の展開も行われません。
\f [ string
]
位置揃えされていない問い合わせの出力用の、フィールドの区切り文字を設定します。
デフォルトは、縦棒(|
)です。
これは\pset fieldsep
と同じです。
\g [ (option
=value
[...]) ] [ filename
]
\g [ (option
=value
[...]) ] [ |command
]
現在の問い合わせ入力バッファをサーバに送って実行します。
\g
の後に括弧が現れる場合は、括弧はoption
=
value
書式オプション句の空白で区切られた一覧を囲んでいます。書式オプション句は\pset
option
value
コマンドと同じように解釈されますが、この問い合わせの間でのみ有効です。
この一覧の中では、空白は=
の周りでは許されていませんが、オプション句の間には必要です。
=
value
が省略された場合、指名されたoption
は、明示されたvalue
がない\pset
option
と同じように変更されます。
filename
や|
command
引数を指定すると、問い合わせ出力を通常通りに表示する代わりに、指定したファイルに書き込んだり、指定のシェルコマンドにパイプで渡します。
問い合わせが成功しゼロ以上のタプルが返る場合にのみファイルまたはコマンドに書き出されます。
問い合わせが失敗する場合やデータを返さないSQLコマンドでは書き出されません。
現在の問い合わせバッファが空の場合、最も最近に送信された問い合わせが再実行されます。
その点を除けば、\g
だけを指定した場合は、セミコロンと実質的に同じです。
\g
に引数を指定した場合は、\o
コマンドの「一度限りの」代替手段として使用でき、さらに通常は\pset
で設定される出力書式のオプションの一度限りの調整もできます。
最後の引数が|
で始まっている場合、行の残りの部分はすべて実行するcommand
であると解釈され、その中では変数の置換も逆引用符の展開も行なわれません。
行の残り部分は、単にあるがままにシェルに渡されます。
\gdesc
現在の問い合わせバッファの結果の説明(列名とデータ型)を表示します。 問い合わせは実際には実行されませんが、ある種の構文エラーが含まれている場合、そのエラーは通常の方法で報告されます。
現在の問い合わせバッファが空の場合、直近に送った問い合わせの説明が代わりに出力されます。
\gexec
現在の問い合わせバッファをサーバに送信し、問い合わせの出力(あれば)の各行の各列をSQL文として実行します。
例えば、my_table
の各列にインデックスを作成するには次のようにします。
=>SELECT format('create index on my_table(%I)', attname)
->FROM pg_attribute
->WHERE attrelid = 'my_table'::regclass AND attnum > 0
->ORDER BY attnum
->\gexec
CREATE INDEX CREATE INDEX CREATE INDEX CREATE INDEX
生成された問い合わせは行が返された順番で実行され、また2つ以上の列が返された場合は、各行の中で左から右に実行されます。
NULLのフィールドは無視されます。
生成された問い合わせは、そのままサーバに送信されて処理されるため、psqlのメタコマンドとすることはできず、またpsqlの変数の参照を含むこともできません。
個別の問い合わせで失敗した場合、残りの問い合わせの実行はON_ERROR_STOP
が設定されているのでなければ継続します。
個々の問い合わせの実行はECHO
の処理に従います。
(\gexec
を使う場合、ECHO
をall
あるいはqueries
に設定することが推奨されることが多いでしょう。)
問い合わせのログ出力、シングルステップモード、時間表示(timing)、およびその他の問い合わせ実行に関する機能は、生成された各問い合わせにも適用されます。
現在の問い合わせバッファが空の場合、最も最近に送信された問い合わせが再実行されます。
\gset [ prefix
]
現在の問い合わせバッファをサーバに送信し、問い合わせの出力をpsql変数(下記のVariables参照)に格納します。 実行される問い合わせは正確に1行を返さなければなりません。 行の各列は、列と同じ名前を持つ別々の変数に格納されます。 例えば、以下のようになります。
=>SELECT 'hello' AS var1, 10 AS var2
->\gset
=>\echo :var1 :var2
hello 10
prefix
を指定した場合、使用する変数の名前を作成する時にその文字列が問い合わせの列名の前に付けられ、次のようになります。
=>SELECT 'hello' AS var1, 10 AS var2
->\gset result_
=>\echo :result_var1 :result_var2
hello 10
列の結果がNULLである場合、対応する変数は設定されず未設定状態となります。
問い合わせが失敗、または1行を返さない場合、変数は変更されません。
現在の問い合わせバッファが空の場合、最も最近に送信された問い合わせが再実行されます。
\gx [ (option
=value
[...]) ] [ filename
]
\gx [ (option
=value
[...]) ] [ |command
]
\gx
は、\pset
オプションの一覧にexpanded=on
が含まれているかのように、この問い合わせに対して拡張出力モードを使用することを除いて\g
と同じです。
\x
も参照してください。
\h
または\help
[ command
]
指定したSQLコマンドの構文に関するヘルプを表示します。
command
が指定されていない場合は、psqlは構文ヘルプが存在する全てのコマンドの一覧を表示します。
command
をアスタリスク(*
)にすると、全てのSQLコマンドの構文ヘルプが表示されます。
他のほとんどのメタコマンドと異なり、行の残り部分はすべて\help
の引数であると常に解釈され、引数内の変数の置換も逆引用符の展開も行われません。
入力を簡単にするため、複数の単語からなるコマンドを引用符で囲む必要はありません。
\help alter table
と入力するだけで十分です。
\H
または\html
HTML問い合わせ出力形式を有効にします。
HTML形式が有効になっている場合は、デフォルトの位置揃えされたテキスト形式に戻します。
このコマンドは互換性と簡便性のために存在します。
他の出力オプションについては、\pset
を参照してください。
\i
または\include
filename
filename
ファイルから入力を読み取り、キーボードから入力された場合と同じように実行します。
filename
が-
(ハイフン)の場合、EOFを示すもの、または\q
メタコマンドが読まれるまで標準入力から読み込みます。
これは対話的な入力とファイルからの入力を混在させるために使うことができます。
Readlineと同じ挙動は、それが最も外部のレベルで動作している場合にのみ利用されることに注意してください。
読み取られた行を画面に表示させる場合は、ECHO
変数をall
に設定する必要があります。
\if
expression
\elif
expression
\else
\endif
このコマンド群は入れ子にすることができる条件ブロックを実現します。
条件ブロックは\if
で始まり、\endif
で終わらなければなりません。
その間には\elif
句をいくつでも置くことができ、さらにその後に\else
句を1つだけ置くことができます。
条件ブロックを構成するコマンドの間には、通常の問い合わせや他の種類のバックスラッシュコマンドを置くことができます(通常は置きます)。
\if
コマンドおよび\elif
コマンドはその引数を読み取り、それを論理式であるとして評価します。
式の結果がtrue
であれば、通常通りに処理が続きますが、そうでないときは、対応する\elif
、\else
または\endif
に到達するまで行をスキップします。
ひとたび\if
または\elif
の評価が真になったら、同じブロック内のそれより後にある\elif
コマンドの引数は評価されず、偽であるとして扱われます。
\else
より後にある行は、それより前の対応する\if
と\elif
が一つも真にならなかった時にのみ実行されます。
\if
コマンドおよび\elif
コマンドのexpression
引数は、他のバックスラッシュコマンドの引数と同様、変数置換と逆引用符展開の対象となります。
その後で、on/offのオプション変数の値のように評価されます。
従って有効な値は、true
、false
、1
、0
、on
、off
、yes
、no
のいずれかに曖昧性なしに、大文字小文字を区別せずにマッチするものです。
例えば、t
、T
、tR
はすべてtrue
であるとみなされます。
真にも偽にも適切に評価できない式には警告を発行し、偽として扱います。
スキップされる行も、問い合わせとバックスラッシュコマンドを特定するため、通常通り解析されますが、問い合わせはサーバには送信されず、条件コマンド(\if
、\elif
、\else
、\endif
)以外のバックスラッシュコマンドは無視されます。
条件コマンドは入れ子の有効性の確認のためだけに検査されます。
スキップされる行の変数参照は展開されず、逆引用符の展開も実行されません。
条件ブロック内のすべてのバックスラッシュコマンドは同じファイル内になければなりません。
ファイル内のすべての\if
ブロックが閉じられるより前に、メインの入力ファイルまたは\include
されたファイルの終端に到達した場合、psqlはエラーを発生させます。
例を示します。
-- データベース内に2つのレコードが存在するかどうかを検査し、 -- その結果を2つのpsql変数に格納する。 SELECT EXISTS(SELECT 1 FROM customer WHERE customer_id = 123) as is_customer, EXISTS(SELECT 1 FROM employee WHERE employee_id = 456) as is_employee \gset \if :is_customer SELECT * FROM customer WHERE customer_id = 123; \elif :is_employee \echo 'is not a customer but is an employee' SELECT * FROM employee WHERE employee_id = 456; \else \if yes \echo 'not a customer or employee' \else \echo 'this will never print' \endif \endif
\ir
または\include_relative
filename
\ir
コマンドは\i
と似ていますが、相対ファイル名の解決方法が異なります。
対話モードで実行している場合は2つのコマンドの動作は同一です。
しかし、スクリプトから呼び出す場合、\ir
は、現在の作業ディレクトリではなく、そのスクリプトの格納ディレクトリから見た相対ファイル名として解釈します。
\l[+]
または \list[+] [ pattern
]
サーバ内のデータベースについて、その名前、所有者、文字セット符号化方式、アクセス権限を一覧表示します。
pattern
を指定すると、パターンにマッチする名前を持つデータベースのみを表示します。
コマンド名に+
を付けると、データベースのサイズ、デフォルトのテーブル空間、説明も表示します。
(サイズ情報は現在のユーザが接続可能なデータベースでのみ表示されます。)
\lo_export loid
filename
データベースからOIDがloid
であるラージオブジェクトを読み取り、filename
に書き出します。
これはlo_export
サーバ関数とは微妙に異なります。
lo_export
関数は、データベースサーバを実行しているユーザ権限で、サーバ上のファイルシステムに対して動作します。
ラージオブジェクトのOIDを確認するには、\lo_list
を使用してください。
\lo_import filename
[ comment
]
ファイルを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
は、この点で微妙に異なっています。
\lo_list
現在データベースに保存されている全てのPostgreSQLラージオブジェクトの一覧を、そのオブジェクトに付けられたコメントと一緒に表示します。
\lo_unlink loid
OIDがloid
であるラージオブジェクトをデータベースから削除します。
ラージオブジェクトのOIDを確認するには、\lo_list
を使用してください。
\o
または\out [ filename
]
\o
または\out [ |command
]
以降の問い合わせの結果を、filename
で指定されたファイルに保存するか、またはシェルコマンドcommand
にパイプで渡すようにします。
引数がない場合、問い合わせの出力はリセットされて標準出力になります。
引数が|
で始まっている場合、行の残りの部分はすべて実行するcommand
であると解釈され、その中では変数の置換も逆引用符の展開も行われません。
行の残り部分は、単にあるがままにシェルに渡されます。
「問い合わせの結果」には、全てのテーブル、コマンドの応答、データベースサーバからの注意メッセージだけでなく、データベースに問い合わせを行う(\d
のような)各種バックスラッシュコマンドの出力が含まれます。ただし、エラーメッセージは含まれません。
問い合わせの結果の間にテキストを挿入するには、\qecho
を使用してください。
\p
または\print
現在の問い合わせバッファを標準出力に書き出します。 現在の問い合わせバッファが空の場合、最も最近に実行された問い合わせが書き出されます。
\password [ username
]
指定したユーザ(デフォルトは現在のユーザ)のパスワードを変更します。
このコマンドは、新しいパスワードを促し、暗号化して、それをALTER ROLE
コマンドとしてサーバに送信します。
これによりコマンド履歴やサーバログなどどこにも新しいパスワードが平文では残りません。
\prompt [ text
] name
変数name
に代入するテキストを入力するようにユーザを促します。
プロンプトtext
をオプションで指定することができます。
(複数の単語をプロンプトで使用する場合はそのテキストを単一引用符でくくってください。)
デフォルトでは\prompt
は入出力に端末を使用します。
しかし、-f
コマンドラインスイッチが使用されている場合、\prompt
は標準入力、標準出力を使用します。
\pset [ option
[ value
] ]
このコマンドは問い合わせ結果のテーブル出力に影響するオプションを設定します。
option
には、どのオプションを設定するのかを記述します。
value
の意味は選択したオプションにより変わります。
以下のオプション別の説明の通り、オプションの中にはvalue
を省略することでトグルや設定解除を行うものがあります。
こうした動作の記載がなければ、value
を省略すると、単に現在の設定値が表示されることになります。
何も引数をつけずに\pset
を実行すると、すべての表示オプションの現在の状態を表示します。
以下は、表示の調整に関するオプションです。
border
value
は数値でなければなりません。
基本的には、この数字が大きくなればなるほど、表示するテーブルが持つ境界線は増えますが、詳細はそれぞれの出力形式に依存しています。
HTML書式では、この値は直接border=...
属性に反映されます。
他のほとんどの書式の場合は、0(境界線なし)、1(内側の境界線)、2(テーブル枠)という3つの数値のみ意味を持ち、2より大きな値はborder = 2
と同じとして扱われます。
latex
およびlatex-longtable
書式では、さらにデータ行の間に境界線を付ける、3という値をとることができます。
columns
wrapped
書式の対象幅を設定し、そして、ページャを必要とする、拡張自動モードにおける縦表示への切替えに十分な幅で出力するかどうかを決定する幅制限を設定します。
ゼロ(デフォルト)では、環境変数COLUMNS
、もしCOLUMNS
が設定されていなければ、検出したスクリーンの幅、により対象幅が制御されます。
さらにcolumns
がゼロの場合、wrapped
書式はスクリーン出力にのみ影響を与えることになります。
columns
が非ゼロの場合は、ファイルやパイプへの出力も同様に折り返されます。
csv_fieldsep
CSV出力形式で使われるフィールド区切り文字を指定します。 区切り文字がフィールドの値中に現れる場合には、標準のCSV規則に従ってそのフィールドは二重引用符内に出力されます。 デフォルトはコンマです。
expanded
(またはx
)
value
を指定する場合は、拡張(expanded)モードを有効または無効にするon
またはoff
、あるいはauto
のいずれかでなければなりません。
value
を省略した場合、このコマンドは通常モードと拡張モードの設定をトグルします。
拡張モードを有効にした場合、問い合わせ結果は左に列名、右にデータという2つの列で出力されます。
このモードは、データが通常の「水平(horizontal)」モードによる画面表示に適していない場合に有用です。
自動(auto)設定の場合、問い合わせの出力が2列以上でかつ画面幅より広ければ拡張モードが使用され、そうでなければ通常モードが使用されます。
自動設定は位置揃え書式または折り返し書式でのみ有効です。
この他の書式では、常に拡張モードが無効の場合と同様に動作します。
fieldsep
位置揃えなしの出力書式で使用されるフィールド区切り文字を指定します。
これにより、例えばタブ区切りといった他プログラムに要求される形式を作成することができます。
タブをフィールド区切り文字として使用するには、\pset fieldsep '\t'
と入力します。
デフォルトのフィールド区切り文字は'|'
(縦棒)です。
fieldsep_zero
位置揃えなしの出力書式で使用されるフィールド区切り文字をゼロバイトに指定します。
footer
value
を指定する場合、それぞれテーブルフッタの表示((
数)を有効にするn
rows)on
または無効にするoff
のいずれかでなければなりません。
value
を省略した場合、このコマンドはフッタの表示、非表示をトグルします。
format
出力形式をaligned
、asciidoc
、csv
、html
、latex
、latex-longtable
、troff-ms
、unaligned
、wrapped
のいずれかに設定します。
一意に判別できる範囲で省略が可能です。
aligned
書式は、標準的で人間が読みやすいように、美しく整形されたテキスト出力です。
これがデフォルトです。
unaligned
書式は、表示行の1行に1つの行の全列を、現在有効なフィールド区切り文字で区切って書き出します。
これは他のプログラムに読み込ませることを目的とした出力、例えばタブ区切りやカンマ区切り書式を生成する場合に有用です。
しかし、列の値にフィールド区切り文字が現れても、特別扱いはしません。ですので、そのような目的には、CSV書式の方がより相応しいでしょう。
csv
書式は
RFC 4180で記述された引用規則を適用して、列の値をコンマで区切って書きます。
この出力はサーバのCOPY
コマンドのCSV書式と互換性があります。
列名が書かれたヘッダ行は、tuples_only
がon
でなければ生成されます。
タイトルとフッタは出力されません。
各行はシステム依存の改行文字で終わります。改行文字は、Unix系のシステムでは典型的には単独の改行(\n
)であり、Microsoft Windowsでは復帰と改行の並び(\r\n
)です。
コンマ以外のフィールド区切り文字は\pset csv_fieldsep
で選べます。
wrapped
書式はaligned
と似ていますが、幅の広いデータ値を複数行に折り返して対象の列幅に合うように出力します。
対象の幅はcolumns
オプションの項に記述されているように決定されます。
psqlは列ヘッダタイトルを折り返さないことに注意して下さい。
このためwrapped
書式は列ヘッダに必要とする幅全体が対象より長い場合、aligned
と動作が同じになります。
asciidoc
、html
、latex
、latex-longtable
およびtroff-ms
書式は対応するマークアップ言語を使用する文書内に含めることを目的とした表を出力します。
出力自体は完全な文書ではありません。
HTMLでは必要性がないかもしれませんが、LaTeXでは完全な文書ラッパを持たせなければなりません。
latex
書式はLaTeXのtabular
環境を使います。
latex-longtable
書式ではLaTeXのlongtable
およびbooktabs
パッケージも必要です。
linestyle
境界線の表示形式をascii
、old-ascii
またはunicode
のいずれかに設定します。
一意になれば省略形が許されます。(つまり一文字で十分であることを意味します。)
デフォルトの設定はascii
です。
このオプションはaligned
およびwrapped
出力書式のみで有効です。
ascii
形式は通常のASCIIを使用します。
データ内の改行は右側余白に+
を使用して表します。
wrapped
書式で、改行文字のない行が2行にまたがるときは、先頭行の右側余白にドット(.
)を表示し、次の行の左側余白にもドットを表示します。
old-ascii
形式は通常のASCII文字を使用して、PostgreSQL 8.4以前で使用されていた方法で整形します。
データ内の改行は列区切りの左側に:
記号を使用して表します。
データを改行文字なしに折り返す際には、列区切りの左側に;
記号を使用して表します。
unicode
形式はUnicode矩形描画文字を使用します。
データ内の改行は右側の余白に復帰記号を使用して表します。
データを改行文字なしに折り返す際には、省略記号を先頭行の右側余白に表示し、次の行の左側余白にも表示します。
border
設定がゼロより大きい場合、linestyle
オプションはまた、境界線を描画する文字も決定します。
通常のASCII文字はどのような場合でも動作しますが、Unicode文字が表示できる環境では、その方が見た目が良くなります。
null
null値の代わりに表示する文字列を設定します。
デフォルトでは何も表示しません。
そのため、よく空の文字列と間違うことがあります。
例えば\pset null '(null)'
とする人もいます。
numericlocale
value
を指定する場合、それぞれ10進数マーカの左に桁のくくりを分離するロケール固有の文字を表示するon
または表示しないoff
のいずれかでなければなりません。
value
を省略した場合、このコマンドは通常出力かロケール固有の数値出力かをトグルします。
pager
問い合わせおよびpsqlのヘルプを出力する際の、ページャプログラムの使用を制御します。
環境変数PSQL_PAGER
またはPAGER
が設定されている場合、出力は指定したプログラムにパイプで渡されます。
設定されていない場合は、プラットフォーム依存のデフォルト(more
など)が使用されます。
pager
オプションがoff
の場合、ページャプログラムは使用されません。
pager
オプションがon
の場合、ページャは適切な場合、つまり出力先が端末であり、その画面に収まらない場合に使用されます。
またpager
オプションはalways
に設定することもできます。
こうすると画面に収まるかどうかに関わらずすべての端末出力でページャが使用されます。
value
を指定しない\pset pager
はページャの使用をトグルします。
pager_min_lines
pager_min_lines
がページ高より大きな数に設定されている場合、少なくともこれに設定されている行数の出力がなければ、ページャプログラムを呼び出しません。
デフォルトの設定は0です。
recordsep
位置揃えなしの出力書式で使用されるレコード(行)の区切り文字を指定します。 デフォルトは改行文字です。
recordsep_zero
位置揃えなしの出力書式で使用されるレコードの区切り文字をゼロバイトに指定します。
tableattr
(または T
)
HTML出力書式では、これはtable
タグ内に記述する属性を指定します。
これを使用して、例えば、cellpadding
やbgcolor
を指定することができます。
border
属性は既に\pset border
によって処理されているので、このコマンドでborder
を指定する必要はないでしょう。
value
の指定がない場合、テーブル属性の設定は解除されます。
latex-longtable
書式では、これは
左揃えされたデータ型を含む各列の幅の比率を制御します。
空白文字で区切られた値のリスト、例えば'0.2 0.2 0.6'
として指定します。
指定がない出力列は最後に指定された値を使用します。
title
(または C
)
今後表示される全てのテーブル用にテーブルタイトルを設定します。
これは出力に説明のためのタグを付けたい場合に有用です。
value
がない場合、タイトルの設定が解除されます。
tuples_only
(または t
)
value
を指定する場合、それぞれタプルのみの表示を有効にする、on
または無効にするoff
のいずれかでなければなりません。
value
を省略した場合、このコマンドはタプルのみの表示と通常表示をトグルします。
通常表示では列のヘッダ、タイトル、各種フッタなどのその他の情報が追加されます。
タプルのみのモードでは、テーブルの実データのみが表示されます。
unicode_border_linestyle
unicode
の線の形式の境界の形式をsingle
またはdouble
のどちらかに設定します。
unicode_column_linestyle
unicode
の線の形式の列の形式をsingle
またはdouble
のどちらかに設定します。
unicode_header_linestyle
unicode
の線の形式のヘッダの形式をsingle
またはdouble
のどちらかに設定します。
これらの異なる書式がどのように見えるかを示した実例が、下記のExamplesにあります。
\pset
には各種のショートカットコマンドがあります。
\a
、\C
、\f
、\H
、\t
、\T
、\x
を参照してください。
\q
または\quit
psqlプログラムを終了します。 スクリプトファイルでは、そのスクリプトの実行のみが終了します。
\qecho text
[ ... ]
このコマンドは、\echo
と同じです。
ただし、出力が\o
により設定された問い合わせ出力チャネルに書き出される点が異なります。
\r
または\reset
問い合わせバッファをリセット(クリア)します。
\s [ filename
]
psqlのコマンドラインの履歴をfilename
に出力します。
filename
が省略された場合、履歴は標準出力に書き出されます(適切であればページャを使います)。
このコマンドは、psqlがReadlineサポートなしの状態でビルドされた場合は利用できません。
\set [ name
[ value
[ ... ] ] ]
psqlの変数name
をvalue
、または複数のvalueが与えられた場合はそれらを連結したものに設定します。
第一引数しか指定されない場合は、変数に空文字列の値が設定されます。
変数を未設定とするには、\unset
コマンドを使用してください。
引数をまったく取らない\set
は、現在設定されているpsql変数すべての名前と値を表示します。
変数名には、文字、数字、アンダースコアを使用することができます。 詳細は、後述のVariablesを参照してください。 変数名は大文字小文字を区別します。
psqlの動作を制御する、あるいは接続状態を表す値に自動的に設定される、という点で特別な変数がいくつかあります。 これらの変数については、以下のVariablesに記載されています。
このコマンドはSQLのSET
コマンドとは関係ありません。
\setenv name
[ value
]
環境変数name
をvalue
に設定します。
value
が与えられない場合は、その環境変数を未設定状態にします。
以下に例を示します。
testdb=>\setenv PAGER less
testdb=>\setenv LESS -imx4F
\sf[+] function_description
このコマンドは、CREATE OR REPLACE FUNCTION
コマンドやCREATE OR REPLACE PROCEDURE
コマンドの形式で、指定された関数やプロシージャの定義を抽出し表示します。
この定義は、\o
で設定された現在の問い合わせ出力チャネルに出力されます。
対象の関数は、名前だけまたは、例えばfoo(integer, text)
のように名前と引数で指定することができます。
同じ名前の関数が複数存在する場合は、引数の型を指定しなければなりません。
コマンド名に+
を付けると、出力行に関数本体の先頭行を1行目と数える行番号が付けられます。
他のほとんどのメタコマンドと異なり、行の残り部分はすべて\sf
の引数であると常に解釈され、引数内の変数の置換も逆引用符の展開も行われません。
\sv[+] view_name
このコマンドは、指定したビューの定義をCREATE OR REPLACE VIEW
コマンドの形式で取得して表示します。
定義は現在の問い合わせの出力チャネルに表示されます。
これは\o
で設定できます。
コマンド名の後に+
が付加された場合は、出力行に1から番号が付けられます。
他のほとんどのメタコマンドと異なり、行の残り部分はすべて\sv
の引数であると常に解釈され、引数内の変数の置換も逆引用符の展開も行われません。
\t
出力列名ヘッダと行数フッタの表示を切り替えます。
このコマンドは\pset tuples_only
と同じで、簡便性のために用意されています。
\T table_options
HTML出力書式におけるtable
タグ内部に記述する属性を指定します。
このコマンドは\pset tableattr
と同じ効力を持ちます。
table_options
\timing [ on
| off
]
パラメータがある場合、各SQL文にかかる時間の表示の有無をonまたはoffに設定します。 パラメータがない場合、表示をonとoffの間で切り替えます。 表示はミリセカンド単位です。 1秒より長い時間は 分:秒 の形式で表示され、必要なら時間と日のフィールドが追加されます。
\unset name
psql変数name
を未設定状態にします(削除します)。
psqlの動作を制御するほとんどの変数は未設定にすることができず、\unset
はそれをデフォルト値に設定するものとして解釈されます。
以下のVariablesを参照してください。
\w
または\write
filename
\w
または\write
|
command
現在の問い合わせバッファを、filename
ファイルに書き出すか、もしくは、シェルコマンドcommand
にパイプで渡します。
現在の問い合わせバッファが空の場合、最も最近に実行された問い合わせを書き出します。
引数が|
で始まっている場合、行の残りの部分はすべて実行するcommand
であると解釈され、その中では変数の置換も逆引用符の展開も行われません。
行の残り部分は、単にあるがままにシェルに渡されます。
\warn text
[ ... ]
このコマンドは、出力が標準出力ではなくpsqlの標準エラーチャネルに書かれることを除いて\echo
と同一です。
\watch [ seconds
]
中断するか問い合わせが失敗するまで、現在の問い合わせバッファを繰り返し(\g
と同じように)実行します。
実行の間に指定秒数(デフォルトは2)の休止が入ります。
各問い合わせの結果には、\pset title
の文字列(あれば)、問い合わせ開始時の時刻、および遅延間隔を含むヘッダとともに表示されます。
現在の問い合わせバッファが空の場合、最も最近に送信された問い合わせが再実行されます。
\x [ on
| off
| auto
]
拡張テーブル形式モードを設定またはトグルします。
従って、このコマンドは\pset expanded
と同じ効力を持ちます。
\z [ pattern
]
テーブル、ビュー、シーケンスを、関連付けられているアクセス権限とともに一覧表示します。
pattern
を指定すると、パターンに名前がマッチするテーブル、ビュー、シーケンスのみが表示されます。
これは\dp
(「権限の表示(display privileges)」)の別名です。
\! [ command
]
引数がないときはサブシェルに制御を渡し、サブシェルが終了したらpsqlが再開されます。
引数があるときは、シェルコマンドcommand
を実行します。
他のほとんどのメタコマンドと異なり、行の残り部分はすべて\!
の引数であると常に解釈され、引数内の変数の置換も逆引用符の展開も行われません。
行の残りの部分は単にあるがままにシェルに渡されます。
\? [ topic
]
ヘルプ情報を表示します。
オプションのtopic
パラメータ(デフォルトはcommands
)はpsqlのどの部分を説明するかを選択します。
commands
はpsqlのバックスラッシュコマンドについて、options
はpsqlに渡すことができるコマンド行オプションについて、variables
はpsqlの設定変数についてのヘルプを表示します。
\;
バックスラッシュ-セミコロンは前述のコマンドと同じ位置づけのメタコマンドではありません。そうではなく単にセミコロンを追加処理無しで問い合わせバッファに加えます。
通常、psqlは、コマンド終了のセミコロンに到達したら、更なる入力が現在行に残っていても、SQLコマンドをすぐにサーバに送ります。 よって、例えば、
select 1; select 2; select 3;
上記は3つのSQLコマンドが個々にサーバに送られることになり、各々の結果は続く次コマンドの前に表示されます。
しかしながら、\;
として挿入されたセミコロンはコマンド処理を誘発せず、その後、そのさらに後のコマンドは事実上結合されて、サーバに一つのリクエストとして送られます。
したがって、例えば、
select 1\; select 2\; select 3;
上記は、バックスラッシュの無いセミコロンに達したときに、3つのSQLコマンドがサーバに単一リクエストでサーバに送られます。
文字列にそれを複数トランザクションに分けるための明示的なBEGIN
/COMMIT
が含まれているのでない限り、サーバはこのようなリクエストを単一トランザクションとして実行します。
(複数問い合わせの文字列をどのようにサーバが処理するかについて、詳しくは53.2.2.1を参照してください。)
psqlは各リクエストに対して受け取った最後の問い合わせ結果だけを出力します。
この例では、3つ全てのSELECT
が実際に実行されますが、psqlは3
だけ出力します。
各種\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
を含むテーブルを全て表示します。
ドットがない場合、パターンは現行のスキーマ検索パス内で可視的なオブジェクトのみにマッチします。
ここでも、二重引用符で括られた文字列内のドットは特別な意味を失い、文字そのものにマッチすることになります。
ドット(.
)を2つ含むリレーションパターンは、データベース名にスキーマ名が続き、オブジェクト名が続くパターンとして解釈されます。
データベース名の部分はパターンとしては扱われず、現在接続しているデータベースの名前に一致しなければなりません。さもないとエラーが発生します。
ドット(.
)を含むスキーマパターンは、データベース名にスキーマ名が続くパターンとして解釈されます。
例えば、\dn mydb.*foo*
は、スキーマ名がfoo
を含むスキーマを全て表示します。
データベース名の部分はパターンとしては扱われず、現在接続しているデータベースの名前に一致しなければなりません。さもないとエラーが発生します。
上級者は文字クラス(例えば任意の数にマッチする[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 Interpolationで詳しく説明します。
第二引数なしで\set
を呼び出すと、その変数には空文字列の値が設定されます。
変数を未設定状態にする(つまり削除する)ためには、\unset
コマンドを使用してください。
すべての変数の値を表示するためには、引数なしで\set
を呼び出してください。
\set
の引数は他のコマンドと同じ置換規則に従います。
このため、\set :foo 'something'
のような参照を作成して、Perlにおける「ソフトリンク」やPHPにおける「可変変数」に当たるものを得られます。
しかし、残念ながら(あるいは幸運にも)、このような構成をうまく使用する方法はありません。
一方、\set bar :foo
のようにして変数をコピーするのは、完全に有効な方法です。
これらの変数の多くは、psqlに特別扱いされています。 これらは、変数の値を変更することにより、実行時に変更可能なオプションの設定を表現します。 またpsqlの変更可能な状態を表現しているものもあります。 慣習上、特別視される変数の名前はすべてASCII大文字(と数字とアンダースコア)からなります。 将来的な互換性を最大限考慮するために、自分で作成した変数にはこのような変数名を使用しないでください。
psqlの動作を制御する変数は、一般に未設定にしたり、無効な値に設定したりすることができません。
\unset
コマンドの実行は許されますが、変数をデフォルト値に設定するものとして解釈されます。
第2引数なしの\set
コマンドは、on
の値を受け付ける制御変数では変数をon
に設定するものとして解釈され、それ以外の場合は拒絶されます。
また、 on
とoff
の値を受け付ける制御変数では、true
やfalse
などそれ以外の論理値の共通で使われる綴りも受け付けます。
特別に扱われる変数を以下に示します。
AUTOCOMMIT
この変数の値がon
の場合(これがデフォルトです)、各SQLコマンドの実行が成功すると、自動的にコミットされます。
コミットを延期するには、BEGIN
もしくはSQLのSTART TRANSACTION
コマンドを入力する必要があります。
値がoff
もしくは未設定の場合、明示的にCOMMIT
もしくはEND
を発行するまで、SQLコマンドはコミットされません。
自動コミット無効モードでは、トランザクションブロック以外でコマンドが発行されると、そのコマンドを実行する前に、自動的にBEGIN
コマンドが発行されます(ただし、そのコマンド自体がBEGIN
コマンドやその他のトランザクション制御コマンドである場合、トランザクションブロック内で実行することができないコマンド(VACUUM
など)である場合は除きます)
自動コミット無効モードでは、ABORT
やROLLBACK
を発行して、明示的に失敗したトランザクションを放棄しなければなりません。
また、コミットせずにセッションを終了した場合は、作業が失われてしまうので注意してください。
PostgreSQLは、伝統的に自動コミット有効モードで動作していましたが、自動コミット無効モードの方がよりSQLの仕様に近いものです。
自動コミット無効モードは、システム全体に対するpsqlrc
ファイル、もしくは、個人用の~/.psqlrc
ファイルで設定すれば実現できます。
COMP_KEYWORD_CASE
SQLキーワードを補完する時に大文字小文字のどちらを使用するかを決定します。
lower
またはupper
が設定された場合、補完された単語はそれぞれ小文字または大文字になります。
preserve-lower
またはpreserve-upper
(デフォルト)が設定された場合、
補完された単語は入力済みの文字の大文字小文字を引き継ぎますが、何も入力されていない場合はそれぞれ小文字または大文字に補完されます。
DBNAME
現在接続しているデータベース名です。 この変数は(プログラム起動時も含め)データベースに接続する度に設定されますが、変更したり、未設定にすることもできます。
ECHO
all
に設定された場合、空でない全ての入力行は、標準出力に書き出されます。
(これは対話式に読み込まれる行には適用されません。)
この動作をプログラム起動時に設定するには、-a
スイッチを使用してください。
queries
に設定された場合、psqlは各問い合わせがサーバに送信されるときに表示します。
この動作を選択するオプションは-e
です。
errors
に設定された場合、失敗した問い合わせのみが標準エラー出力に出力されます。
この動作に対応するオプションは-b
です。
none
(デフォルトです)に設定された場合、どの問い合わせも表示されません。
ECHO_HIDDEN
この変数がon
に設定されている場合、バックスラッシュコマンドがデータベースに問い合わせを行う時、最初にその問い合わせが表示されます。
この機能は、PostgreSQL内部動作について調べたり、自作プログラム内で同様の関数機能を用意したりするのに役立つでしょう。
(この動作をプログラム起動時に選択するには-E
スイッチを使用してください)。
この変数をnoexec
という値に設定した場合、問い合わせは実際にサーバに送信、実行されずに、単に表示されるだけになります。
デフォルト値はoff
です。
ENCODING
現在のクライアント側の文字セット符号化方式です。
これは(プログラムの起動時を含め)データベースに接続する度に、また符号化方式を\encoding
で変更した時に設定されますが、変更したり、未設定にすることができます。
ERROR
最後のSQL問い合わせが失敗したならtrue
、成功したならfalse
。
SQLSTATE
も参照してください。
FETCH_COUNT
この変数が0より大きな整数値に設定されている場合、SELECT
問い合わせの結果は、指定した行数の集合として取り出され、表示されます。
デフォルトの動作では、表示する前にすべての結果が取り出されます。
したがって、結果セットの大きさに関係なくメモリの使用量が限定されます。
この機能を有効とする場合に100から1000までの値がよく使用されます。
この機能を使用する際には、既に一部の行が表示されている場合、問い合わせが失敗する可能性があることに注意してください。
任意の出力書式でこの機能を使用することができますが、デフォルトのaligned
書式は適していません。
FETCH_COUNT
行のグループそれぞれが別々に整形されてしまい、行のグループによって列幅が異なることになるためです。
他の出力書式は適切に動作します。
HIDE_TABLEAM
この変数がtrue
に設定されていれば、テーブルのアクセスメソッドの詳細は表示されません。
これは主にリグレッションテストで有用です。
HIDE_TOAST_COMPRESSION
この変数がtrue
に設定されていれば、列の圧縮法の詳細は表示されません。
これは主にリグレッションテストで有用です。
HISTCONTROL
この変数をignorespace
に設定した場合、空白文字から始まる行は履歴リストには入りません。
ignoredups
に設定した場合、直前の履歴と同じ行は履歴リストに入りません。
ignoreboth
に設定した場合は、上記の2つを組み合わせたものになります。
none
(デフォルトです)に設定した場合は、対話モードで読まれる全ての行が履歴リストに保存されます。
この機能はBashの機能を真似たものです。
HISTFILE
履歴を格納するために使用されるファイルの名前です。
未設定にすると、ファイル名は環境変数PSQL_HISTORY
から取得されます。
それも設定されていない場合、デフォルトは~/.psql_history
、またはWindowsでは%APPDATA%\postgresql\psql_history
です。
例えば、以下を
\set HISTFILE ~/.psql_history-:DBNAME
~/.psqlrc
内に指定すると、psqlはデータベースごとに別々の履歴を保持します。
この機能はBashの機能を真似たものです。
HISTSIZE
コマンド履歴に保存するコマンドの最大数(デフォルトは500)です。 負の値に設定すると、制限がなくなります。
この機能はBashの機能を真似たものです。
HOST
接続中のデータベースサーバホストです。 この変数は(プログラム起動時も含め)データベースに接続する度に設定されますが、変更したり、未設定にすることもできます。
IGNOREEOF
この変数を1以下に設定すると、対話式セッションにEOF文字(通常Control+D)が送信された時、psqlが終了します。 1より大きな数値を設定すると、対話的セッションを終了するには、指定された数だけ、続けてEOF文字を送信しなければなりません。 数値以外を設定した場合は、10と解釈されます。 デフォルトは0です。
この機能はBashの機能を真似たものです。
LASTOID
INSERT
や\lo_import
コマンドによって返された、最後に影響を受けたOIDの値です。
この変数は、次のSQLコマンドの結果が表示されるまでの間のみ保証されています。
バージョン12からPostgreSQLサーバはOIDシステム列をサポートしませんので、そのようなサーバを対象とした場合INSERT
の後は、LASTOIDは常に0です。
LAST_ERROR_MESSAGE
LAST_ERROR_SQLSTATE
現在のpsqlセッションの直近の失敗した問い合わせに対する主エラーメッセージと関連するSQLSTATEコード。あるいは、現在セッションでエラーが無い場合、空文字列と00000
。
ON_ERROR_ROLLBACK
on
に設定されている場合、トランザクションブロック内である文がエラーとなった時に、そのエラーは無視され、トランザクションは継続します。
interactive
に設定されている場合、対話式セッション内の場合にのみエラーは無視されます。スクリプトファイルを読み込んでいる場合は無視されません。
off
(デフォルトです)に設定されている場合、トランザクションブロック内の文がエラーになると、トランザクション全体をアボートします。
エラーロールバックのモードは、トランザクションブロック内で各コマンドの実行直前に暗黙的なSAVEPOINT
を行い、コマンドが失敗した時にこのセーブポイントにロールバックすることで実現されています。
ON_ERROR_STOP
デフォルトではエラーの後もコマンド処理は続行されます。
この変数がon
に設定されていると、代わりに即座に停止します。
対話モードではpsqlはコマンドプロンプトに戻ります。
これ以外ではpsqlは終了し、エラーコード1を返す致命的エラー条件と区別できるように、エラーコード3を返します。
どちらの場合でも、現在実行中のスクリプト(トップレベルのスクリプト、もしあれば関連性を持つ他のスクリプトすべて)は即座に終了します。
トップレベルのコマンド文字列が複数のSQLコマンドを含む場合、その時点のコマンドで処理は終了します。
PORT
接続中のデータベースサーバのポートです。 この変数は(プログラム起動時も含め)データベースに接続する度に設定されますが、変更することも未設定にすることもできます。
PROMPT1
PROMPT2
PROMPT3
これらの変数は、psqlが発行するプロンプトの見た目を指定します。 後述のPromptingを参照してください。
QUIET
この変数をon
に設定することはコマンドラインオプション-q
と同じ効力を持ちます。
対話式モードではあまり役立ちません。
ROW_COUNT
最後のSQL問い合わせにより、返された、あるいは、影響をうけた行数。あるいは、問い合わせが失敗したか行数が報告されていない場合、0。
SERVER_VERSION_NAME
SERVER_VERSION_NUM
文字列としてのサーバーのバージョン番号、例えば9.6.2
、10.1
、11beta1
など、および数値形式でのバージョン番号、例えば90602
、100001
などです。
これらは(プログラムの起動時を含め)データベースに接続する度に設定されますが、変更することも未設定にすることもできます。
SHOW_CONTEXT
この変数は値never
、errors
、あるいはalways
に設定することができ、CONTEXT
フィールドがサーバからのメッセージに表示されるかどうかを制御します。
デフォルトはerrors
です(CONTEXTはエラーメッセージ内では表示されますが、注意や警告メッセージでは表示されません)。
この設定はVERBOSITY
がterse
またはsqlstate
に設定されている場合は効果がありません。
(\errverbose
も参照してください。こちらは受け取ったばかりのエラーについて、冗長なメッセージが必要なときに使えます。)
SINGLELINE
この変数をon
に設定することはコマンドラインオプション-S
と同じ効力を持ちます。
SINGLESTEP
この変数をon
に設定することはコマンドラインオプション-s
と同じ効力を持ちます。
SQLSTATE
最後のSQL問い合わせの失敗に関するエラーコード(付録Aを参照)、あるいは、SQLが成功した場合には00000
。
USER
接続中のデータベースユーザです。 この変数は(プログラム起動時も含め)データベースに接続する度に設定されますが、変更することも未設定にすることもできます。
VERBOSITY
この変数をdefault
、verbose
、terse
、sqlstate
のいずれかに設定することで、エラー報告の冗長性を制御できます。
(\errverbose
も参照してください。こちらは受け取ったばかりのエラーについて、冗長なメッセージが必要なときに使えます。)
VERSION
VERSION_NAME
VERSION_NUM
これらの変数はプログラムの起動時にpsqlのバージョンを表すために設定され、それぞれ冗長な文字列、短い文字列(例:9.6.2
、10.1
、11beta1
)、数字(例:90602
、100001
)です。
これらは変更することも未設定にすることもできます。
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');
(my_file.txt
にNULバイトが含まれている場合、これはうまく動作しないことに注意してください。
psqlは変数値内に埋め込まれたNULバイトをサポートしません。)
コロン(:)もSQLコマンド内で正規に使用できますので、
指定した変数が現在設定されていない場合、差し替え時の見かけの置換(:name
、:'name'
、:"name"
)は行われません。
コロンをバックスラッシュでエスケープすれば、常に差し替えから保護することができます。
:{?
特別構文は、その変数が存在しているかどうかに応じてTRUEかFALSEを返します。従って、コロンがバックスラッシュでエスケープされていない限り、常に置き換えられます。
name
}
変数用のコロン構文は、ECPGのような組み込みの問い合わせ言語用の標準SQLとして規定されています。 配列の一部の切り出し、および型キャスト用のコロン構文はPostgreSQLの拡張であり、標準での使用方法と競合することがあります。 SQLリテラルまたは識別子として変数の値をエスケープさせる引用符付きコロン構文はpsqlの拡張です。
psqlが発行するプロンプトは好みに応じてカスタマイズできます。
PROMPT1
、PROMPT2
、PROMPT3
という3つの変数はプロンプトの表示内容を示す文字列や特別なエスケープシーケンスを持ちます。
プロンプト1はpsqlが新しいコマンドを受け付ける際に発行される通常のプロンプトです。
プロンプト2は、例えばコマンドがセミコロンで終わっていない、または、引用符が閉じていないなど、コマンドの入力中にさらなる入力が期待される際に発行されます。
プロンプト3はSQLのCOPY FROM STDIN
コマンドを実行中で、端末上で行の値の入力が必要な際に発行されます。
選択されたプロンプト変数の値はそのまま文字として表示されます。
ただし、パーセント(%
)が含まれる場合は例外です。
この場合は、次の文字に従って、特定のテキストに置換されます。
置換対象として定義されているのは次のものです。
%M
データベースサーバの(ドメイン名付きの)完全なホスト名です。その接続がUnixドメインソケットの場合は[local]
となります。
ただし、Unixドメインソケットがコンパイル時に設定したデフォルトの場所に存在しない場合は、[local:
となります。
/dir/name
]
%m
最初のドット以降を省略したデータベースサーバのホスト名です。その接続がUnixドメインソケットの場合は[local]
となります。
%>
データベースサーバが監視するポート番号です。
%n
データベースセッションユーザの名前です
(この値の展開結果は、SET SESSION AUTHORIZATION
コマンドの実行によってデータベースセッション中に変わることがあります)。
%/
接続中のデータベース名です。
%~
デフォルトデータベースの場合に~
(チルダ)が出力される点を除いて、%/
と同じです。
%#
セッションユーザがデータベーススーパーユーザである場合は#
、それ以外の場合は>
となります
(この値の展開結果は、SET SESSION AUTHORIZATION
コマンドの実行によってデータベースセッション中に変わることがあります)。
%p
現在接続しているバックエンドのプロセスIDです。
%R
プロンプト1の場合、通常は=
ですが、条件ブロックの使われない部分では@
、シングル行モードでは^
、また、データベースとの接続が切れたセッションでは!
になります(\connect
が失敗した場合に発生します)。
プロンプト2の場合、%R
は、なぜpsqlがさらなる入力を要求しているかによって決まる文字に置き換えられます。
これは、単にコマンドがまだ終了していない場合は-
ですが、/* ... */
のコメントがまだ終了していない場合は*
、引用符付きの文字列が終了していない場合は単一引用符、引用符付きの識別子が終了していない場合は二重引用符、ドル引用文字列が終了していない場合はドル記号、そして閉じられていない左括弧がある場合は(
となります。
プロンプト3の場合、%R
に対しては何も表示されません。
%x
トランザクションの状態です。
トランザクションブロックの外にいる場合は空文字列に、トランザクションブロックの中にいる場合は*
に、失敗したトランザクションブロックの中にいる場合は!
に、(接続されていないなど)トランザクションの状態が不定の場合は?
になります。
%l
現在の文の内部での行番号で、1
から始まります。
%
digits
指定された8進の数値コードの文字に置換されます。
%:
name
:
psqlの変数name
の値です。
詳細は上記のVariablesを参照してください。
%`
command
`
通常の「逆引用符」による置き換えと同様で、command
の出力です。
%[
... %]
プロンプトには端末制御文字を含めることができます。
具体的には、色、背景、プロンプトテキストの様式の変更、端末ウィンドウのタイトルの変更などが指定できます。
Readlineの行編集機能を適切に動作させるためには、印字されない制御文字を%[
と%]
で囲んで、不可視であることを明示しなければなりません。
この記号の組み合わせはプロンプト内に複数記述することができます。
以下に例を示します。
testdb=> \set PROMPT1 '%[%033[1;33;40m%]%n@%/%R%[%033[0m%]%# '
これにより、VT100互換のカラー端末では、太字フォントで(1;
)、黒地に黄色の(33;40
)プロンプトが表示されます。
%w
PROMPT1
の直近の出力と同じ幅の空白です。
これは、複数行の文が最初の行とそろっているが第2のプロンプトが見えないようにするためにPROMPT2
の設定として使えます。
プロンプトにパーセント記号を入れる場合は、%%
と記述してください。
デフォルトのプロンプトは、プロンプト1と2が'%/%R%x%# '
、プロンプト3が'>> '
です。
この機能はtcshの機能を真似たものです。
psqlは行内編集や繰り返し入力が簡便になるようにReadlineライブラリをサポートしています。
コマンド履歴は、psqlの終了時に自動的に保存され、psqlの起動時に再読み込みされます。
タブによる補完もサポートされていますが、SQLのパーサとしてコマンドを解釈して判断してくれるわけではありません。
タブによる補完によって生成される問い合わせは他のSQLコマンド、例えばSET TRANSACTION ISOLATION LEVEL
と干渉することもあります。
タブによる補完を何らかの事情により使用したくなければ、ホームディレクトリ内の.inputrc
というファイルに以下のように書き込むことで無効にできます。
$if psql set disable-completion on $endif
(これはpsqlの機能ではなく、Readlineの機能です。 詳細についてはReadlineのドキュメントを参照してください)。
COLUMNS
\pset columns
がゼロの場合、wrapped
書式の幅、および、幅の広い出力がページャを必要とするかどうかを決める幅を制御します。
また自動拡張モードでは縦書式に切り替えるべきかどうかを制御します。
PGDATABASE
PGHOST
PGPORT
PGUSER
デフォルトの接続パラメータです(34.15を参照)。
PG_COLOR
診断メッセージで色を使うかどうかを指定します。
可能な値はalways
、auto
、never
です。
PSQL_EDITOR
EDITOR
VISUAL
\e
コマンド、\ef
コマンド、\ev
コマンドで使用されるエディタです。
変数はこの順に検索され、設定された最初のものが使用されます。
いずれも設定されていない場合、デフォルトでUnixシステムではvi
を、Windowsシステムではnotepad.exe
を使用します。
PSQL_EDITOR_LINENUMBER_ARG
\e
、\ef
または\ev
が行番号引数を付けて使用された場合、この変数は、ユーザのエディタに開始行番号を渡すために使用されるコマンドライン引数を指定します。
Emacsまたはviのようなエディタでは、これはプラス(+)記号です。
オプション名と行番号の間に空白文字が必要な場合は、変数の値の最後に空白文字を含めてください。
以下に例を示します。
PSQL_EDITOR_LINENUMBER_ARG='+' PSQL_EDITOR_LINENUMBER_ARG='--line '
Unixシステム上のデフォルトは+
です。
(デフォルトのエディタvi
に対応するものですが、他のよく使われる多くのエディタでも役に立ちます。)
一方Windowsシステムではデフォルトはありません。
PSQL_HISTORY
コマンド履歴ファイルの場所を指定します。
チルダ(~
)展開が行われます。
PSQL_PAGER
PAGER
問い合わせ結果が画面に入り切らない場合、このコマンドによって結果をパイプします。
一般的に指定される値は、more
、またはless
です。
ページャの使用を無効にするにはPSQL_PAGER
やPAGER
を空文字列にするか、\pset
コマンドのページャ関連のオプションを調整します。
これらの変数は列挙した順で検査され、最初の設定されているものが使われます。
いずれも設定されていない場合、デフォルトで大部分のプラットフォームではmore
が使われ、しかし、Cygwinではless
が使われます。
PSQLRC
ユーザの.psqlrc
ファイルの場所を指定します。
チルダ(~
)展開が行われます。
SHELL
\!
コマンドが実行するコマンドです。
TMPDIR
一時ファイルを格納するディレクトリです。
デフォルトは/tmp
です。
このユーティリティは、他のほとんどのPostgreSQLユーティリティと同様、libpqでサポートされる環境変数を使用します(34.15を参照してください)。
psqlrc
and ~/.psqlrc
-X
オプションが渡されない場合、psqlは、データベースに接続した後、通常のコマンドを受け付け始める前に、システム全体用の開始ファイル(psqlrc
)のコマンドを、続いてユーザ用の開始ファイル(~/.psqlrc
)のコマンドを読み込み、実行しようとします。
これらのファイルは、\set
やSET
コマンドを使用して、好みに応じたクライアントやサーバを設定するために使用することができます。
システム全体の開始ファイルはpsqlrc
という名前で、インストレーションの「システム設定」ディレクトリの中で探されます。
このディレクトリを特定するにはpg_config --sysconfdir
を実行するのが最も確実です。
デフォルトでは、PostgreSQLの実行ファイルを含むディレクトリからの相対パスで../etc/
になります。
このディレクトリの名前は環境変数PGSYSCONFDIR
を使って明示的に設定することができます。
ユーザ用の開始ファイルは.psqlrc
という名前で、実行しているユーザのホームディレクトリの中で探されます。
Windowsではそのような概念がないので、個人用の開始ファイルは%APPDATA%\postgresql\psqlrc.conf
という名前になります。
ユーザ用の開始ファイルは環境変数PSQLRC
で明示的に設定することができます。
システム全体用の開始ファイルとユーザ用の開始ファイルに、例えば、~/.psqlrc-9.2
や~/.psqlrc-9.2.5
のように、ハイフン記号とPostgreSQLのメジャーリリース番号またはマイナーリリース番号をファイル名に付加することで、特定バージョンのpsql向けのファイルとすることができます。
マッチするバージョンのファイルはバージョン指定のないファイルよりも優先して読み込まれます。
.psql_history
コマンドライン履歴はファイル~/.psql_history
、Windowsの場合は%APPDATA%\postgresql\psql_history
に格納されます。
履歴ファイルの場所はpsql変数のHISTFILE
または環境変数PSQL_HISTORY
を介して明示的に設定することができます。
psqlは、同じまたはより古いメジャーバージョンのサーバと稼働させることが最善です。
特にバックスラッシュコマンドは、サーバがpsql自身のバージョンより新しいと失敗しやすくなります。
\d
系列のバックスラッシュコマンドは7.4までさかのぼるバージョンのサーバで動作するはずですが、psql自身よりもサーバが新しい場合は、必ずしもそうではありません。
SQLコマンドの実行ならびに問い合わせ結果の表示といった一般的な機能はより新しいメジャーバージョンのサーバとでも動作するはずですが、すべての場合において保証することはできません。
メジャーバージョンが異なる複数のサーバとの接続のためにpsqlを使用したいのであれば、psqlの最新版を使用することを勧めます。 他の方法として、各メジャーバージョンのpsqlのコピーを保持し、確実にそれぞれのサーバに対応するバージョンを使用することができます。 しかし実際には、この複雑さを追加することは必要ではないはずです。
PostgreSQLの9.6より前では、-c
オプションが-X
(--no-psqlrc
)を暗示しましたが、現在ではそうなっていません。
PostgreSQLの8.4より前では、psqlで1文字のバックスラッシュコマンドの最初の引数をコマンドの直後に空白文字を挟むことなく記述できました。 現在では何らかの空白が必要になっています。
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 "public.my_table"
Column | Type | Collation | Nullable | Default
--------+---------+-----------+----------+---------
first | integer | | not null | 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 csv
Output format is csv. peter@localhost testdb=>\pset tuples_only
Tuples only is on. peter@localhost testdb=>SELECT second, first FROM my_table;
one,1 two,2 three,3 four,4 peter@localhost testdb=>\pset format unaligned
Output format is unaligned. peter@localhost testdb=>\pset fieldsep '\t'
Field separator is " ". 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
また、この出力書式オプションは\g
を使って1つの問い合わせにだけ設定できます。
peter@localhost testdb=>SELECT * FROM my_table
peter@localhost testdb->\g (format=aligned tuples_only=off expanded=on)
-[ RECORD 1 ]- first | 1 second | one -[ RECORD 2 ]- first | 2 second | two -[ RECORD 3 ]- first | 3 second | three -[ RECORD 4 ]- first | 4 second | four
これは、\df
コマンドを使って、名前がint*pl
にマッチし、2番目の引数の型がbigint
である関数のみを見つける例です。
testdb=> \df int*pl * bigint
List of functions
Schema | Name | Result data type | Argument data types | Type
------------+---------+------------------+---------------------+------
pg_catalog | int28pl | bigint | smallint, bigint | func
pg_catalog | int48pl | bigint | integer, bigint | func
pg_catalog | int8pl | bigint | bigint, bigint | func
(3 rows)
問い合わせの結果が適していれば、以下のように\crosstabview
コマンドを使用してクロス表形式で表示することができます。
testdb=>SELECT first, second, first > 2 AS gt2 FROM my_table;
first | second | gt2 -------+--------+----- 1 | one | f 2 | two | f 3 | three | t 4 | four | t (4 rows) testdb=>\crosstabview first second
first | one | two | three | four -------+-----+-----+-------+------ 1 | f | | | 2 | | f | | 3 | | | t | 4 | | | | t (4 rows)
この2つ目の例では、掛け算の表を、行は逆順にソートし、列はそれとは別に昇順に示しています。
testdb=>SELECT t1.first as "A", t2.first+100 AS "B", t1.first*(t2.first+100) as "AxB",
testdb(>row_number() over(order by t2.first) AS ord
testdb(>FROM my_table t1 CROSS JOIN my_table t2 ORDER BY 1 DESC
testdb(>\crosstabview "A" "B" "AxB" ord
A | 101 | 102 | 103 | 104 ---+-----+-----+-----+----- 4 | 404 | 408 | 412 | 416 3 | 303 | 306 | 309 | 312 2 | 202 | 204 | 206 | 208 1 | 101 | 102 | 103 | 104 (4 rows)