他のバージョンの文書9.6 | 9.5 | 9.4 | 9.3 | 9.2 | 9.1 | 9.0 | 8.4 | 8.3 | 8.2 | 8.1 | 8.0 | 7.4 | 7.3 | 7.2

9.24. システム管理関数

表9-54は、実行時構成パラメータの問い合わせや変更に使用できる関数を示しています。

表 9-54. 構成設定関数

名前戻り型説明
current_setting(setting_name) text現在の設定値の取得
set_config(setting_name, new_value, is_local) textパラメータを設定し、新規値を返す

関数current_settingは、設定setting_nameの現在の値を返します。この関数は、SQLSHOWコマンドと同じです。以下に例を示します。

SELECT current_setting('datestyle');

 current_setting
-----------------
 ISO, MDY
(1 row)

set_config関数は、パラメータsetting_namenew_valueに設定します。ただし、is_localtrueの場合、新規値は現在のトランザクションにのみ適用されます。新規値を現在のセッションに適用する場合は、代わりにfalseを使用してください。この関数は、SQLのSETコマンドと同じです。以下に例を示します。

SELECT set_config('log_statement_stats', 'off', false);

 set_config
------------
 off
(1 row)

表9-55に示す関数は、制御用シグナルを他のサーバプロセスに送信します。これらの関数の使用はスーパーユーザのみに制限されています。

表 9-55. サーバシグナル送信関数

名前戻り型説明
pg_cancel_backend(pid int) booleanバックエンドの現在の問い合わせを取り消す
pg_terminate_backend(pid int) booleanバックエンドを終結
pg_reload_conf() booleanサーバプロセスに構成ファイルの再読み込みをさせる
pg_rotate_logfile() booleanサーバログファイルを循環させる

これらのぞれぞれの関数は成功の場合true(真)を返し、そうでない場合はfalse(偽)を返します。

pg_cancel_backendpg_terminate_backendは(それぞれ、SIGINTまたはSIGTERM)シグナルをプロセス識別子で特定されたバックエンドプロセスに送ります。使用中のバックエンドのプロセス識別子はpg_stat_activityビューのprocpid列から、もしくは、(UnixではpsWindowsではTask Managerにより)サーバ上のpostgresプロセスをリストすることで見つけられます。

pg_reload_confSIGHUPシグナルをサーバに送り、その結果全てのサーバプロセスが構成ファイルを再読み込みすることになります。

pg_rotate_logfileはログファイルマネージャに即座に新規出力ファイルに切替えるよう信号を送ります。これは組み込みログ取得が起動している場合のみ有効です。起動していない場合はログファイルマネージャの子プロセスが存在しない理由からです。

表9-56に示す関数はオンラインバックアップの作成を支援するものです。これらの関数は、リカバリ中には実行できません。最初の3つの関数の使用はスーパーユーザに制限されています。

表 9-56. バックアップ制御関数

名前戻り型説明
pg_start_backup(label text [, fast boolean ]) textオンラインバックアップの実行準備
pg_stop_backup() textオンラインバックアップの実行後に終了
pg_switch_xlog() text新しいトランザクションログファイルへの強制移行
pg_current_xlog_location() text現在のトランザクションログの書き込み位置を入手
pg_current_xlog_insert_location() text現在のトランザクションログの挿入位置を入手
pg_xlogfile_name_offset(location text) text, integerトランザクションログの位置を表す文字列を、ファイル名とファイル内の10進のバイトオフセットに変換
pg_xlogfile_name(location text) textトランザクションログの位置を表す文字列をファイル名に変換

pg_start_backupは、ユーザが任意に定義したバックアップラベルを受け付けます(通常、格納に使用するバックアップダンプファイルにちなんだ名前が付けられます)。この関数は、データベースクラスタのデータディレクトリにバックアップラベルファイル(backup_label)を書き出し、チェックポイントを実行し、バックアップを始めるトランザクションログの位置をテキスト形式で返します。ユーザはこの結果値を無視することができますが、便利なこともあるので提供されています。

postgres=# select pg_start_backup('label_goes_here');
 pg_start_backup
-----------------
 0/D4445B8
(1 row)

オプションのboolean型パラメータがあります。であれば、すべからく早くpg_start_backupの実行を指定します。いかなる現時点で実行中の問い合わせも速度を落とし、I/O操作で急増の原因の即時チェックポイントを強要します。

pg_stop_backupは、pg_start_backupで作成されたラベルファイルを削除し、トランザクションログ格納領域にバックアップ履歴ファイルを作成します。履歴ファイルにはpg_start_backupで付与されたラベル、バックアップのトランザクションログの位置の開始位置、終了位置、バックアップ開始時刻、終了時刻が含まれます。戻り値は、バックアップの終了トランザクションログの位置です(これも同様に無視可能です)。終了位置を記録した後、現在のトランザクションログの挿入位置は自動的に、次のトランザクションログに進みます。ですので、終了トランザクションログファイルをすぐにアーカイブし、バックアップを完了させることができます。

pg_switch_xlogは、次のトランザクションログファイルに移動し、現在のファイルをアーカイブできるようにします。(アーカイブを続けて使用することを前提とします。)戻り値は、完了した現在のトランザクションログファイル内の終了トランザクションログの位置に1を加えたものです。前回のトランザクションログファイルの切り替えからトランザクションログに変化がなければ、pg_switch_xlogは現在使用中のトランザクションログファイルの開始位置を返します。

pg_current_xlog_locationは、上記の関数で使用される同一の書式で現在のトランザクションログの書き込み位置を表示します。同様にpg_current_xlog_insert_locationは、現在のトランザクションログの挿入位置を表示します。挿入位置は "論理的"な任意の時点のトランザクションログの終了位置です。一方、書き込み位置は、サーバの内部バッファから書き出された実際の終了位置です。書き込み位置はサーバ外部から検証可能なものの終端です。通常は、部分的に完了したトランザクションログファイルのアーカイブ処理を行いたい場合に必要とされるものです。挿入位置はサーバをデバッグする際に主に使用されます。これらはどちらも読み取りのみの操作であり、スーパーユーザ権限を必要としません。

pg_xlogfile_name_offsetを使用して、上記いずれの関数の結果からも、対応するトランザクションログファイルとバイトオフセットを取り出すことができます。以下に例を示します。

postgres=# SELECT * FROM pg_xlogfile_name_offset(pg_stop_backup());
        file_name         | file_offset 
--------------------------+-------------
 00000001000000000000000D |     4039624
(1 row)

同様に、pg_xlogfile_nameは、トランザクションログファイル名のみを取り出します。指定したトランザクションログの位置が正確にトランザクションログファイルの境界であった場合、これらの両関数は前のトランザクションログファイルの名前を返します。通常これは、トランザクションログファイルのアーカイブ動作では好まれる動作です。前のファイルが現在のアーカイブで必要とする最後のファイルであるからです。

これらの関数の正しい使用方法については、項24.3を参照してください。

表9-57に示される関数は、スタンバイサーバの現在のステータス情報を提供します。これらの関数はリカバリ中、および通常稼動時に実行することができるでしょう。

表 9-57. リカバリ情報関数

名前戻り型説明
pg_is_in_recovery() boolまだリカバリ実施中であれば真を返します。
pg_last_xlog_receive_location() textストリーミングレプリケーションにより受信されディスクに書き込みされた、トランザクションログの最後の位置を取得します。ストリーミングレプリケーションが実施されている場合は、この値が単調に増加していくでしょう。ただし、ストリーミングレプリケーションが一度停止されて、再度開始された場合、レプリケーションの開始位置まで巻き戻ることがあります。典型的には現在の再生位置を含むWALファイルの先頭です。リカバリが完了した場合、受信されディスクに書き込まれた最後のWALレコードの位置の値がそのまま残ります。ストリーミングレプリケーションが無効、もしくは開始されていない場合、この関数はNULLを返します。
pg_last_xlog_replay_location() textリカバリ中に再生された最後のトランザクションログの位置を取得します。リカバリが実施されている場合は、この値が単調に増加していくでしょう。リカバリが完了した場合は、リカバリ時に適用された最後のWALレコードの値がそのまま残ります。もしサーバがリカバリ無しで普通に起動された場合、この関数はNULLを返します。

表9-58で示された関数はデータベースオブジェクトのディスク領域を計算します。

表 9-58. データベースオブジェクト容量関数

名前戻り型説明
pg_column_size(any)int特定の値を格納するのに使用される(場合により圧縮された)バイト数
pg_total_relation_size(regclass) bigint 指定されたOIDもしくは名前のテーブルで使用される、すべてのインデックスとTOASTデータを含むディスク総容量。
pg_table_size(regclass) bigint 指定されたOIDもしくは名前のテーブルで使用される容量の内、すべてのインデックスを除外した(しかしTOAST、空き領域マップ、可視性マップを含む)ディスク総容量。
pg_indexes_size(regclass) bigint 指定されたOIDもしくは名前のテーブルに関連したインデックスで使用される総ディスク容量。
pg_database_size(oid) bigint指定されたOIDを持つデータベースで使用されるディスク容量
pg_database_size(name) bigint指定された名前を持つデータベースで使用されるディスク容量
pg_tablespace_size(oid)> bigint指定されたOIDを持つテーブル空間で使用されるディスク容量
pg_tablespace_size(name) bigint指定された名前を持つテーブル空間で使用されるディスク容量
pg_relation_size(relation regclass, fork text) bigint 指定されたOIDまたは名前のテーブルまたはインデックスの指定されたフォーク('main''fsm'または'vm')で使用されるディスク容量
pg_relation_size(relation regclass) bigint pg_relation_size(..., 'main')の省略表現
pg_size_pretty(bigint) textバイト単位のサイズを指定サイズの可読性が高い書式に変換

pg_column_sizeはどんな個別のデータ値を格納するのにも使用される領域を示します。

pg_total_relation_sizeは、テーブルまたはTOASTテーブルのOIDまたは名前を受け付け、指定されたテーブルと関連する全てのインデックスで使用される総ディスク容量を返します。この関数はpg_table_size + pg_indexes_size の結果と等しいです。

pg_table_sizeは、テーブルのOIDまたは名前を受け付け、インデックスを除いたテーブルのみで使用されるディスク容量を返します。(TOAST領域、空き領域マップ、可視性マップを含みます。)

pg_indexes_sizeは、テーブルのOIDまたは名前を受け付け、指定されたテーブル付与されている全てのインデックスで使用されるディスク容量を返します。

pg_database_sizepg_tablespace_sizeはデータベースまたはテーブル空間の名前またはOIDを受付け、そこで使用される総容量を返します。

pg_relation_sizeはOIDもしくはテーブル名、インデックスもしくはtoastテーブルを受け付け、ディスク容量をバイト単位で返します。'main'を指定するか、第二番目の引数を除外するとその関係の主データフォークの容量を返します。'fsm'を指定すると、関係(リレーション)に関連した空き領域マップ(項54.3を参照)を返します。'vm'を指定すると、関係に関連した可視性マップ(項54.4を参照)の容量を返します。この関数は一つのフォークのみのサイズを示すことに注意して下さい。大方の目的では、pg_total_relation_sizepg_table_sizeなどの関数を使う方が便利です。

pg_size_prettyは、適切にkB、MB、GB、もしくはTB単位を使用して目で見て判るようにその他の関数の1つの結果を整形するのに使用可能です。

表9-59 に示される関数は、データベースオブジェクトに関連する特定のディスクファイルを確認する際の手助けとなります。

表 9-59. データベースオブジェクト位置関数

名前戻り型説明
pg_relation_filenode(relation regclass) oid 指定されたOIDまたは名前に関連するリレーションのファイルノード番号
pg_relation_filepath(relation regclass) text 指定されたOIDまたは名前に関連するリレーションのファイルパス

pg_relation_filenodeは、テーブル、インデックス、シーケンス、もしくはTOASTテーブルのOIDまたは名前を受け付け、現在それに充てられている"ファイルノード"を返します。ファイルノードは、リレーションに使用しているファイル名の基礎部分です。(詳しくは項54.1を参照して下さい。)ほとんどのテーブルについては、結果がpg_class.relfilenodeと同じになります。ただし、いくつかのシステムカタログではrelfilenodeが0になるため、これらのシステムカタログの正しいファイルノードを取得するには、この関数を使用しなければいけません。この関数は、ビューの様にストレージに格納されないリレーションが指定された場合はNULLを返します。

pg_relation_filepathpg_relation_filenodeと似ていますが、こちらはリレーションのファイルパス名(データベースクラスタのディレクトリであるPGDATAからの相対パス)を返します。

表9-60で示されている関数はサーバをホスティングしているマシン上のファイルに対し、生来のアクセスを提供します。データベースクラスタディレクトリとlog_directoryに存在するファイルのみがアクセス可能です。クラスタディレクトリ内のファイルに対して相対パスを、そしてログファイルに対してはlog_directory構成設定に一致するパスを使用してください。

表 9-60. 汎用ファイルアクセス関数

名前戻り型説明
pg_ls_dir(dirname text) setof textディレクトリ内容のリスト
pg_read_file(filename text, offset bigint, length bigint) textテキストファイルの内容を返す
pg_stat_file(filename text) recordファイル情報を返す

pg_ls_dirは、特別なエントリである"."、および ".."を除いた、指定されたディレクトリの全ての名前を返します。

pg_read_fileは与えられたoffsetから始まり、最大lengthバイト(最初にファイルの終りに到達すればこれより少なくなりますが)テキストファイルの一部分を返します。offsetが負の場合にはファイルの終りから数えた位置から読み出します。

pg_stat_fileはファイル容量、最終アクセス時刻、最終更新時刻、最後にファイルステータスを変更した時刻(これはUnixプラットフォームのみ)、ファイル作成時刻(Windowsのみ)およびもしディレクトリであればそれを示すbooleanを返します。典型的な使用法を示します。

SELECT * FROM pg_stat_file('filename');
SELECT (pg_stat_file('filename')).modification;

表9-61に示す関数は勧告的ロックを管理します。これらの関数の適切な使用方法についての詳細は、項13.3.4を参照してください。

表 9-61. 勧告的ロック用関数

名前戻り型説明
pg_advisory_lock(key bigint) void排他勧告的ロックを獲得
pg_advisory_lock(key1 int, key2 int) void排他勧告的ロックを獲得
pg_advisory_lock_shared(key bigint) void共有勧告的ロックを獲得
pg_advisory_lock_shared(key1 int, key2 int) void共有勧告的ロックを獲得
pg_try_advisory_lock(key bigint) boolean可能ならば排他勧告的ロックを獲得
pg_try_advisory_lock(key1 int, key2 int) boolean可能ならば排他勧告的ロックを獲得
pg_try_advisory_lock_shared(key bigint) boolean可能ならば共有勧告的ロックを獲得
pg_try_advisory_lock_shared(key1 int, key2 int) boolean可能ならば共有勧告的ロックを獲得
pg_advisory_unlock(key bigint) boolean排他勧告的ロックを解放
pg_advisory_unlock(key1 int, key2 int) boolean排他勧告的ロックを解放
pg_advisory_unlock_shared(key bigint) boolean共有勧告的ロックを解放
pg_advisory_unlock_shared(key1 int, key2 int) boolean共有勧告的ロックを解放
pg_advisory_unlock_all() void現在のセッションで保持している勧告的ロックをすべて解放

pg_advisory_lockは、アプリケーションが定義したリソースをロックします。キー型はpg_locks.objidで指定されます。これは、単一の64ビットキー値、または、2つの32ビットキー(この2つのキー空間は重複しないことに注意)によって識別されます。他のセッションが同一リソースに対するロックを保持している場合、関数はリソースが利用可能になるまで待機します。ロックは排他ロックです。複数のロック要求が待ち状態になります。ですので、同一リソースが3回ロックされた場合、他のセッションが使用できるように解放するためにはロック解除を3回行わなければなりません。

pg_advisory_lock_sharedの動作はpg_advisory_lockと同じですが、他のセッションの共有ロックと共有できるロックである点が異なります。 排他ロック要求のみ締め出されます。

pg_try_advisory_lockpg_advisory_lockと同様ですが、この関数の場合、ロックが利用可能になるまで待機しません。ロックを即座に取得しtrueを返すか、ロックを即座に獲得できなかった場合にfalseを返すかのいずれかです。

pg_try_advisory_lock_sharedの動作は pg_try_advisory_lockと同じですが、排他ロックではなく共有ロックの獲得を試みます。

pg_advisory_unlockは、事前に獲得した勧告的排他ロックを解放します。ロックの解放に成功した場合、trueを返します。ロックを保持していない場合、falseを返し、さらに、SQL警告がサーバから発生します。

pg_advisory_unlock_sharedの動作はpg_advisory_unlockと同じですが、勧告的共有ロックを解放する点が異なります。

pg_advisory_unlock_allは、現在のセッションで保持する勧告的ロックを解放します。(この関数は、クライアントとの接続がぶざまに切れた場合でも、セッション終了時に暗黙的に呼び出されます。)