システム管理関数

PostgreSQL 9.1.1文書
前のページ | 巻戻し | 第 9章関数と演算子 | 早送り | 次のページ

# 9.24. システム管理関数

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

表 9-54. 構成設定関数

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

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

    SELECT current_setting('datestyle');

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

`set_config`関数は、パラメータ`setting_name`を`new_value`に設定します。ただし、`is_local`が`true`の場合、新規値は現在のトランザクションにのみ適用されます。新規値を現在のセッションに適用する場合は、代わりに`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_reload_conf()`` | `boolean` | サーバプロセスに構成ファイルの再読み込みをさせる
``pg_rotate_logfile()`` | `boolean` | サーバログファイルを循環させる
``pg_terminate_backend(`pid` `int`)`` | `boolean` | バックエンドを終結

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

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

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

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

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

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

名前 | 戻り型 | 説明
--- | --- | ---
``pg_create_restore_point(`name` `text`)`` | `text` | リストア実行用に名前付けされたポイントを作成(スーパーユーザのみ実施可能です)
``pg_current_xlog_insert_location()`` | `text` | 現在のトランザクションログの挿入位置の取得
``pg_current_xlog_location()`` | `text` | 現在のトランザクションログの書き込み位置を取得
``pg_start_backup(`label` `text` [, `fast` `boolean` ])`` | `text` | オンラインバックアップの実行準備(スーパーユーザかレプリケーション用のロールでのみ実施可能です)
``pg_stop_backup()`` | `text` | オンラインバックアップの実行の終了(スーパーユーザかレプリケーション用のロールでのみ実施可能です)
``pg_switch_xlog()`` | `text` | 新しいトランザクションログファイルへの強制移行(スーパユーザのみ実施可能です)
``pg_xlogfile_name(`location` `text`)`` | `text` | トランザクションログの位置を表す文字列をファイル名に変換
``pg_xlogfile_name_offset(`location` `text`)`` | `text`, `integer` | トランザクションログの位置を表す文字列を、ファイル名とファイル内の10進のバイトオフセットに変換

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

`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レコードの位置の値がそのまま残ります。ストリーミングレプリケーションが無効、もしくは開始されていない場合、この関数はNULLを返します。
``pg_last_xlog_replay_location()`` | `text` | リカバリ中に再生された最後のトランザクションログの位置を取得します。リカバリが実施されている場合は、この値が単調に増加していくでしょう。リカバリが完了した場合は、リカバリ時に適用された最後のWALレコードの値がそのまま残ります。もしサーバがリカバリ無しで普通に起動された場合、この関数はNULLを返します。
``pg_last_xact_replay_timestamp()`` | `timestamp with time zone` | リカバリ中に再生された最後のトランザクションのタイムスタンプを取得します。このタイムスタンプは、プライマリにて該当するトランザクションがコミット、もしくはアボートされた際のトランザクションログが生成された時間です。もしリカバリ中に何のトランザクションも再生されていない場合、この関数はNULLを返します。もしリカバリが完了した場合、この関数はリカバリ中に再生した最後のトランザクションの時間を静的に示し続けます。サーバがリカバリ処理無しに開始された場合、この関数はNULLを返します。

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

表 9-58. リカバリ制御関数

名前 | 戻り型 | 説明
--- | --- | ---
``pg_is_xlog_replay_paused()`` | `bool` | リカバリが停止中であれば真を返す
``pg_xlog_replay_pause()`` | `void` | 即座にリカバリを停止する
``pg_xlog_replay_resume()`` | `void` | もしリカバリ停止中であれば再開する

リカバリ停止中は、それ以降のデータベースへの変更は適用されません。ホットスタンバイ側であれば、停止以降に発行されたSQLは、同じ一貫性を持ったデータベースのスナップショットを参照することができます。 そしてリカバリが再開されるまで、以降のSQLとプライマリへのSQLの衝突は発生しません。

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

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

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

名前 | 戻り型 | 説明
--- | --- | ---
``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'`）で使用されるディスク容量
``pg_relation_size(`relation` `regclass`)`` | `bigint` | `pg_relation_size(..., 'main')`の省略表現
``pg_size_pretty(`bigint`)`` | `text` | バイト単位のサイズを可読性が高いサイズ単位の書式に変換
``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_size`と`pg_tablespace_size`はデータベースまたはテーブル空間の名前またはOIDを受付け、そこで使用される総容量を返します。

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

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

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

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

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

名前 | 戻り型 | 説明
--- | --- | ---
``pg_relation_filenode(`relation` `regclass`)`` | `oid` | 指定されたリレーションのファイルノード番号
``pg_relation_filepath(`relation` `regclass`)`` | `text` | 指定されたリレーションのファイルパス

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

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

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

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

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

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

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

`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-62に示す関数は勧告的ロックを管理します。これらの関数の適切な使用方法についての詳細は、項13.3.4を参照してください。

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

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

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

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

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

`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`と同じですが、ロックが獲得できた場合は現在のトランザクションの終了時に自動的にロックが解放され、明示的なロックの解放はできません。

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

`pg_advisory_unlock_shared`の動作は`pg_advisory_unlock`と同じですが、セッションレベルの勧告的共有ロックを解放する点が異なります。

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

前のページ | ホーム | 次のページ
システム情報関数 | 上に戻る | トリガ関数