本節で説明する関数は、PostgreSQLインストレーションの制御と監視を行うために使用されます。
表 9.83は、実行時設定パラメータの問い合わせや変更に使用できる関数を示しています。
表9.83 構成設定関数
表 9.84に示す関数は、制御用シグナルを他のサーバプロセスに送信します。
これらの関数の使用は、デフォルトでスーパーユーザのみに制限されていますが、注記された例外を除き、GRANT
を使用して他のユーザにアクセスを許可できます。
これらのそれぞれの関数は成功の場合true
(真)を返し、そうでない場合はfalse
(偽)を返します。
表9.84 サーバシグナル送信関数
pg_cancel_backend
とpg_terminate_backend
は(それぞれ、SIGINTまたはSIGTERM)シグナルをプロセス識別子で特定されたバックエンドプロセスに送ります。
使用中のバックエンドのプロセス識別子はpg_stat_activity
ビューのpid
列から、もしくは、(Unixではps、WindowsではTask Managerにより)サーバ上のpostgres
プロセスをリストすることで見つけられます。
実行中のバックエンドのロールはpg_stat_activity
のusename
列から確認することができます。
表 9.85に示す関数はオンラインバックアップの作成を支援するものです。
これらの関数は、リカバリ中には実行できません(非排他的pg_start_backup
、非排他的pg_stop_backup
、pg_is_in_backup
、pg_backup_start_time
、およびpg_wal_lsn_diff
は除く)。
これらの関数の正しい使用方法については、25.3を参照してください。
表9.85 バックアップ制御関数
関数 説明 |
---|
先行書き込みログ中に後でリカバリターゲットとして使用できる名前付けされたマーカーレコードを作成し、関連する先行書き込みログの位置を返します。 与えられた名前はリカバリをどこまで進めるかを指定するためにrecovery_target_nameとともに利用できます。 同じ名前で複数のリストアポイントを作成するのは避けてください。リカバリターゲットが一致した最初のところでリカバリが停止するからです。 この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行するEXECUTE権限を与えることができます。 |
先行書き込みログの現在のフラッシュ位置を取得します。(下の注釈を参照してください。) |
現在の先行書き込みログの挿入位置を取得します。(下の注釈を参照してください。) |
現在の先行書き込みログの書き込み位置を取得します。(下の注釈を参照してください。) |
サーバがオンラインバックアップを開始するのを準備します。
必須パラメータはユーザが任意に定義したバックアップラベルだけです。
(通常、格納に使用するバックアップダンプファイルにちなんだ名前が付けられます。)
オプションの2番目のパラメータが
排他モードで使用される場合、この関数は、データベースクラスタのデータディレクトリにバックアップラベルファイル( この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行するEXECUTE権限を与えることができます。 |
排他的あるいは非排他的オンラインバックアップを終了します。
オプションで2番目の
プライマリで実行された場合、この関数はまた、先行書き込みログの格納領域にバックアップ履歴ファイルを作成します。
履歴ファイルには
この関数の結果は単一レコードです。
この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行するEXECUTE権限を与えることができます。 |
排他的オンラインバックを終了します。
この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行するEXECUTE権限を与えることができます。 |
排他的オンラインバックアップが実行中なら真を返します。 |
実行中ならオンライン排他的バックアップの開始時刻を返します。実行中でなければ |
サーバに対して新しい先行書き込みログファイルへ強制スイッチを行い、それによってその現在のファイルがアーカイブされるようにします。
(継続的アーカイブを利用中だと仮定します。)
結果は今ちょうど終了した先行書き込みログファイル内の終了先行書き込みログファイルの場所プラス1です。
最後の先行書き込みログファイルのスイッチ以降先行書き込みログファイル活動がなければ、 この関数はデフォルトではスーパーユーザのみ実施可能ですが、他のユーザにも関数を実行するEXECUTE権限を与えることができます。 |
先行書き込みログファイルの位置を、その位置を保持しているWALファイルの名前に変換します。 |
先行書き込みログファイルの位置を、そのファイルの名前とそのファイル内のバイトオフセットに変換します。 |
2つの先行書き込みログの位置のバイト単位の差分を計算します。
これは |
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.86に示される関数は、スタンバイサーバの現在のステータス情報を提供します。 これらの関数はリカバリ中、および通常稼動時に実行することができるでしょう。
表9.86 リカバリ情報関数
表 9.87に示す関数は、リカバリの進行を制御する関数です。 これらの関数はリカバリ中のみ実行することが可能です。
表9.87 リカバリ制御関数
pg_wal_replay_pause
とpg_wal_replay_resume
は昇格が進行中は実行できません。
リカバリ中断中に昇格が引き起こされると中断状態は終了し、昇格が継続します。
ストリーミングレプリケーションが無効の場合、停止状態は特に問題なく永久に継続します。 ストリーミングレプリケーションの進行中は、WALレコードの受信が継続され、停止時間、WALの生成速度、ディスクの残存容量によりますが、ディスク溢れが発生する可能性があります。
PostgreSQLはデータベースのセッションに対して、それらのスナップショットを同期させることが可能です。
スナップショットは、そのスナップショットを使用しているトランザクションにどのデータが可視かを決定します。
同期スナップショットは、2つ以上のセッションにおいて、全く同じデータベース内容を見たい場合に必要となります。
単に2つのセッションが独立してそれぞれのトランザクションを開始するだけでは、第3のトランザクションのコミットが、2つのトランザクションのSTART TRANSACTION
の狭間で実行され、そのため一方のトランザクションではそのコミット結果が見え、他方では見えないという可能性が常にあります。
このような問題を解決するため、PostgreSQLではトランザクションが使用しているスナップショットをエクスポートできるようになっています。エクスポートしたトランザクションが開かれ続けている限り、他のトランザクションがそれをインポートすることができ、 そしてこれにより最初のトランザクションと正確に同じとなるデータベースの可視性を保証されます。ただし、これらの(スナップショットを共有している)トランザクションによって発生したデータベースへの変更は、コミットされていないトランザクションによる変更と同様に、(スナップショットを共有している)他のトランザクションには見えないままです。 つまり、既存データに対しては同期されますが、それら自身による変更については通常の振る舞いをします。
スナップショットは、表 9.88に示すpg_export_snapshot
関数を用いてエクスポートされ、SET TRANSACTIONコマンドを用いてインポートされます。
表9.88 スナップショット同期関数
関数 説明 |
---|
現在のトランザクションのスナップショットを保存し、それを識別する
必要ならばトランザクションは複数のスナップショットをエクスポートできます。
これは |
表 9.89に示す関数はレプリケーション機能を制御したり、情報を取得したりするためのものです。
基盤となっている機能の情報に関しては26.2.5、26.2.6、第49章を参照してください。
これらの関数のレプリケーションオリジンでの使用はスーパーユーザに限定されています。
これらの関数のレプリケーションスロットでの使用はスーパーユーザとREPLICATION
権限を持つユーザに限定されています。
これらの関数の多くには、レプリケーションプロトコルに等価なコマンドがあります。 52.4を参照してください。
9.27.3、9.27.4、9.27.5に書かれている関数もレプリケーションに関係するものです。
表9.89 レプリケーション管理関数
関数 説明 |
---|
|
|
出力プラグイン |
|
|
変更が最後に消費された時点から開始して、スロット |
変更が消費されないということを除いて、 |
変更は |
変更は |
|
指定した外部名でレプリケーション起点を作成し、割り当てられた内部IDを返します。 |
以前に作成されたレプリケーション起点を、それに関連するすべての再生の進捗も含めて削除します。 |
レプリケーション起点を名前で検索し、内部IDを返します。 相当するレプリケーション起点が見つからない場合はエラーが発生します。 |
現在のセッションに、指定の起点から再生中であると印を付け、再生の進捗が追跡できるようにします。
起点が選択されていない場合にのみ使うことができます。
元に戻すには |
|
現在のセッションでレプリケーション起点が選択されていれば真を返します。 |
現在のセッションで設定されたレプリケーション起点の再生位置を返します。
パラメータ |
現在のトランザクションに、指定のLSNおよびタイムスタンプでコミットしたトランザクションを再生中であると印をつけます。
事前にレプリケーション起点が |
|
指定したノードのレプリケーションの進捗を、指定の位置に設定します。 これは主に設定変更の後で初期位置や新しい位置を設定するときなどに役立ちます。 この関数を不注意に使うと、レプリケーションデータが一貫性を失うかもしれないことに注意して下さい。 |
指定したレプリケーション起点の再生位置を返します。
パラメータ |
論理デコードのメッセージを送出します
これは汎用的なメッセージをWALを通して論理デコードのプラグインに渡すのに使うことができます。
パラメータ |
表 9.90で示された関数はデータベースオブジェクトのディスク領域の使用状況を計算したり、使用結果の表示を補助します。
これらの関数はすべてバイト単位の大きさを返します。
関数に存在するオブジェクト以外のOIDが渡されるとNULL
が返ります。
表9.90 データベースオブジェクトサイズ関数
上記の関数において、テーブルやインデックスをregclass
引数として受け取って処理するものがありますが、この引数は単にpg_class
システムカタログにあるテーブルやインデックスのOIDです。
ただし、regclass
データ型が自動で入力変換を行うため、ユーザが手動で該当するOIDを調べる必要はありません。リテラル定数のようにシングルクオートで囲んだテーブル名を記述するだけです。
通常のSQL名に対する処理互換のため、テーブル名をダブルクオートで囲わない限り、テーブル名として入力された文字列は小文字に変換されます。
表 9.91 に示される関数は、データベースオブジェクトに関連する特定のディスクファイルを確認する際の手助けとなります。
表9.91 データベースオブジェクト位置関数
関数 説明 |
---|
指定されたリレーションに現在割り当てられている「ファイルノード」番号を返します。
ファイルノードは、リレーションに使用しているファイル名の基本要素です。(詳しくは68.1を参照して下さい。)
ほとんどのリレーションについては、結果は |
リレーションのファイルパス名全体(データベースクラスタのデータディレクトリ、 |
与えられたテーブル空間OIDとファイルノードに格納されているリレーションのOIDを返します。
これは本質的に |
表 9.92に照合順序の管理に使用される関数の一覧を示します。
表9.92 照合順序管理関数
関数 説明 |
---|
オペレーティングシステムに現在インストールされている照合順序オブジェクトの実際のバージョンを返します。
これが |
オペレーティングシステム上にあるすべてのロケールに基づき、システムカタログ |
表 9.93にパーティション化テーブルの構造に関する情報を提供する関数を示します。
表9.93 パーティション情報関数
たとえばパーティション化テーブルmeasurement
に含まれるデータの全体サイズを確認するには、次の問い合わせが利用できます。
SELECT pg_size_pretty(sum(pg_relation_size(relid))) AS total_size FROM pg_partition_tree('measurement');
表 9.94にインデックスの保守タスクに使用可能な関数を示します。 (これらの保守業務は通常自動バキュームが自動的に行うことに注意してください。これらの関数は特別な場合にのみ必要になります。) これらの関数はリカバリ中は実行できません。 これらの関数の使用はスーパーユーザと対象のインデックスの所有者に限定されます。
表9.94 Index Maintenance Functions
Function 説明 |
---|
指定されたBRINインデックスを検査してベーステーブル内のインデックスによって現在要約されていないページ範囲を探します。 そのような範囲があれば、テーブルのページをスキャンして新しい要約インデックスタプルを作成します。 インデックスに挿入された新しいページ範囲要約の数を返します。 |
指定のブロックを含むページ範囲が、まだ要約されていなければ、要約します。
これは |
指定のブロックを含むページ範囲が要約されていれば、それを含むページ範囲を要約するBRINインデックスタプルを削除します。 |
指定GINインデックスの「処理待ち」リストのエントリをメインのインデックスデータ構造に一括で移動します。
処理待ちリストから削除されたページ数を返します。
|
表 9.95で示されている関数はサーバをホスティングしているマシン上のファイルに対し、ネイティブのアクセスを提供します。
ユーザがpg_read_server_files
ロールを与えられていない限り、データベースクラスタディレクトリとlog_directory
に存在するファイルのみがアクセス可能です。
クラスタディレクトリ内のファイルに対して相対パスを、そしてログファイルに対してはlog_directory
構成設定に一致するパスを使用してください。
ユーザに対してEXECUTE権限をpg_read_file()
あるいは関連する関数に与えることは、サーバの上データベースサーバプロセスが読めるすべてのファイルを読めるようにすることになることに注意してください。これらの関数はデータベース内のすべての権限チェックをすり抜けます。
このことは、たとえばそのようなアクセス権を持つユーザは、認証情報が格納されたpg_authid
テーブルの中身を読むことができますし、同様にデータベース内のすべてのテーブルデータを読むことができるということを意味します。
ですからこれらの関数にアクセス権限を与えるのは慎重に考慮したほうが良いでしょう。
これらの関数の一部はオプションでmissing_ok
パラメータをとり、ファイルまたはディレクトリが存在しない場合の動作を指定できます。
true
の場合、関数はNULLを返すか、適切な場合には空の結果集合を返します。
false
の場合はエラーが発生します。
デフォルトはfalse
です。
表9.95 汎用ファイルアクセス関数
表 9.96に示す関数は勧告的ロックを管理します。 これらの関数の適切な使用方法についての詳細は、13.3.5を参照してください。
これらの関数はすべて単一の64ビットキー値か2つの32ビットキー値(これらのキー空間は重なり合わないことに注意してください)で識別されるアプリケーション定義のリソースをロックするために使うことを意図しています。
他のセッションがすでに同じリソース識別子とコンフリクトするロックを保持していたら、関数はリソースが利用可能になるまで待つか、その関数にとって適切ならばfalse
を結果として返します。
ロックは共有はあるいは排他のどちらも可能です。共有ロックは同じリソースに対して他の共有ロックとコンフリクトしません。排他ロックとだけコンフリクトします。
ロックはセッションレベル(ロックは解放されるまで保持するかセッションの終了まで保持します)あるいはトランザクションレベル(ロックは現在のトランザクションが終了するまで保持します。手動で解放する方法はありません)で取得できます。
複数のセッションレベルロック要求は積み重ねられます。これにより、同じリソース識別子が3回ロックされると、セッション終了前にそのリソースを解放するアンロック要求が3回発行されなければならなくなります。
表9.96 勧告的ロック用関数