他のバージョンの文書 15 | 14 | 13 | 12 | 11 | 10 | 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.26. システム管理関数

本節で説明する関数は、PostgreSQLインストレーションの制御と監視を行うために使用されます。

9.26.1. 構成設定関数

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

表9.82 構成設定関数

名前戻り型説明
current_setting(setting_name [, missing_ok ]) 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)

setting_nameという名前の設定がない場合、missing_okが渡され、かつ、それがtrueのときを除き、current_settingはエラーを発生させます。

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

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

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

9.26.2. サーバシグナル送信関数

表 9.83に示す関数は、制御用シグナルを他のサーバプロセスに送信します。 これらの関数の使用は、デフォルトでスーパーユーザのみに制限されていますが、注記された例外を除き、GRANTを使用して他のユーザにアクセスを許可できます。

表9.83 サーバシグナル送信関数

名前戻り型説明
pg_cancel_backend(pid int) booleanバックエンドの現在の問い合わせを取り消す。 関数を呼ぶユーザが取り消す対象のバックエンドのロールのメンバーであるとき、あるいはpg_signal_backendの権限を与えられているときも実行できます。 ただし、スーパーユーザのバックエンドはスーパーユーザのみが取り消せます。
pg_reload_conf() booleanサーバプロセスに構成ファイルの再読み込みをさせる
pg_rotate_logfile() booleanサーバログファイルを循環させる
pg_terminate_backend(pid int) booleanバックエンドを終了する。 関数を呼ぶユーザが終了対象のバックエンドのロールのメンバーであるとき、あるいはpg_signal_backendの権限を与えられているときも実行できます。 ただし、スーパーユーザのバックエンドはスーパーユーザのみが終了できます。

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

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

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

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

9.26.3. バックアップ制御関数

表 9.84に示す関数はオンラインバックアップの作成を支援するものです。 これらの関数は、リカバリ中には実行できません(非排他的pg_start_backup、非排他的pg_stop_backuppg_is_in_backuppg_backup_start_time、およびpg_wal_lsn_diffは除く)。

表9.84 バックアップ制御関数

名前戻り型説明
pg_create_restore_point(name text) pg_lsnリストア実行用に名前付けされたポイントを作成(デフォルトではスーパーユーザのみ実施可能、ただし他のユーザにも関数を実行するEXECUTE権限を与えることができる)
pg_current_wal_flush_lsn() pg_lsn先行書き込みログの現在のフラッシュ位置を取得する
pg_current_wal_insert_lsn() pg_lsn現在の先行書き込みログの挿入位置の取得
pg_current_wal_lsn() pg_lsn現在の先行書き込みログの書き込み位置を取得
pg_start_backup(label text [, fast boolean [, exclusive boolean ]]) pg_lsnオンラインバックアップの実行準備(デフォルトではスーパーユーザでのみ実施可能、ただし他のユーザにも関数を実行するEXECUTE権限を与えることができる)
pg_stop_backup() pg_lsn排他的オンラインバックアップの実行の終了(デフォルトではスーパーユーザでのみ実施可能、ただし他のユーザにも関数を実行するEXECUTE権限を与えることができる)
pg_stop_backup(exclusive boolean [, wait_for_archive boolean ]) setof record排他的、あるいは非排他的オンラインバックアップの実行の終了(デフォルトではスーパーユーザでのみ実行可能、ただし他のユーザにも関数を実行するEXECUTE権限を与えることができる)
pg_is_in_backup() boolオンラインでの排他的バックアップが実行中は真。
pg_backup_start_time() timestamp with time zone実行中のオンライン排他的バックアップの開始時刻を取得。
pg_switch_wal() pg_lsn新しい先行書き込みログファイルへの強制移行(デフォルトではスーパーユーザのみ実行可能、ただし他のユーザにも関数を実行するEXECUTE権限を与えることができる)
pg_walfile_name(lsn pg_lsn) text先行書き込みログの位置をファイル名に変換
pg_walfile_name_offset(lsn pg_lsn) text, integer先行書き込みログの位置を、ファイル名とファイル内の10進のバイトオフセットに変換
pg_wal_lsn_diff(lsn pg_lsn, lsn pg_lsn) numeric2つの先行書き込みログの位置差分を算出

pg_start_backupは、ユーザが任意に定義したバックアップラベルを受け付けます。 (通常、格納に使用するバックアップダンプファイルにちなんだ名前が付けられます。) 排他モードで使用される場合、この関数は、データベースクラスタのデータディレクトリにバックアップラベルファイル(backup_label)およびpg_tblspc/ディレクトリにリンクがあるならテーブル空間マップファイル(tablespace_map)を書き出し、チェックポイントを実行し、先行書き込みログのバックアップ開始位置をテキスト形式で返します。 ユーザはこの結果値を無視することができますが、便利なこともあるので提供されています。 非排他モードで使用される場合は、排他モードとは違い、これらのファイルの内容がpg_stop_backup関数によって戻され、呼び出しユーザはそれをバックアップに書き込む必要があります。

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

オプションのboolean型パラメータがあります。 trueであれば、できる限り高速にpg_start_backupを実行します。 これは、即時のチェックポイントを強制するため、I/O 操作の急激な増加を引き起こし、実行中の問い合わせ全てを遅延させることがあります。

排他的バックアップでは、pg_stop_backupは、pg_start_backupで作成されたラベルファイルおよび、もしあればtablespace_mapファイルを削除します。 非排他的バックアップでは、backup_labelおよびtablespace_mapの内容が関数の結果として返され、それをバックアップ内のファイルに書き込む必要があります(データディレクトリ内のファイルに書いてはいけません)。 2番目のパラメータはboolean型で省略可能です。 falseの場合、pg_stop_backupはバックアップの完了後、WALがアーカイブされるのを待たずに、即座に戻ります。 この動作はWALのアーカイブを独立して監視するバックアップソフトウェアに対してのみ有用でしょう。 それ以外の場合、バックアップを一貫性のあるものにするために必要なWALが欠けていて、バックアップが役立たなくなるかもしれません。 このパラメータがtrueのとき、アーカイブが有効なら、pg_stop_backupはWALがアーカイブされるまで待機します。 スタンバイでは、これはつまりarchive_mode = alwaysのときのみ待機するということです。 プライマリでの書き込み活動が少ないときは、セグメントの変更を即座に起こさせるためにプライマリでpg_switch_walを実行するのが有効かもしれません。

プライマリで実行された場合、この関数はまた、先行書き込みログの格納領域にバックアップ履歴ファイルを作成します。 履歴ファイルにはpg_start_backupで付与されたラベル、バックアップの先行書き込みログの位置の開始位置、終了位置、バックアップ開始時刻、終了時刻が含まれます。 戻り値は、バックアップの終了先行書き込みログの位置です(これもまた無視可能です)。 終了位置を記録した後、現在の先行書き込みログの挿入位置は自動的に、次の先行書き込みログファイルに進みます。 従って、終了先行書き込みログファイルをすぐにアーカイブし、バックアップを完了させることができます。

pg_switch_walは次の先行書き込みログファイルに移動し、現在のファイルがアーカイブできるようにします(継続的アーカイブを使用している場合)。 戻り値は完了したばかりの先行書き込みログの終了書き込みログ位置に1を加えたものです。 最後に先行書き込みログを変更したときから先行書き込みログの活動がなかった場合は、pg_switch_walは何もせずに、現在使用中の先行書き込みログファイルの開始位置を返します。

pg_create_restore_pointはリカバリターゲットとして使用可能な名前付けされた先行書き込みログレコードを生成し、それに該当するログ位置を返します。 与えられた名前は、どこまでリカバリをするかを明示的に指定するrecovery_target_nameパラメータに使用することができます。 リカバリ処理はリカバリターゲットに指定した名前と一致した最初の時点で終了するため、同じ名前で複数のリストアポイントを作成することは避けてください。

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

pg_walfile_name_offsetを使用して、上記いずれの関数の結果からも、対応する先行書き込みログファイルとバイトオフセットを取り出すことができます。 以下に例を示します。

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

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

pg_wal_lsn_diffは、2つの先行書き込みログの位置の差分をバイト数で算出します。 この関数はpg_stat_replication表 9.84に示される関数と併用することで、レプリケーションの遅延の確認に使用できます。

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

9.26.4. リカバリ制御関数

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

表9.85 リカバリ情報関数

名前戻り型説明
pg_is_in_recovery() boolまだリカバリ実施中であれば真を返します。
pg_last_wal_receive_lsn() pg_lsnストリーミングレプリケーションにより受信されディスクに書き込みされた、先行書き込みログの最後の位置を取得します。ストリーミングレプリケーションが実施されている場合は、この値が単調に増加していくでしょう。リカバリが完了した場合、受信されディスクに書き込まれた最後のWALレコードの位置の値がそのまま残ります。ストリーミングレプリケーションが無効、もしくは開始されていない場合、この関数はNULLを返します。
pg_last_wal_replay_lsn() pg_lsnリカバリ中に再生された最後の先行書き込みログの位置を取得します。リカバリが実施されている場合は、この値が単調に増加していくでしょう。リカバリが完了した場合は、リカバリ時に適用された最後のWALレコードの値がそのまま残ります。もしサーバがリカバリ無しで普通に起動された場合、この関数はNULLを返します。
pg_last_xact_replay_timestamp() timestamp with time zone リカバリ中に再生された最後のトランザクションのタイムスタンプを取得します。 このタイムスタンプは、プライマリにて該当するトランザクションがコミット、もしくはアボートされた際のWALレコードが生成された時間です。 リカバリ中に何のトランザクションも再生されていない場合、この関数はNULLを返します。 リカバリがまだ実行中の場合、この関数の戻り値は単調に増加します。 リカバリが完了している場合、この関数の戻り値はリカバリ中に再生した最後のトランザクションの時間のまま変化しません。 サーバがリカバリ処理無しに正常に開始された場合、この関数はNULLを返します。

表 9.86に示す関数は、リカバリの進行を制御する関数です。 これらの関数はリカバリ中のみ実行することが可能です。

表9.86 リカバリ制御関数

名前戻り型説明
pg_is_wal_replay_paused() boolリカバリが停止中であれば真を返す
pg_promote(wait boolean DEFAULT true, wait_seconds integer DEFAULT 60) boolean 物理スタンバイサーバを昇格します。 waittrue(デフォルト)を設定すると、この関数は昇格が完了するか、wait_seconds秒が経過するまで待ち、昇格に成功すればtrue、さもなければfalseを返します。 waitfalseを設定すると、この関数は昇格を起こすためにpostmasterにSIGUSR1を送信した後、直ちにtrueを返します。 デフォルトではこの関数の実行はスーパーユーザに限定されますが、他のユーザに関数を実行するEXECUTE権限を与えることができます。
pg_wal_replay_pause() void即座にリカバリを停止する(デフォルトではスーパーユーザのみ実行可能、ただし他のユーザにも関数を実行するEXECUTE権限を与えることができる)
pg_wal_replay_resume() voidもしリカバリ停止中であれば再開する(デフォルトではスーパーユーザのみ実行可能、ただし他のユーザにも関数を実行するEXECUTE権限を与えることができる)

リカバリ停止中は、それ以降のデータベースへの変更は適用されません。 ホットスタンバイ側では、新しい問い合わせはすべて、同じ一貫性を持ったデータベースのスナップショットを参照することになります。 そしてリカバリが再開されるまで、これ以上の問い合わせの競合は発生しません。

ストリーミングレプリケーションが無効の場合、停止状態はいつまでも問題なく継続するでしょう。 ストリーミングレプリケーションの実行中は、WALレコードの受信が継続され、停止時間、WALの生成速度、ディスクの残存容量によりますが、ディスク溢れが発生する可能性があります。

9.26.5. スナップショット同期関数

PostgreSQLはデータベースのセッションに対して、それらのスナップショットを同期させることが可能です。 スナップショットは、そのスナップショットを使用しているトランザクションにどのデータが可視かを決定します。 同期スナップショットは、2つ以上のセッションにおいて、全く同じデータベース内容を見たい場合に必要となります。 単に2つのセッションが独立してそれぞれのトランザクションを開始するだけでは、第3のトランザクションのコミットが、2つのトランザクションのSTART TRANSACTIONの狭間で実行され、そのため一方のトランザクションではそのコミット結果が見え、他方では見えないという可能性が常にあります。

このような問題を解決するため、PostgreSQLではトランザクションが使用しているスナップショットをエクスポートできるようになっています。エクスポートしたトランザクションが開かれ続けている限り、他のトランザクションがそれをインポートすることができ、 そしてこれにより最初のトランザクションと正確に同じとなるデータベースの可視性を保証されます。ただし、これらの(スナップショットを共有している)トランザクションによって発生したデータベースへの変更は、コミットされていないトランザクションによる変更と同様に、(スナップショットを共有している)他のトランザクションには見えないままです。 つまり、既存データに対しては同期されますが、それら自身による変更については通常の振る舞いをします。

スナップショットは、表 9.87に示すpg_export_snapshot関数を用いてエクスポートされ、SET TRANSACTIONコマンドを用いてインポートされます。

表9.87 スナップショット同期関数

名前戻り値型説明
pg_export_snapshot() text現在のスナップショットを保存し、その識別子を返す

pg_export_snapshot関数は現在のスナップショットを保存し、そのスナップショットを識別するtext文字列を返します。 この文字列はスナップショットをインポートしたい(データベース外の)クライアントに渡されなければなりません。 エクスポートしたトランザクションが終わるまでの間のみ、そのスナップショットをインポートすることができます。 必要ならばトランザクションは複数のスナップショットをエクスポートできます。 REPEATABLE READや上位の隔離レベルでは、トランザクションはその有効期間の間同じスナップショットを使用しますので、これはREAD COMMITTEDトランザクションでのみ有用であることに注意してください。 一旦スナップショットをエクスポートしたトランザクションでは、PREPARE TRANSACTIONによる準備を使用することができなくなります。

エクスポートしたトランザクションの使用方法の詳細についてはSET TRANSACTIONを参照してください。

9.26.6. レプリケーション関数

表 9.88に示す関数はレプリケーション機能を制御したり、情報を取得したりするためのものです。 基盤となっている機能の情報に関しては26.2.526.2.6第49章を参照してください。 これらの関数のレプリケーションオリジンでの使用はスーパーユーザに限定されています。 これらの関数のレプリケーションスロットでの使用はスーパーユーザとREPLICATION権限を持つユーザに限定されています。

これらの関数の多くには、レプリケーションプロトコルに等価なコマンドがあります。 52.4を参照してください。

9.26.39.26.49.26.5に書かれている関数もレプリケーションに関係するものです。

表9.88 レプリケーションSQL関数

関数戻り値型説明
pg_create_physical_replication_slot(slot_name name [, immediately_reserve boolean, temporary boolean]) (slot_name name, lsn pg_lsn) slot_nameという名前の新しい物理レプリケーションスロットを作成します。 2番目のパラメータはオプションで、trueの場合、このレプリケーションスロットのLSNが即座に予約されることを指定します。 それ以外の場合はLSNはストリーミングレプリケーションのクライアントから最初に接続された時に予約されます。 物理スロットからのストリーミングの変更はストリーミングレプリケーションプロトコルでのみ可能です。52.4を参照してください。 3番目のパラメータtemporaryはオプションで、trueに設定されるとそのスロットは永続的にディスクに保存されるものではなく、現在のセッションによってのみ用いられることを意図していることを指定します。 一時的なスロットはエラーが発生したときも解放されます。 この関数は、レプリケーションプロトコルコマンドCREATE_REPLICATION_SLOT ... PHYSICALに対応するものです。
pg_drop_replication_slot(slot_name name) void slot_nameという名前の物理もしくは論理レプリケーションスロットを削除します。 レプリケーションプロトコルコマンドDROP_REPLICATION_SLOTと同じです。 論理スロットの場合、この関数はスロットが作成されたのと同じデータベースに接続している時に呼ばなければなりません。
pg_create_logical_replication_slot(slot_name name, plugin name [, temporary boolean]) (slot_name name, lsn pg_lsn) 出力プラグインpluginを使ってslot_nameという名前の新しいロジカル(デコーディング)レプリケーションスロットを作ります。 3番目のオプションパラメータtemporaryをtrueに設定すると、このスロットを永続的にディスクに保存するべきではなく、現在のセッションでのみ使われることを意図します。 また、一時スロットはエラーが起きると解放されます。 この関数の呼び出しはレプリケーションプロトコルコマンドのCREATE_REPLICATION_SLOT ... LOGICALと同じ効果があります。
pg_copy_physical_replication_slot(src_slot_name name, dst_slot_name name [, temporary boolean]) (slot_name name, lsn pg_lsn) src_slot_nameという名前の既存の物理レプリケーションスロットをdst_slot_nameという名前の物理レプリケーションスロットにコピーします。 コピーされた物理スロットはソーススロットと同じLSNからWALの保存を開始します。 temporaryはオプションです。 temporaryを省略すると、ソーススロットと同じ値を使用します。
pg_copy_logical_replication_slot(src_slot_name name, dst_slot_name name [, temporary boolean [, plugin name]]) (slot_name name, lsn pg_lsn) src_slot_nameという名前の既存の論理レプリケーションスロットをdst_slot_nameという名前の論理レプリケーションスロットに出力プラグインと永続性を変更しながらコピーします。 コピーされたロジカルスロットはソースロジカルスロットと同じLSNから開始します。 temporarypluginはどちらもオプションです。 temporaryあるいはpluginを省略すると、ソースロジカルスロットと同じ値が使用されます。
pg_logical_slot_get_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[]) (lsn pg_lsn, xid xid, data text) 変更が最後に消費された時点から開始して、スロットslot_nameの変更を返します。 upto_lsnupto_nchangesがNULLならば論理デコードはWALの最後まで続きます。 upto_lsnが非NULLであれば、デコードは指定されたLSNより前にコミットされたトランザクションのみを含みます。 upto_nchangesが非NULLであれば、デコードにより生成された行の数が指定された値を越えたときに、デコードは止まります。 しかしながら、新しいトランザクションの各コミットをデコードして生成された行を追加した後でしかこの制限は確認されませんので、実際に返される行の数は大きいかもしれないことに注意してください。
pg_logical_slot_peek_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[]) (lsn pg_lsn, xid xid, data text) 変更が消費されないということを除いて、pg_logical_slot_get_changes()関数と同じように振る舞います。すなわち、将来の呼び出しでは再び同じものが返ります。
pg_logical_slot_get_binary_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[]) (lsn pg_lsn, xid xid, data bytea) 変更はbyteaとして返されるということを除いてpg_logical_slot_get_changes()関数と同じように振る舞います。
pg_logical_slot_peek_binary_changes(slot_name name, upto_lsn pg_lsn, upto_nchanges int, VARIADIC options text[]) (lsn pg_lsn, xid xid, data bytea) 変更はbyteaとして返され消費されないということを除いてpg_logical_slot_get_changes()関数と同じように振る舞います。すなわち、将来の呼び出しでは再び同じものが返ります。
pg_replication_slot_advance(slot_name name, upto_lsn pg_lsn) (slot_name name, end_lsn pg_lsn) bool slot_nameという名前のレプリケーションスロットの現在の確認された位置を進めます。 スロットは後方には動きませんし、現在の挿入位置を超えて進むこともありません。 スロットの名前と前に進んだ実際の位置を返します。 前に進んだ場合は更新されたスロットに関する情報がこの後のチェックポイントで書き出されます。 クラッシュが発生すると、そのスロットは以前の位置に戻るかもしれません。
pg_replication_origin_create(node_name text) oid 指定した外部名でレプリケーション起点を作成し、割り当てられた内部IDを返します。
pg_replication_origin_drop(node_name text) void 以前に作成されたレプリケーション起点を、それに関連するすべての再生の進捗も含めて削除します。
pg_replication_origin_oid(node_name text) oid レプリケーション起点を名前で検索し、内部IDを返します。 相当するレプリケーション起点が見つからない場合はエラーが発生します。
pg_replication_origin_session_setup(node_name text) void 現在のセッションに、指定の起点から再生中であると印を付け、再生の進捗が追跡できるようにします。 元に戻すにはpg_replication_origin_session_resetを使って下さい。 以前に起点が設定されていない場合にのみ使うことができます。
pg_replication_origin_session_reset() void pg_replication_origin_session_setup()の効果を取り消します。
pg_replication_origin_session_is_setup() bool 現在のセッションで、レプリケーション起点が設定されたかどうかを返します。
pg_replication_origin_session_progress(flush bool) pg_lsn 現在のセッションで設定されたレプリケーション起点の再生位置を返します。 パラメータflushにより、対応するローカルトランザクションがディスクにフラッシュされていることが保証されるかどうかを決定します。
pg_replication_origin_xact_setup(origin_lsn pg_lsn, origin_timestamp timestamptz) void 現在のトランザクションに、指定のLSNおよびタイムスタンプでコミットしたトランザクションを再生中であると印をつけます。 事前にレプリケーション起点がpg_replication_origin_session_setup()を使って設定されている場合にのみ呼び出せます。
pg_replication_origin_xact_reset() void pg_replication_origin_xact_setup()の効果を取り消します。
pg_replication_origin_advance(node_name text, lsn pg_lsn) void 指定したノードのレプリケーションの進捗を、指定の位置に設定します。 これは主に設定変更の後で初期位置や新しい位置を設定するときなどに役立ちます。 この関数を不注意に使うと、レプリケーションデータが一貫性を失うかもしれないことに注意して下さい。
pg_replication_origin_progress(node_name text, flush bool) pg_lsn 指定したレプリケーション起点の再生位置を返します。 パラメータflushにより、対応するローカルトランザクションがディスクにフラッシュされていることが保証されるかどうかを決定します。
pg_logical_emit_message(transactional bool, prefix text, content text) pg_lsn 論理デコードのテキストのメッセージを送出します これは汎用的なメッセージをWALを通して論理デコードのプラグインに渡すのに使うことができます。 パラメータtransactionalは、メッセージが現在のトランザクションの一部なのか、あるいはすぐに書き込み、論理デコードがレコードを読んだらすぐにデコードされるべきものなのかを指定します。 prefixは文字通りの接頭辞で、論理デコードのプラグインが、自分にとって関心のあるメッセージを容易に認識できるように使われます。 contentはメッセージのテキストです。
pg_logical_emit_message(transactional bool, prefix text, content bytea) pg_lsn 論理デコードのバイナリのメッセージを送出します これは汎用的なメッセージをWALを通して論理デコードのプラグインに渡すのに使うことができます。 パラメータtransactionalは、メッセージが現在のトランザクションの一部なのか、あるいはすぐに書き込み、論理デコードがレコードを読んだらすぐにデコードされるべきものなのかを指定します。 prefixは文字通りの接頭辞で、論理デコードのプラグインが、自分にとって関心のあるメッセージを容易に認識できるように使われます。 contentはメッセージのバイナリの内容です。

9.26.7. データベースオブジェクト管理関数

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

表9.89 データベースオブジェクト容量関数

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

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_database_sizeを使うためには、指定されたデータベースにCONNECT権限(デフォルトで付与されている)を持っているか、あるいはpg_read_all_statsロールのメンバーでなければなりません。 pg_tablespace_sizeを使うためには、それが現在のデータベースのデフォルトテーブル空間でない限り、指定されたテーブル空間にCREATE権限を持っているか、あるいはpg_read_all_statsロールのメンバーでなければなりません。

pg_relation_sizeは、テーブル、インデックス、またはTOASTテーブルのOIDまたは名前を受け付け、そのリレーションの1つのフォークのディスク容量をバイト単位で返します。 (たいていの目的には、高位の関数pg_total_relation_sizepg_table_sizeを使うのがより便利であることに注意してください。高位の関数はフォークすべての容量を合計します。) 引数1つでは、そのリレーションの主データフォークの容量を返します。 2番目の引数はどのフォークを調査するかを指定するために設定できます。

  • 'main'を指定すると、そのリレーションの主データフォークの容量を返します。

  • 'fsm'を指定すると、リレーションに関連した空き領域マップ(68.3を参照)を返します。

  • 'vm'を指定すると、リレーションに関連した可視性マップ(68.4を参照)の容量を返します。

  • 'init'を指定すると、もしあれば、リレーションに関連した初期化フォークの容量を返します。

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

pg_size_bytes可読性の高い形式の文字列からバイト単位のサイズを取得するのに使用可能です。 入力はbytes、kB、MB、GB、TBの単位を使用可能で、大文字小文字を区別せずに解釈されます。 単位の指定がなければ、bytes(バイト)であるとみなされます。

注記

pg_size_prettyおよびpg_size_bytesが利用するkB、MB、GB、TBの単位は10のべき乗ではなく2のべき乗として定義されているため、1kBは1024バイト、1MBは10242 = 1048576バイト、それ以上も同じようになります。

上記の関数において、テーブルやインデックスをregclass引数として受け取って処理するものがありますが、この引数は単にpg_classシステムカタログにあるテーブルやインデックスのOIDです。 ただし、regclassデータ型が自動で入力変換を行うため、ユーザが手動で該当するOIDを調べる必要はありません。リテラル定数のようにシングルクオートで囲んだテーブル名を記述するだけです。 通常のSQL名に対する処理互換のため、テーブル名をダブルクオートで囲わない限り、テーブル名として入力された文字列は小文字に変換されます。

上記の関数に対し、既存オブジェクトに該当するものがないOIDが渡された場合はNULLが返されます。

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

表9.90 データベースオブジェクト位置関数

名前戻り型説明
pg_relation_filenode(relation regclass) oid 指定されたリレーションのファイルノード番号
pg_relation_filepath(relation regclass) text 指定されたリレーションのファイルパス
pg_filenode_relation(tablespace oid, filenode oid) regclass 与えられたテーブル空間とファイルノードに関連するリレーションを見つける

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

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

pg_filenode_relationpg_relation_filenodeの逆です。 テーブル空間OIDとファイルノードを与えると、関連するリレーションのOIDを返します。 データベースのデフォルトテーブル空間内のテーブルに対しては、テーブル空間は0と指定できます。

表 9.91に照合順序の管理に使用される関数の一覧を示します。

表9.91 照合順序管理関数

名前戻り型説明
pg_collation_actual_version(oid) text照合順序の実際のバージョンをオペレーティングシステムから返す
pg_import_system_collations(schema regnamespace) integerオペレーティングシステムの照合順序をインポートする

pg_collation_actual_versionは照合順序の実際のバージョンをオペレーティングシステムに現在インストールされている通りに返します。 これがpg_collation.collversionの値と異なる場合は、その照合順序に依存するオブジェクトは再構築が必要かもしれません。 ALTER COLLATIONも参照してください。

pg_import_system_collationsは、オペレーティングシステム上にあるすべてのロケールに基づき、システムカタログpg_collationに照合順序を追加します。 これはinitdbが使用しているもので、より詳細については23.2.2を参照してください。 その後にオペレーティングシステムに追加のロケールをインストールした場合、この関数を再度実行して、その新しいロケールの照合順序を追加することができます。 pg_collationに既存のエントリにマッチするロケールはスキップされます。 (しかし、オペレーティングシステム上にもはや存在しなくなったロケールに基づく照合順序オブジェクトはこの関数では削除されません。) schemaパラメータは通常はpg_catalogですが、必ずしもそうでなければならないわけではなく、照合順序をどれか他のスキーマにインストールすることもできます。 この関数は新しく作成された照合順序オブジェクトの数を返します。

表9.92 パーティション情報関数

名前戻り型説明
pg_partition_tree(regclass) setof record 1行1パーティションで与えられたパーティション化テーブルあるいはパーティション化インデックスのパーティションツリー内のテーブルあるいはインデックスの情報を表示します。 提供される情報にはパーティション名、その直接の親、パーティションが葉かどうかを示す真偽値、階層内のレベルを表す整数が含まれます。 レベル値は与えられたテーブルあるいはインデックスがパーティションツリーの根としての役割を持つことを表す0で始まり、1ならその直下のパーティション、2ならそのまた下のパーティションなどとなります。
pg_partition_ancestors(regclass) setof regclass パーティション自身を含む、与えられたパーティションの先祖リレーションを列挙します。
pg_partition_root(regclass) regclass 与えられたリレーションが所属するパーティションツリーの最上位の親を返します。

5.11.2.1で説明されているmeasurementテーブルに含まれるデータの全体サイズを確認するには、次の問い合わせが利用できます。

=# SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
     FROM pg_partition_tree('measurement');
 total_size 
------------
 24 kB
(1 row)

9.26.8. インデックス保守関数

表 9.93にインデックスの保守タスクに使用可能な関数を示します。 これらの関数はリカバリ中は実行できません。 これらの関数の使用はスーパーユーザと対象のインデックスの所有者に限定されます。

表9.93 インデックス保守関数

名前戻り型説明
brin_summarize_new_values(index regclass) integerまだ要約されていないページ範囲を要約する
brin_summarize_range(index regclass, blockNumber bigint) integer指定のブロックを含むページ範囲が、まだ要約されていなければ、要約する
brin_desummarize_range(index regclass, blockNumber bigint) integer指定のブロックを含むページ範囲が要約されていれば、要約されていない状態にする
gin_clean_pending_list(index regclass) bigintGINの処理待ちリストのエントリをメインのインデックス構造に移動する

brin_summarize_new_valuesはBRINインデックスのOIDまたは名前を受け取り、インデックスを検査してベーステーブル内のインデックスによって現在要約されていないページ範囲を探します。 そのような範囲があれば、テーブルのページをスキャンして新しい要約インデックスタプルを作成します。 インデックスに挿入された新しいページ範囲要約の数を返します。 brin_summarize_rangeも同じですが、ただし指定のブロック番号を含む範囲についてしか要約しません。

gin_clean_pending_listはGINインデックスのOIDまたは名前を受け取り、指定のインデックスの処理待ちリストのエントリをメインのGINデータ構造にまとめて移動することで、リストを削除します。 処理待ちリストから削除されたページ数が返されます。 引数がfastupdateオプションを無効にして構築されたGINインデックスの場合、インデックスには処理待ちリストがないため、削除は発生せず、戻り値は0になることに注意して下さい。 処理待ちリストおよびfastupdateの詳細については66.4.1および66.5を参照して下さい。

9.26.9. 汎用ファイルアクセス関数

表 9.94で示されている関数はサーバをホスティングしているマシン上のファイルに対し、ネイティブのアクセスを提供します。 ユーザがpg_read_server_filesロールを与えられていない限り、データベースクラスタディレクトリとlog_directoryに存在するファイルのみがアクセス可能です。 クラスタディレクトリ内のファイルに対して相対パスを、そしてログファイルに対してはlog_directory構成設定に一致するパスを使用してください。 これらの関数は特に記述がある場合を除き、スーパーユーザだけが使用できます。

ユーザに対してpg_read_file()あるいは関連する関数へのEXECUTE権限を許可することは、サーバ上のデータベースが読むことのできるすべてのファイルに対して読み出し許可を与えることになること、こうした読み出しについてはデータベース内のあらゆる権限チェックがすり抜けられることに注意してください。 これはつまり、この権限を持っているユーザは、とりわけ認証情報が含まれるpg_authidテーブルの内容を読むことができることを意味します。 ですから、これらの関数には注意深くアクセス許可を与えるべきです。

表9.94 汎用ファイルアクセス関数

名前戻り型説明
pg_ls_dir(dirname text [, missing_ok boolean, include_dot_dirs boolean]) setof text ディレクトリの内容を一覧表示する。デフォルトではスーパーユーザに制限されるが、他のユーザにEXECUTEを許可することによりこの関数を実行できる
pg_ls_logdir() setof record ログディレクトリ内のファイルの名前、サイズ、最終更新時刻を一覧表示します。 pg_monitorロールのメンバーにはアクセス権が付与されており、他の非スーパーユーザのロールにもアクセス権を付与することができます。
pg_ls_waldir() setof record WALディレクトリ内のファイルの名前、サイズ、最終更新時刻を一覧表示します。 pg_monitorロールのメンバーにはアクセス権が付与されており、他の非スーパーユーザのロールにもアクセス権を付与することができます。
pg_ls_archive_statusdir() setof record WALアーカイブステータスディレクトリ内のファイルの名前、サイズ、最終更新時刻を一覧表示します。 pg_monitorロールのメンバーにはアクセス権が付与されており、他の非スーパーユーザのロールにもアクセス権を付与することができます。
pg_ls_tmpdir([tablespace oid]) setof record tablespace用の一時ディレクトリ内のファイルの名前、サイズ、最終更新時刻を一覧表示します。 tablespaceが与えられなかった場合はpg_defaultテーブル空間が使用されます。 pg_monitorロールのメンバーにはアクセス権が付与されており、他の非スーパーユーザのロールにもアクセス権を付与することができます。
pg_read_file(filename text [, offset bigint, length bigint [, missing_ok boolean] ]) text テキストファイルの内容を返す。デフォルトではスーパーユーザに制限されるが、他のユーザにEXECUTEを許可することによりこの関数を実行できる
pg_read_binary_file(filename text [, offset bigint, length bigint [, missing_ok boolean] ]) bytea ファイルの内容を返す。デフォルトではスーパーユーザに制限されるが、他のユーザにEXECUTEを許可することによりこの関数を実行できる
pg_stat_file(filename text[, missing_ok boolean]) record ファイルについての情報を返す。デフォルトではスーパーユーザに制限されるが、他のユーザにEXECUTEを許可することによりこの関数を実行できる

これらの関数の一部はオプションでmissing_okパラメータをとり、ファイルまたはディレクトリが存在しない場合の動作を指定できます。 trueの場合、関数はNULLを返します(ただし、pg_ls_dirは空の結果集合を返します)。 falseの場合はエラーが発生します。 デフォルトはfalseです。

pg_ls_dirは、指定されたディレクトリ内のすべてのファイル(およびディレクトリと他の特殊ファイル)の名前を返します。 include_dot_dirs...が結果集合に含まれるかどうかを指定します。 デフォルト(false)ではそれらを除外しますが、それらを含めると、missing_oktrueの場合は、空のディレクトリと存在しないディレクトリを区別するために役立つでしょう。

pg_ls_logdirはログディレクトリ内の各ファイルについて、名前、サイズ、最終更新時刻(mtime)を返します。 デフォルトでは、スーパーユーザとpg_monitorロールのメンバーだけがこの関数を使用できます。 GRANTを使って他のロールにアクセス権を付与することができます。 ドットで始まるファイ名、ディレクトリ名その他の特殊なファイルは表示されません。

pg_ls_waldirは先行書き込みログ(WAL)ディレクトリ内の各ファイルについて、名前、サイズ、最終更新時刻(mtime)を返します。 デフォルトでは、スーパーユーザとpg_monitorロールのメンバーだけがこの関数を使用できます。 GRANTを使って他のロールにアクセス権を付与することができます。 ドットで始まるファイ名、ディレクトリ名その他の特殊なファイルは表示されません。

pg_ls_archive_statusdirはWALアーカイブディレクトリ内の各ファイルについて、名前、サイズ、最終更新時刻(mtime)を返します。 デフォルトでは、スーパーユーザとpg_monitorロールのメンバーだけがこの関数を使用できます。 GRANTを使って他のロールにアクセス権を付与することができます。 ドットで始まるファイ名、ディレクトリ名その他の特殊なファイルは表示されません。

pg_ls_tmpdirは指定されたtablespace用の一時ディレクトリ内のファイルの名前、サイズ、最終更新時刻を一覧表示します。 tablespaceが与えられなかった場合はpg_defaultテーブル空間が使用されます。 デフォルトでは、スーパーユーザとpg_monitorロールのメンバーだけがこの関数を使用できます。 GRANTを使って他のロールにアクセス権を付与することができます。 ドットで始まるファイ名、ディレクトリ名その他の特殊なファイルは表示されません。

pg_read_fileは与えられたoffsetから始まり、最大lengthバイト(先にファイルの終りに到達すればこれより少なくなります)テキストファイルの一部分を返します。 offsetが負の場合にはファイルの終りから数えた位置から読み出します。 offsetlengthが省略された場合、ファイル全体が返されます。 ファイルから読み込まれたバイトは、そのサーバの符号化方式での文字列として解釈されます。 読み込んだバイト列がその符号化方式において有効でない場合にはエラーが投げられます。

pg_read_binary_fileは、結果がbytea値となり、従って符号化の検査がされないことを除き、pg_read_fileと似ています。 convert_from関数と組み合わせることで、この関数を、指定した符号化方式でファイルの読み込むために使うことができます。

SELECT convert_from(pg_read_binary_file('file_in_utf8.txt'), 'UTF8');

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

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

9.26.10. 勧告的ロック用関数

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

表9.95 勧告的ロック用関数

名前戻り型説明
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_advisory_unlock(key bigint) booleanセッションレベルの排他勧告的ロックを解放
pg_advisory_unlock(key1 int, key2 int) booleanセッションレベルの排他勧告的ロックを解放
pg_advisory_unlock_all() void現在のセッションで保持している全てのセッションレベルの勧告的ロックを解放
pg_advisory_unlock_shared(key bigint) booleanセッションレベルの共有勧告的ロックを解放
pg_advisory_unlock_shared(key1 int, key2 int) booleanセッションレベルの共有勧告的ロックの解放
pg_advisory_xact_lock(key bigint) voidトランザクションレベルの排他勧告的ロックの獲得
pg_advisory_xact_lock(key1 int, key2 int) voidトランザクションレベルの排他勧告的ロックの獲得
pg_advisory_xact_lock_shared(key bigint) voidトランザクションレベルの共有勧告的ロックの獲得
pg_advisory_xact_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_try_advisory_xact_lock(key bigint) boolean可能ならばトランザクションレベルの排他勧告的ロックの獲得
pg_try_advisory_xact_lock(key1 int, key2 int) boolean可能ならばトランザクションレベルの排他勧告的ロックの獲得
pg_try_advisory_xact_lock_shared(key bigint) boolean可能ならばトランザクションレベルの共有勧告的ロックの獲得
pg_try_advisory_xact_lock_shared(key1 int, key2 int) boolean可能ならばトランザクションレベルの共有勧告的ロックの獲得

pg_advisory_lockは、アプリケーションが定義したリソースをロックします。キーは単一の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は、現在のセッションで保持するセッションレベルの勧告的ロックをすべて解放します。 (この関数は、クライアントとの接続がぶざまに切れた場合でも、セッション終了時に暗黙的に呼び出されます。)

pg_advisory_xact_lockの動作はpg_advisory_lockと同じですが、現在のトランザクションの終了時に自動的にロックが解放され、明示的なロックの解放はできません。

pg_advisory_xact_lock_sharedの動作はpg_advisory_lock_sharedと同じですが、現在のトランザクションの終了時に自動的にロックが解放され、明示的なロックの解放はできません。

pg_try_advisory_xact_lockの動作はpg_try_advisory_lockと同じですが、ロックが獲得できた場合は現在のトランザクションの終了時に自動的にロックが解放され、明示的なロックの解放はできません。

pg_try_advisory_xact_lock_sharedの動作はpg_try_advisory_lock_sharedと同じですが、ロックが獲得できた場合は現在のトランザクションの終了時に自動的にロックが解放され、明示的なロックの解放はできません。