表9-45は、実行時構成パラメータの問い合わせや変更に使用できる関数を示しています。
表 9-45. 構成設定の関数
| 名前 | 戻り値型 | 説明 |
|---|---|---|
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-46に示す関数は、制御用シグナルを他のサーバプロセスに送信します。これらの関数の使用はスーパーユーザのみに制限されています。
表 9-46. サーバシグナル送信関数
| 名前 | 戻り値型 | 説明 |
|---|---|---|
pg_cancel_backend(pid int)
| boolean | バックエンドの現在の問い合わせをキャンセル |
pg_reload_conf()
| boolean | サーバプロセスに構成ファイルの再読み込みをさせる |
pg_rotate_logfile()
| boolean | サーバログファイルを回転させる |
これらのぞれぞれの関数は成功の場合trueを返し、そうでない場合はfalseを返します。
pg_cancel_backendは問い合わせ取り消し（SIGINT）シグナルをプロセス識別子で特定されたバックエンドプロセスに送ります。動いているバックエンドのプロセス識別子はpg_stat_activityビューのprocpid列から、もしくはpsによりサーバ上のpostgresプロセスをリストすることで見つけられます。
pg_reload_confはSIGHUPシグナルをサーバに送り、その結果全てのサーバプロセスが構成ファイルを再読み込みすることになります。
pg_rotate_logfileはログファイルマネージャに即座に新規出力ファイルに切替えるよう信号を発します。これはログ取得に redirect_stderrが使用されている場合にのみ有効です。そうでない場合にはログファイルマネージャの子プロセスが存在しないからです。
表9-47に示す関数はオンラインバックアップの作成を補助するものです。 最初の3つの関数の使用はスーパーユーザに制限されています。
表 9-47. バックアップ制御関数
| 名前 | 戻り値型 | 説明 |
|---|---|---|
pg_start_backup(label text)
| 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は、ユーザが任意に定義したバックアップラベルである、パラメータを1つ受け付けます
（通常、格納に使用するバックアップダンプファイルにちなんだ名前が付けられます）。
この関数は、データベースクラスタのデータディレクトリにバックアップラベルファイルを書き出し、バックアップを始めるトランザクションログの位置をテキスト形式で返します。
ユーザはこの結果値に注意する必要はありません。
しかし、使用されることもありますのでこの値が提供されています。
postgres=# select pg_start_backup('label_goes_here');
pg_start_backup
-----------------
0/D4445B8
(1 row)
pg_stop_backupは、pg_start_backupで作成されたラベルファイルを削除し、代わりに、トランザクションログ格納領域にバックアップ履歴ファイルを作成します。
履歴ファイルにはpg_start_backupで付与されたラベル、バックアップのトランザクションログの位置の開始位置、終了位置、バックアップ開始時刻、終了時刻が含まれます。
戻り値は、バックアップの終了トランザクションログの位置です（これも同様に稀に使用されることがあります）。
終了位置を通知した後、現在のトランザクションログの挿入位置は自動的に、次のトランザクションログに進みます。
ですので、終了トランザクションログファイルをすぐにアーカイブし、バックアップを完了させることができます。
pg_switch_xlogは、次のトランザクションログファイルに移り、現在のファイルをアーカイブできるようにします。
（アーカイブを続けて使用することを前提とします。）
結果は、完了した現在のトランザクションログファイル内の終了トランザクションログの位置です。
前回のトランザクションログファイルの切り替えからトランザクションログに変化がなければ、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は、トランザクションログファイル名のみを取り出します。
指定したトランザクションログの位置が正確にトランザクションログファイルの境界であった場合、これらの両関数は前のトランザクションログファイルの名前を返します。
通常これは、トランザクションログファイルのアーカイブ動作では好まれる動作です。
前のファイルが現在のアーカイブで必要とする最後のファイルであるからです。
この関数の正しい使用方法については、項23.3を参照してください。
表9-48で示された関数はデータベースオブジェクトの実際のディスク領域を計算します。
表 9-48. データベースオブジェクト容量関数
| 名前 | 戻り値型 | 説明 |
|---|---|---|
pg_column_size(any) | int | 特定の値を格納するのに使用される（ひょっとしたら圧縮された）バイト数 |
pg_database_size(oid)
| bigint | 指定されたOIDを持つでデータベースで使用されるディスク領域 |
pg_database_size(name)
| bigint | 指定された名前を持つデータベースで使用されるディスク領域 |
pg_relation_size(oid)
| bigint | 指定されたOIDを持つテーブルもしくはインデックスで使用されるディスク領域 |
pg_relation_size(text)
| bigint | 指定された名前を持つテーブルもしくはインデックスで使用されるディスク領域。テーブル名はスキーマ名で条件付けられることもあります。 |
pg_size_pretty(bigint)
| text | バイト単位のサイズを指定サイズの可読性が高い書式に変換します。 |
pg_tablespace_size(oid)
| bigint | 指定されたOIDを持つテーブル空間で使用されるディスク領域 |
pg_tablespace_size(name)
| bigint | 指定された名前を持つテーブル空間で使用されるディスク領域 |
pg_total_relation_size(oid)
| bigint | 特定されたOIDを持つテーブルで使用されるディスク領域で、インデックスとtoastされたデータを含みます。 |
pg_total_relation_size(text)
| bigint | 特定された名前を持つテーブルで使用されるディスク領域で、インデックスとtoastされたデータを含みます。テーブル名はスキーマ名で条件付けられることもあります。 |
pg_column_sizeはどんな個別のデータ値を格納するのにも使用される領域を示します。
pg_database_sizeとpg_tablespace_sizeはデータベースまたはテーブル空間の名前またはOIDを受付け、そこで使用される総容量を返します。
pg_relation_sizeはOIDもしくはテーブル名、インデックスもしくはtoastテーブルを受け付け、バイト単位の容量を返します。
pg_size_prettyは、適切にkB、MB、GB、もしくはTB単位を使用して目で見た判るようにその他の関数の1つの結果を整形するのに使用することができます。
pg_total_relation_sizeは、テーブルまたはTOASTテーブルのOIDまたは名前を受け付け、データおよび関連するインデックス、TOASTテーブルの総容量をバイト単位で返します。
表9-49で示されている関数はサーバをホスティングしているマシン上のファイルに対し、本来的に適用するファイルアクセスを提供します。データベースクラスタディレクトリとlog_directoryに存在するファイルのみがアクセス可能です。クラスタディレクトリ内のファイルに対して相対パスを、そしてログファイルに対してはlog_directory構成設定に一致するパスを使用してください。
表 9-49. 汎用ファイルアクセス関数
| 名前 | 戻り値型 | 説明 |
|---|---|---|
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-50に示す関数は勧告的ロックを管理します。 これらの関数の適切な使用方法についての詳細は、項12.3.4を参照してください。
表 9-50. 勧告的ロック用関数
| 名前 | 戻り値の型 | 説明 |
|---|---|---|
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は、アプリケーションが定義したリソースをロックします。
これは、単一の64ビットキー値、または、2つの32ビットキー（この2つのキー空間は重複しないことに注意）によって識別されます。
他のセッションが同一リソースに対するロックを保持している場合、関数はリソースが利用可能になるまで待機します。
ロックは排他ロックです。
複数のロック要求が待ち状態になります。
ですので、同一リソースが3回ロックされた場合、他のセッションが使用できるように解放するためにはロック解除を3回行わなければなりません。
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_unlockは、事前に獲得した勧告的排他ロックを解放します。
ロックの解放に成功した場合、trueを返します。
ロックを実際に保持していない場合、falseを返し、さらに、SQL警告がサーバから発生します。
pg_advisory_unlock_sharedの動作はpg_advisory_unlockと同じですが、勧告的共有ロックを解放する点が異なります。
pg_advisory_unlock_allは、現在のセッションで保持する勧告的ロックを解放します。
（この関数は、クライアントとの接続が意図せずに切れた場合でも、セッション終了時に暗黙的に呼び出されます。）