★PostgreSQLカンファレンス2021 11月12日開催/チケット販売中★
他のバージョンの文書 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.27. システム管理関数

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

9.27.1. 構成設定関数

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

表9.83 構成設定関数

関数

説明

current_setting ( setting_name text [, missing_ok boolean ] ) → text

現在のsetting_nameの設定値を返します。 そのような設定がなければ、missing_okが渡され、それがtrueでない限りcurrent_settingはエラーを引き起こします。 この関数はSQLコマンドのSHOWに関連します。

current_setting('datestyle')ISO, MDY

set_config ( setting_name text, new_value text, is_local boolean ) → text

setting_nameパラメータにnew_valueを設定し、その値を返します。 is_localが渡され、それがtrueなら新しい値は現在のトランザクションにのみ適用されます。 現在のセッションに新しい値を適用したければ、代わりにfalseとしてください。 このコマンドはSQLコマンドのSETに関連します。

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


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

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

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

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

関数

説明

pg_cancel_backend ( pid integer ) → boolean

指定したプロセスIDを持つバックエンドプロセスの現在のセッションの問い合わせを取り消します。 呼び出し側のロールがキャンセルされるバックエンドのロールのメンバーであるか、pg_signal_backendの権限を与えられている場合に実行できます。 ただし、スーパーユーザのバックエンドはスーパーユーザのみが取り消せます。

pg_reload_conf () → boolean

PostgreSQLのすべてのサーバプロセスに構成ファイルの再読み込みをさせます。 (これはSIGHUPシグナルをpostmasterプロセスに送ることによって始まり、postmasterは続いてSIGHUPを子に送ります。)

pg_rotate_logfile () → boolean

ログファイルマネージャにシグナルを送って新しいファイルに直ちに切り替えさせます。 これは組み込みのログ収集機構が実行中のみ動作します。でないとログマネージャサブプロセスが存在しないからです。

pg_terminate_backend ( pid integer ) → boolean

バックエンドが指定したプロセスIDを持つセッションを終了させます。 呼び出し側のロールが終了されるバックエンドのロールのメンバーであるか、pg_signal_backendの権限を与えられている場合に実行できます。 ただし、スーパーユーザのバックエンドはスーパーユーザのみが終了できます。


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

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

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

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

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

関数

説明

pg_create_restore_point ( name text ) → pg_lsn

先行書き込みログ中に後でリカバリターゲットとして使用できる名前付けされたマーカーレコードを作成し、関連する先行書き込みログの位置を返します。 与えられた名前はリカバリをどこまで進めるかを指定するためにrecovery_target_nameとともに利用できます。 同じ名前で複数のリストアポイントを作成するのは避けてください。リカバリターゲットが一致した最初のところでリカバリが停止するからです。

この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行する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

サーバがオンラインバックアップを開始するのを準備します。 必須パラメータはユーザが任意に定義したバックアップラベルだけです。 (通常、格納に使用するバックアップダンプファイルにちなんだ名前が付けられます。) オプションの2番目のパラメータがtrueとして与えられると、pg_start_backupを可能な限り素早く実行することが指定されます。 これによりI/O操作の急上昇をもたらして同時に実行中のすべての問い合わせを遅くする即時チェックポイントが強制されます。 オプションの3番目のパラメータは、排他あるいは非排他のどちらのバックアップを実行するかを指定します。(デフォルトは排他です。)

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

この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行するEXECUTE権限を与えることができます。

pg_stop_backup ( exclusive boolean [, wait_for_archive boolean ] ) → setof record ( lsn pg_lsn, labelfile text, spcmapfile text )

排他的あるいは非排他的オンラインバックアップを終了します。 exclusiveパラメータは以前のpg_start_backupの呼び出しと一致していなければなりません。 排他的バックアップでは、pg_stop_backupは、pg_start_backupで作成されたラベルファイルおよび、もしあればテーブル空間マップファイルを削除します。 非排他的バックアップでは、これらのファイルの必要な内容が関数の結果の一部として返され、それをバックアップ内のファイルに書き込む必要があります(データディレクトリ内のファイルに書いてはいけません)。

オプションで2番目のboolean型パラメータがあります。 falseの場合、pg_stop_backupはバックアップの完了後、WALがアーカイブされるのを待たずに、即座に戻ります。 この動作はWALのアーカイブを独立して監視するバックアップソフトウェアに対してのみ有用です。 それ以外の場合、バックアップを一貫性のあるものにするために必要なWALが欠けるためにバックアップが役立たなくなるかもしれません。 省略時あるいはこのパラメータがtrueのとき、アーカイブが有効なら、pg_stop_backupはWALがアーカイブされるまで待機します。 (スタンバイでは、これはつまりarchive_mode = alwaysのときのみ待機するということです。 プライマリでの書き込み活動が少ないときは、セグメントの変更を即座に起こさせるためにプライマリでpg_switch_walを実行するのが有効かもしれません。)

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

この関数の結果は単一レコードです。 lsn列はバックアップの終了先行書き込みログの位置です(これもまた無視可能です)。 2番目3番目の列は排他的バックアップの終了ではNULLです。非排他的バックアップの後では、2番目3番目の列にはラベルとテーブル空間マップファイルの必要な内容が含まれます。

この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行するEXECUTE権限を与えることができます。

pg_stop_backup () → pg_lsn

排他的オンラインバックを終了します。 pg_lsnを返す点だけを除けばこれはpg_stop_backup(true, true)の単純化されたバージョンです。

この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行するEXECUTE権限を与えることができます。

pg_is_in_backup () → boolean

排他的オンラインバックアップが実行中なら真を返します。

pg_backup_start_time () → timestamp with time zone

実行中ならオンライン排他的バックアップの開始時刻を返します。実行中でなければNULLを返します。

pg_switch_wal () → pg_lsn

サーバに対して新しい先行書き込みログファイルへ強制スイッチを行い、それによってその現在のファイルがアーカイブされるようにします。 (継続的アーカイブを利用中だと仮定します。) 結果は今ちょうど終了した先行書き込みログファイル内の終了先行書き込みログファイルの場所プラス1です。 最後の先行書き込みログファイルのスイッチ以降先行書き込みログファイル活動がなければ、pg_switch_walは何もせず、現在使用中の先行書き込みログファイルの先頭位置を返します。

この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行するEXECUTE権限を与えることができます。

pg_walfile_name ( lsn pg_lsn ) → text

先行書き込みログファイルの位置を、その位置を保持しているWALファイルの名前に変換します。

pg_walfile_name_offset ( lsn pg_lsn ) → record ( file_name text, file_offset integer )

先行書き込みログファイルの位置を、そのファイルの名前とそのファイル内のバイトオフセットに変換します。

pg_wal_lsn_diff ( lsn pg_lsn, lsn pg_lsn ) → numeric

2つの先行書き込みログの位置のバイト単位の差分を計算します。 これはpg_stat_replication表 9.85内の関数でレプリケーションの遅延を取得するために使用することができます。


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

pg_walfile_name_offsetを使用して、pg_lsn値から、対応する先行書き込みログファイル名とバイトオフセットを取り出すことができます。 以下に例を示します。

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

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

9.27.4. リカバリ制御関数

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

表9.86 リカバリ情報関数

関数

説明

pg_is_in_recovery () → boolean

まだリカバリ実施中であれば真を返します。

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.87に示す関数は、リカバリの進行を制御する関数です。 これらの関数はリカバリ中のみ実行することが可能です。

表9.87 リカバリ制御関数

関数

説明

pg_is_wal_replay_paused () → boolean

リカバリが中断中なら真を返します。

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権限を与えることができます。


pg_wal_replay_pausepg_wal_replay_resumeは昇格が進行中は実行できません。 リカバリ中断中に昇格が引き起こされると中断状態は終了し、昇格が継続します。

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

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

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

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

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

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

関数

説明

pg_export_snapshot () → text

現在のトランザクションのスナップショットを保存し、それを識別するtext文字列を返します。 この文字列は(データベースの外側で)スナップショットを取り込みたいクライアントに渡さなければなりません。 エクスポートしたトランザクションが終わるまでの間のみ、そのスナップショットをインポートすることができます。

必要ならばトランザクションは複数のスナップショットをエクスポートできます。 これはREAD COMMITTEDのトランザクションにおいてのみ有用であることに注意してください。 REPEATABLE READおよびそれ以上の隔離レベルのトランザクションでは終了まで同じスナップショットを使うからです。 一旦スナップショットをエクスポートしたトランザクションでは、PREPARE TRANSACTIONによる準備を使用することができなくなります。


9.27.6. レプリケーション管理関数

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

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

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

表9.89 レプリケーション管理関数

関数

説明

pg_create_physical_replication_slot ( slot_name name [, immediately_reserve boolean, temporary boolean ] ) → record ( 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 ] ) → record ( 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 ] ) → record ( 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 ]] ) → record ( slot_name name, lsn pg_lsn )

src_slot_nameという名前の既存の論理レプリケーションスロットをdst_slot_nameという名前の論理レプリケーションスロットにコピーします。オプションで出力プラグインと永続性を変更します。 コピーされた論理スロットはソース論理スロットと同じLSNから開始します。 temporarypluginはどちらもオプションです。 省略するとソース論理スロットと同じ値が使用されます。

pg_logical_slot_get_changes ( slot_name name, upto_lsn pg_lsn, upto_nchanges integer, VARIADIC options text[] ) → setof record ( 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 integer, VARIADIC options text[] ) → setof record ( 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 integer, VARIADIC options text[] ) → setof record ( 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 integer, VARIADIC options text[] ) → setof record ( lsn pg_lsn, xid xid, data bytea )

変更はbyteaとして返されることを除いてpg_logical_slot_peek_changes()関数と同じように振る舞います。

pg_replication_slot_advance ( slot_name name, upto_lsn pg_lsn ) → record ( slot_name name, end_lsn pg_lsn )

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 () → boolean

現在のセッションでレプリケーション起点が選択されていれば真を返します。

pg_replication_origin_session_progress ( flush boolean ) → pg_lsn

現在のセッションで設定されたレプリケーション起点の再生位置を返します。 パラメータflushにより、対応するローカルトランザクションがディスクにフラッシュされていることが保証されるかどうかを決定します。

pg_replication_origin_xact_setup ( origin_lsn pg_lsn, origin_timestamp timestamp with time zone ) → 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 boolean ) → pg_lsn

指定したレプリケーション起点の再生位置を返します。 パラメータflushにより、対応するローカルトランザクションがディスクにフラッシュされていることが保証されるかどうかを決定します。

pg_logical_emit_message ( transactional boolean, prefix text, content text ) → pg_lsn

pg_logical_emit_message ( transactional boolean, prefix text, content bytea ) → pg_lsn

論理デコードのメッセージを送出します これは汎用的なメッセージをWALを通して論理デコードのプラグインに渡すのに使うことができます。 パラメータtransactionalは、メッセージが現在のトランザクションの一部なのか、あるいはすぐに書き込み、論理デコードがレコードを読んだらすぐにデコードされるべきものなのかを指定します。 prefixパラメータは文字通りの接頭辞で、論理デコードのプラグインが、自分にとって関心のあるメッセージを容易に認識できるように使われます。 contentパラメータはメッセージの内容で、テキストまたはバイナリ形式で与えられます。


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

表 9.90で示された関数はデータベースオブジェクトのディスク領域の使用状況を計算したり、使用結果の表示を補助します。 これらの関数はすべてバイト単位の大きさを返します。 関数に存在するオブジェクト以外のOIDが渡されるとNULLが返ります。

表9.90 データベースオブジェクトサイズ関数

関数

説明

pg_column_size ( "any" ) → integer

個々のデータ値を格納するのに使用されるバイト数を表示します。 テーブルの列の値に直接適用すると、圧縮が行われていればそれを反映します。

pg_database_size ( name ) → bigint

pg_database_size ( oid ) → bigint

名前あるいはOIDで指定したデータベースによって使われている全ディスクスペースを計算します。 この関数を使うには、指定したデータベースにCONNECT権限(デフォルトで付与されています)を持っているか、pg_read_all_statsロールのメンバーでなければなりません。

pg_indexes_size ( regclass ) → bigint

指定したテーブルに付与されたインデックスで使用されている全ディスクスペースを計算します。

pg_relation_size ( relation regclass [, fork text ] ) → bigint

指定したリレーションの一つのforkで使用されているディスクスペースを計算します。 (大抵の目的には、すべてのフォークのサイズを合計する高レベルのpg_total_relation_sizeあるいはpg_table_sizeを使う方が便利です。) 引数1つではリレーションの主データフォークのサイズを返します。 2番目の引数で対象となるのがどのフォークであるかを指定できます。

  • mainはリレーションの主データフォークのサイズを返します。

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

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

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

pg_size_bytes ( text ) → bigint

可読性の高い形式(pg_size_prettyが返したもの)をバイトに変換します。

pg_size_pretty ( bigint ) → text

pg_size_pretty ( numeric ) → text

バイトサイズを、サイズ単位(バイト、kB、MB、GB、TBのうちの適切なもの)を使ったより人間が読みやすい形式に変換します。 単位は10のべき乗ではなく、2のべき乗であることに注意してください。ですから1kBは1024バイトで、1MBは10242 = 1048576バイト、などとなります。

pg_table_size ( regclass ) → bigint

指定テーブルが使用している、インデックスを含まないディスクスペースを計算します。(ただしあればTOASTテーブル、空き領域マップ、可視性マップを含みます。)

pg_tablespace_size ( name ) → bigint

pg_tablespace_size ( oid ) → bigint

名前あるいはOIDで指定されたテーブル空間で使用されているディスクスペースを計算します。 現在のデータベースのデフォルトテーブル空間でない限り、この関数を使うには、指定したテーブル空間にCREATE権限を持っているか、pg_read_all_statsロールのメンバーでなければなりません。

pg_total_relation_size ( regclass ) → bigint

指定テーブルが使用している、インデックスとTOASTデータを含む全ディスクスペースを計算します。 結果はpg_table_size + pg_indexes_sizeと等価です。


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

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

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

関数

説明

pg_relation_filenode ( relation regclass ) → oid

指定されたリレーションに現在割り当てられているファイルノード番号を返します。 ファイルノードは、リレーションに使用しているファイル名の基本要素です。(詳しくは68.1を参照して下さい。) ほとんどのリレーションについては、結果はpg_class.relfilenodeと同じになります。ただし、いくつかのシステムカタログではrelfilenodeがゼロになるため、これらのシステムカタログの正しいファイルノードを取得するには、この関数を使用しなければなりません。 この関数は、ビューの様にストレージに格納されないリレーションが指定された場合はNULLを返します。

pg_relation_filepath ( relation regclass ) → text

リレーションのファイルパス名全体(データベースクラスタのデータディレクトリ、PGDATAからの相対)を返します。

pg_filenode_relation ( tablespace oid, filenode oid ) → regclass

与えられたテーブル空間OIDとファイルノードに格納されているリレーションのOIDを返します。 これは本質的にpg_relation_filepathの逆マッピングです。 データベースのデフォルトテーブル空間内のテーブルに対しては、テーブル空間は0と指定できます。 当たられた値に対応する現在のデータベースにリレーションがなければNULLを返します。


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

表9.92 照合順序管理関数

関数

説明

pg_collation_actual_version ( oid ) → text

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

pg_import_system_collations ( schema regnamespace ) → integer

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


表 9.93にパーティション化テーブルの構造に関する情報を提供する関数を示します。

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

関数

説明

pg_partition_tree ( regclass ) → setof record ( relid regclass, parentrelid regclass, isleaf boolean, level integer )

1行1パーティションで与えられたパーティション化テーブルあるいはパーティション化インデックスのパーティションツリー内のテーブルあるいはインデックスの情報を表示します。 提供される情報にはパーティションOID、その直接の親のOID、パーティションが葉かどうかを示す真偽値、階層内のレベルを表す整数が含まれます。 レベル値は与えられたテーブルあるいはインデックスがパーティションツリーの根としての役割を持つことを表す0で始まり、1ならその直下のパーティション、2ならそのまた下のパーティションなどとなります。 リレーションが存在しない、あるいはパーティションでない、もしくはパーティション化テーブルでない場合は行を返しません。

pg_partition_ancestors ( regclass ) → setof regclass

パーティション自身を含む、与えられたパーティションの先祖リレーションを列挙します。 リレーションが存在しない、あるいはパーティションでない、もしくはパーティション化テーブルでない場合は行を返しません。

pg_partition_root ( regclass ) → regclass

与えられたリレーションが所属するパーティションツリーの最上位の親を返します。 リレーションが存在しない、あるいはパーティションでない、もしくはパーティション化テーブルでない場合はNULLを返します。


たとえばパーティション化テーブルmeasurementに含まれるデータの全体サイズを確認するには、次の問い合わせが利用できます。

SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size
  FROM pg_partition_tree('measurement');

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

表 9.94にインデックスの保守タスクに使用可能な関数を示します。 (これらの保守業務は通常自動バキュームが自動的に行うことに注意してください。これらの関数は特別な場合にのみ必要になります。) これらの関数はリカバリ中は実行できません。 これらの関数の使用はスーパーユーザと対象のインデックスの所有者に限定されます。

表9.94 Index Maintenance Functions

Function

説明

brin_summarize_new_values ( index regclass ) → integer

指定されたBRINインデックスを検査してベーステーブル内のインデックスによって現在要約されていないページ範囲を探します。 そのような範囲があれば、テーブルのページをスキャンして新しい要約インデックスタプルを作成します。 インデックスに挿入された新しいページ範囲要約の数を返します。

brin_summarize_range ( index regclass, blockNumber bigint ) → integer

指定のブロックを含むページ範囲が、まだ要約されていなければ、要約します。 これはbrin_summarize_new_valuesと似ていますが、指定されたテーブルブロック番号のみを対象としてページ範囲を処理するところだけが異なります。

brin_desummarize_range ( index regclass, blockNumber bigint ) → void

指定のブロックを含むページ範囲が要約されていれば、それを含むページ範囲を要約するBRINインデックスタプルを削除します。

gin_clean_pending_list ( index regclass ) → bigint

指定GINインデックスの処理待ちリストのエントリをメインのインデックスデータ構造に一括で移動します。 処理待ちリストから削除されたページ数を返します。 fastupdateオプションが無効で作成されたGINインデックスが引数なら、削除は起こらず結果がゼロになります。そのインデックスには処理待ちリストがないからです。 処理待ちリストとfastupdateオプションの詳細については66.4.166.5をご覧ください。


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

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

ユーザに対してEXECUTE権限をpg_read_file()あるいは関連する関数に与えることは、サーバの上データベースサーバプロセスが読めるすべてのファイルを読めるようにすることになることに注意してください。これらの関数はデータベース内のすべての権限チェックをすり抜けます。 このことは、たとえばそのようなアクセス権を持つユーザは、認証情報が格納されたpg_authidテーブルの中身を読むことができますし、同様にデータベース内のすべてのテーブルデータを読むことができるということを意味します。 ですからこれらの関数にアクセス権限を与えるのは慎重に考慮したほうが良いでしょう。

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

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

関数

説明

pg_ls_dir ( dirname text [, missing_ok boolean, include_dot_dirs boolean ] ) → setof text

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

デフォルトではこの関数の実行はスーパーユーザに限定されますが、他のユーザに関数を実行するEXECUTE権限を与えることができます。

pg_ls_logdir () → setof record ( name text, size bigint, modification timestamp with time zone )

サーバのログディレクトリ内の各通常ファイルについて、名前、サイズ、最終更新時刻(mtime)を返します。 ドットで始まるファイル名、ディレクトリ名その他の特殊なファイルは含まれません。

デフォルトではこの関数の実行はスーパーユーザとpg_monitorロールのメンバーに限定されますが、他のユーザに関数を実行するEXECUTE権限を与えることができます。

pg_ls_waldir () → setof record ( name text, size bigint, modification timestamp with time zone )

先行書き込みログ(WAL)ディレクトリ内の各ファイルについて、名前、サイズ、最終更新時刻(mtime)を返します。 ドットで始まるファイル名、ディレクトリ名その他の特殊なファイルは含まれません。

デフォルトではこの関数の実行はスーパーユーザとpg_monitorロールに限定されますが、他のユーザに関数を実行するEXECUTE権限を与えることができます。

pg_ls_archive_statusdir () → setof record ( name text, size bigint, modification timestamp with time zone )

WALアーカイブステータスディレクトリ(pg_wal/archive_status)内の各ファイルについて、名前、サイズ、最終更新時刻(mtime)を返します。 ドットで始まるファイル名、ディレクトリ名その他の特殊なファイルは含まれません。

デフォルトではこの関数の実行はスーパーユーザとpg_monitorロールに限定されますが、他のユーザに関数を実行するEXECUTE権限を与えることができます。

pg_ls_tmpdir ( [ tablespace oid ] ) → setof record ( name text, size bigint, modification timestamp with time zone )

指定されたtablespace内の一時ファイルディレクトリ内の各ファイルについて、名前、サイズ、最終更新時刻(mtime)を返します。 tablespaceが与えられなければpg_defaultテーブル空間が検査されます。 ドットで始まるファイル名、ディレクトリ名その他の特殊なファイルは含まれません。

デフォルトではこの関数の実行はスーパーユーザとpg_monitorロールのメンバーに限定されますが、他のユーザに関数を実行するEXECUTE権限を与えることができます。

pg_read_file ( filename text [, offset bigint, length bigint [, missing_ok boolean ]] ) → text

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

デフォルトではこの関数の実行はスーパーユーザに限定されますが、他のユーザに関数を実行するEXECUTE権限を与えることができます。

pg_read_binary_file ( filename text [, offset bigint, length bigint [, missing_ok boolean ]] ) → bytea

ファイルの一部あるいは全部を返します。 結果がtextではなくてbytea値となり、任意のバイナリデータを読み出すことができることを除き、pg_read_fileと同じです。 従って符号化方式の検査は行われません。

デフォルトではこの関数の実行はスーパーユーザに限定されますが、他のユーザに関数を実行するEXECUTE権限を与えることができます。

convert_from関数と組み合わせることで、この関数を、指定した符号化方式でファイルを読み込んでデータベース符号化方式に変換することができます。

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

pg_stat_file ( filename text [, missing_ok boolean ] ) → record ( size bigint, access timestamp with time zone, modification timestamp with time zone, change timestamp with time zone, creation timestamp with time zone, isdir boolean )

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

デフォルトではこの関数の実行はスーパーユーザに限定されますが、他のユーザに関数を実行するEXECUTE権限を与えることができます。


9.27.10. 勧告的ロック用関数

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

これらの関数はすべて単一の64ビットキー値か2つの32ビットキー値(これらのキー空間は重なり合わないことに注意してください)で識別されるアプリケーション定義のリソースをロックするために使うことを意図しています。 他のセッションがすでに同じリソース識別子とコンフリクトするロックを保持していたら、関数はリソースが利用可能になるまで待つか、その関数にとって適切ならばfalseを結果として返します。 ロックは共有はあるいは排他のどちらも可能です。共有ロックは同じリソースに対して他の共有ロックとコンフリクトしません。排他ロックとだけコンフリクトします。 ロックはセッションレベル(ロックは解放されるまで保持するかセッションの終了まで保持します)あるいはトランザクションレベル(ロックは現在のトランザクションが終了するまで保持します。手動で解放する方法はありません)で取得できます。 複数のセッションレベルロック要求は積み重ねられます。これにより、同じリソース識別子が3回ロックされると、セッション終了前にそのリソースを解放するアンロック要求が3回発行されなければならなくなります。

表9.96 勧告的ロック用関数

関数

説明

pg_advisory_lock ( key bigint ) → void

pg_advisory_lock ( key1 integer, key2 integer ) → void

必要なら待ってからセッションレベルの排他勧告的ロックを獲得します。

pg_advisory_lock_shared ( key bigint ) → void

pg_advisory_lock_shared ( key1 integer, key2 integer ) → void

必要なら待ってからセッションレベルの共有勧告的ロックを獲得します。

pg_advisory_unlock ( key bigint ) → boolean

pg_advisory_unlock ( key1 integer, key2 integer ) → boolean

事前に獲得したセッションレベルの排他的勧告ロックを解放します。 ロックの解放に成功した場合、trueを返します。 ロックを保持していない場合、falseを返し、さらに、SQL警告がサーバから報告されます。

pg_advisory_unlock_all () → void

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

pg_advisory_unlock_shared ( key bigint ) → boolean

pg_advisory_unlock_shared ( key1 integer, key2 integer ) → boolean

事前に獲得したセッションレベルの共有勧告的ロックを解放します。 ロックの解放に成功した場合、trueを返します。 ロックを保持していない場合、falseを返し、さらに、SQL警告がサーバから報告されます。

pg_advisory_xact_lock ( key bigint ) → void

pg_advisory_xact_lock ( key1 integer, key2 integer ) → void

必要なら待ってからトランザクションレベルの排他勧告的ロックを獲得します。

pg_advisory_xact_lock_shared ( key bigint ) → void

pg_advisory_xact_lock_shared ( key1 integer, key2 integer ) → void

必要なら待ってからトランザクションレベルの共有勧告的ロックを獲得します。

pg_try_advisory_lock ( key bigint ) → boolean

pg_try_advisory_lock ( key1 integer, key2 integer ) → boolean

可能ならセッションレベルの排他勧告的ロックを獲得します。 これは直ちにロックを取得してtrueを返すか、直ちにロックを取得できない場合は待たずにfalseを返します。

pg_try_advisory_lock_shared ( key bigint ) → boolean

pg_try_advisory_lock_shared ( key1 integer, key2 integer ) → boolean

可能ならセッションレベルの共有勧告的ロックを獲得します。 これは直ちにロックを取得してtrueを返すか、直ちにロックを取得できない場合は待たずにfalseを返します。

pg_try_advisory_xact_lock ( key bigint ) → boolean

pg_try_advisory_xact_lock ( key1 integer, key2 integer ) → boolean

可能ならトランザクションレベルの排他勧告的ロックを獲得します。 これは直ちにロックを取得してtrueを返すか、直ちにロックを取得できない場合は待たずにfalseを返します。

pg_try_advisory_xact_lock_shared ( key bigint ) → boolean

pg_try_advisory_xact_lock_shared ( key1 integer, key2 integer ) → boolean

可能ならトランザクションレベルの共有勧告的ロックを獲得します。 これは直ちにロックを取得してtrueを返すか、直ちにロックを取得できない場合は待たずにfalseを返します。